CodeSesh

One place to see every AI coding session you've ever had.

Website · Find Claude Code and Codex history · Installation guide

You use several AI coding agents, and their sessions are scattered across your filesystem. CodeSesh finds them and puts them in one Web UI.

---

Why CodeSesh?

Each AI coding agent keeps its history in its own format and hidden directory. You can't search across them, compare costs, or get back to a conversation from three weeks ago.

CodeSesh does three jobs:

Find

• Structured search — Search titles, messages, tool output, and file paths. Filter by agent, project, smart tag, tool, file activity, and cost. Chinese substrings match, and message results open at the first hit
• Projects — Group sessions by repository identity across agents, with subagent sessions nested under their parent
• File activity — Jump to files that were read, edited, created, deleted, or moved, and find the sessions that touched them
• Bookmarks and aliases — Keep important sessions on the dashboard and give them names that carry through search and activity views
• Time ranges — Switch between rolling presets, all history, or a custom range without restarting

See

• Dashboard — Daily activity, agent distribution, model token shares, smart tags, and latest activity for the selected range
• Tokens and cost — Token totals, cache tokens, recorded costs, and model-based estimates, always labeled as recorded or estimated
• Smart tags — Sessions labeled as bugfix, refactoring, feature work, testing, docs, planning, git, build/deploy, or exploration
• Session receipts — Usage by model and token category, exportable as a PNG

Reuse

• Full replay — Messages, tool calls, and reasoning, paged or complete, with your reading position kept
• Copy as Markdown — Take a whole conversation into a new prompt, issue, or note
• Resume commands — Copy worktree-aware resume commands for supported agents, with the source machine shown

Under the hood: zero configuration, local by default (no account or telemetry), live refresh, an SQLite cache with resumable history indexing, keyboard navigation, light and dark themes, and an English, Simplified Chinese, and Japanese UI.

---

Multiple machines with Hub and Worker

Run codesesh hub for a query-only Web UI and pair an independent codesesh worker on each machine you want to collect from. The source-node panel guides pairing, shows collection health, and manages rescans and Worker replacement. User-level background service commands are available on macOS, Linux, and Windows. See the Hub/Worker guide for setup, migration, and recovery.

Supported Agents

Agent	Status	Usage	Recorded cost	Tool results	Reasoning	Session tree	Resume
Claude Code	Supported	✓	—	✓	✓	✓	✓
Cursor	Supported	◐	—	✓	—	—	—
Kimi-Cli	Supported	◐	—	✓	✓	—	✓
Kimi-Code	Supported	✓	—	✓	✓	—	✓
Codex	Supported	✓	—	✓	✓	✓	✓
Grok	Supported	✓	✓	✓	✓	✓	✓
Pi	Supported	✓	✓	✓	✓	—	✓
OpenCode	Supported	✓	✓	✓	✓	✓	✓
ZCode	Supported	◐	✓	✓	✓	✓	—
MiniMax Code	Supported	✓	✓	✓	✓	✓	✓
DSH	Supported	✓	—	✓	✓	✓	—
DeepChat	Supported	✓	—	✓	✓	✓	—
Cherry Studio	Supported	✓	✓	✓	✓	—	—
Antigravity CLI	Partial support	—	—	—	—	✓	—

✓ available · ◐ partial (for example, input and output tokens only) · — not available. Without a recorded cost, CodeSesh estimates cost from model prices.

Antigravity CLI supports local SQLite conversations, titles, workspace metadata, and tool calls. Tool outcomes and usage remain unknown. IDE .pb histories are not supported. See the compatibility notes.

OpenCode supports V1 SQLite history and the V2 2.0.15 schema. Set OPENCODE_DB to select a custom database (relative to XDG_DATA_HOME/opencode, or ~/.local/share/opencode by default). V2 migration must finish before scanning; session totals prevent copied fork history from being counted again. See the compatibility design for supported messages and validation limits.

MiniMax Code supports CLI 0.4.12 v2/sqlite/runtime-state.sqlite, including session trees, reasoning, tools, and usage. Discovery selects the first database under ~/.minimax or ~/.minimax-code; MINIMAX_DATA_DIR takes precedence over MAVIS_DATA_DIR. Refresh detects updates and removals as well as new messages. Media retains available references; legacy ledger layouts and Desktop compatibility are unverified. See the integration design.

DeepChat supports the current unencrypted app_db/agent.db, including native and ACP sessions. Set DEEPCHAT_USER_DATA_DIR to override its user data directory. Legacy chat.db, SQLCipher-encrypted databases, and resume commands are not supported. ACP sessions are counted under DeepChat; records also discovered from an external agent are not deduplicated.

Cherry Studio supports 2.x Data/cherrystudio.sqlite: Agent sessions (Claude Code, Pi, DSH) and the selected branch of assistant chats. Chat messages and usage follow that branch; alternative replies are excluded. Chats are grouped under the user data directory, while Agent sessions retain their workspace. Set CHERRYSTUDIO_USER_DATA_DIR for custom or portable data directories. Message usage is counted once from Cherry's stored statistics. USD costs are preserved; other currencies use USD model estimates when pricing is available. Legacy 1.x agents.db, independent subagent session trees, and resume commands are not supported. Sessions are attributed to Cherry Studio without cross-agent deduplication.

More agents coming soon. See the extension checklist.

---

Quick Start

Prerequisites

• Node.js 22+ for the npm launcher; the standalone native executable does not require Node. Source builds use Node 24 from mise.toml and Rust from rust-toolchain.toml

• pnpm 12.4.2 for building from source

Native targets are macOS arm64/x64, Linux x64 GNU with glibc 2.35 or later, and Windows x64. Linux CI and release validation use Ubuntu 22.04. Older glibc, musl, and Linux arm64 are not supported by this release.

Install & Run

# Run the published CLI
npx codesesh

Your browser will open at http://localhost:4521 with all your sessions ready to browse. If that default port is busy, CodeSesh automatically tries the next available port.

Native installation (no Node.js required)

macOS / Linux x64 (glibc 2.35+):

curl -sSfL https://codesesh.xingkaixin.me/install.sh | sh
codesesh

The default directory is ~/.local/bin. Run the installer again to update. To select a version or directory:

curl -sSfL https://codesesh.xingkaixin.me/install.sh | CODESESH_VERSION=1.1.1 CODESESH_INSTALL_DIR="$HOME/.local/bin" sh

macOS (Homebrew):

brew install xingkaixin/tap/codesesh
codesesh
# Update
brew upgrade codesesh

Windows x64 (install Scoop first):

scoop bucket add xingkaixin https://github.com/xingkaixin/scoop-bucket
scoop install xingkaixin/codesesh
codesesh
# Update
scoop update codesesh

Stop CodeSesh before updating, then restart it. Each channel manages its own installation; check PATH if you have installed through multiple channels. The shell installer does not edit shell configuration or overwrite symlinks. Uninstall with brew uninstall codesesh, scoop uninstall codesesh, or remove codesesh from the shell installer's directory. User configuration and indexes are retained.

Build from Source

git clone https://github.com/xingkaixin/codesesh.git
cd codesesh

pnpm install
pnpm build
pnpm serve

The local server runs the Rust executable with its embedded Web UI. Build the Web assets before compiling a release executable; pnpm build coordinates the repository build.

---

Usage

Basic Usage

# Start the web UI (default port 4521)
npx codesesh

# Choose a custom starting port
npx codesesh --port 8080
npx codesesh -p 8080

# Start without auto-opening the browser
npx codesesh --no-open

Filter by Time

# Only show sessions active in the last 3 local calendar days
npx codesesh --days 3

# Show all sessions (no time limit)
npx codesesh --days 0

# Show sessions active on or after a specific date (overrides --days)
npx codesesh --from 2025-01-01

# Show sessions within a date range
npx codesesh --from 2025-01-01 --to 2025-03-31

Filter by Directory

# Only show sessions from the current project
npx codesesh --cwd .

# Only show sessions from a specific path
npx codesesh --cwd /Users/you/projects/my-app

Filter by Agent

# Only show Claude Code sessions
npx codesesh --agent claudecode

# Only show Cursor sessions
npx codesesh --agent cursor

# Multiple agents, comma-separated
npx codesesh --agent claudecode,cursor

Open a Specific Session

# Jump directly to a session by agent and ID
npx codesesh --session claudecode://3b0e4ead-eba9-43e7-9fac-b30647e189f8

JSON Output (for scripting)

# Print the session index as JSON instead of starting the server
npx codesesh --json
npx codesesh -j

The output is an index, not an archive: an agents summary and a sessions array of session metadata — reference, title, directory, project identity, timestamps, token/cost stats and smart tags. It does not include messages, tool calls, reasoning or file activity, so it is not a backup of your history. Session content stays in each agent's own data directory.

CLI Options Reference

Flag	Alias	Default	Description
--port	-p	4521	HTTP server starting port; falls back to the next available port if busy
--host	—	127.0.0.1	HTTP server bind address; default is local-only, set explicitly (e.g. 0.0.0.0) to expose on the network
--auth	—	false	Require an API access token for local access
--remote-access	—	false	Allow network or reverse-proxy exposure; always require an API access token
--tls-cert	—	—	Path to a TLS certificate; serves remote access over HTTPS
--tls-key	—	—	Path to the private key matching --tls-cert
--trust-proxy	—	false	A reverse proxy in front of CodeSesh terminates TLS
--public-url	—	—	Public HTTPS origin used with --trust-proxy for startup links
--days	-d	7	Only include sessions active in the last N local calendar days (0 = all time)
--cwd	—	—	Filter to sessions from a project directory (. = current dir)
--agent	-a	all	Filter to specific agent(s), comma-separated
--from	—	—	Sessions active on or after this date YYYY-MM-DD (overrides --days)
--to	—	—	Sessions active on or before this date YYYY-MM-DD
--session	-s	—	Directly open a session (agent://session-id)
--json	-j	false	Print the session index as JSON and exit (metadata only, no messages)
--no-open	—	false	Don't auto-open the browser
--trace	—	false	Print performance trace logs
--cache	—	true	Use cached scan results when available
--clear-cache	—	false	Clear scan cache before starting
-v	—	—	Print version number
-h / --help	—	—	Show help

Local access does not require an API token by default. Use --auth to enable token authentication on the loopback listener. Without it, other users and processes on the same machine can access indexed sessions and write APIs. Host and cross-origin request checks remain enabled.

--remote-access always enables token authentication, including when the backend listens on loopback behind a reverse proxy. Non-loopback binding requires --remote-access. A trusted proxy also requires a loopback --host and an HTTPS --public-url. When authentication is enabled, each server process generates a fresh token and includes it in the startup URL. Treat that URL as a password: do not share or persist it. Worker pairing and upload credentials are unchanged.

A token proves who is asking; it does not hide the answer. Without TLS the token and the full session content travel the network in the clear, and the token in the URL can end up in reverse proxy access logs. Pick one of:

# CodeSesh terminates TLS
npx codesesh --host 0.0.0.0 --remote-access --tls-cert ./cert.pem --tls-key ./key.pem

# A reverse proxy terminates TLS; CodeSesh stays bound to loopback
npx codesesh --host 127.0.0.1 --remote-access --trust-proxy \
  --public-url https://codesesh.example.com

--trust-proxy requires every API request to arrive with X-Forwarded-Proto: https and refuses it otherwise. That header validates the proxy's forwarding configuration; it cannot prove which client sent it. CodeSesh therefore enforces a loopback backend so network clients cannot reach the HTTP listener directly. The printed and automatically opened startup URL uses --public-url.

Using --remote-access without either TLS option still starts on a non-loopback address and prints a warning that the transport is unencrypted.

Model estimates use models.dev, cached in ~/.codesesh/models-dev-pricing.json for one hour. Startup reuses valid cached prices; missing or expired prices are refreshed before scanning, with a 10-second timeout. Network failures fall back to stale cached or bundled prices. Subsequent scans recalculate previously unpriced sessions when their model prices become available.

---

Web UI Walkthrough

Once CodeSesh is running, here's what you'll find:

1. Dashboard — Start from a summary view with total sessions, total messages, total tokens, latest activity, daily activity, agent distribution, model token shares for the selected date range, token trends, smart tags, bookmarks, and recent sessions.
2. Structured Global Search — Query titles, messages, tool output, and file paths, then narrow results by agent, project, tag, tool, file activity, or cost.
3. Projects — Browse project-level totals, recent activity, agent mix, scoped dashboards, and sessions for a single repository or project identity.
4. Session Tree Sidebar — Browse sessions grouped by agent or project identity, with nested subagent sessions kept under their parents, and filter by agent or smart tag.
5. Time Range Control — Filter the entire Web UI with rolling presets, all history, or a custom date range.
6. Session List — Browse your sessions sorted by most recent. Each card shows the session title, working directory, message count, and total cost at a glance.
7. Session Aliases, Smart Tags & Bookmarks — Rename sessions locally, spot their intent quickly, and pin the ones you want to revisit.
8. Session Detail — Click any session to open a full replay with a receipt-style summary, user messages, assistant responses, tool invocations, reasoning steps, model labels, tracked file activity, and agent resume command copy.
9. Keyboard Shortcuts — Use the shortcuts panel to navigate sessions, open global search, focus search, and move between grouped content faster.
10. Live Updates — New or changed local sessions are reflected automatically while the server is running.

---

Development

# Build all packages
pnpm build

# Clean build artifacts
pnpm clean

# Lint
pnpm lint
pnpm lint:fix

# Format
pnpm format
pnpm format:check

# Test
pnpm test
pnpm test:watch
pnpm test:coverage

# Performance benchmark
pnpm bench:perf

# Deploy landing page to Cloudflare Workers
pnpm deploy:www

Rust backend tests run through Cargo. test:coverage measures the TypeScript contract and Web code covered by Vitest; it does not measure Rust coverage. Playwright exercises the browser against the native server. Backend process contracts and the fixed Node reference provide separate compatibility checks.

The landing page deploys to the codesesh Worker at codesesh.xingkaixin.me. Use the globally installed cf CLI managed by mise, already authenticated with Cloudflare; do not add cf or Wrangler as a project dependency. pnpm deploy:www builds the contract and Astro site, prepares .cloudflare/output/v0/, then runs cf deploy --prebuilt. This avoids automatic configuration installing build tools. The output format is currently cf's v0 beta format, verified with cf 1.0.0-beta.12. To validate without uploading, run pnpm --filter @codesesh/contract build, pnpm --filter @codesesh/www build:cf, then (cd apps/www && cf deploy --prebuilt --dry-run).

The preparation script generates _headers with exact paths for built /_astro/ assets and caches them for one year. Workers applies wildcard headers to 404s too, so exact paths keep missing assets out of that cache policy. HTML and unversioned files use the Workers defaults. Finder metadata is excluded from deployment. The deployment explicitly uses trailing-slash URLs and 404-page handling with apps/www/public/404.html, so missing assets return 404 instead of the homepage. Analytics uses Umami only; keep Cloudflare Web Analytics injection disabled.

The Pages migration is complete. The retired Pages project can be removed. Only the production custom domain serves the site; workers.dev and version preview URLs are explicitly disabled in the generated deployment configuration.

Reproduce Required CI Checks

.github/workflows/ci.yml is the source of truth. CI runs Rust and frontend checks, browser contracts, and native artifact validation. The following commands list the workflow’s declared checks. Run them in their job order; rebuild Web after pnpm clean. The packaging line containing ${{ matrix.* }} is a CI template: locally use pnpm package:artifact. verify-set needs artifacts collected from all four runners:

pnpm install --frozen-lockfile
node scripts/check-quality-task-coverage.mjs
pnpm build:web
pnpm lint
pnpm format:check
pnpm typecheck
pnpm typecheck:e2e
node scripts/release-preflight.mjs
node scripts/check-docs-paths.mjs
node scripts/check-docs-facts.mjs
pnpm clean
pnpm test:coverage
pnpm --filter @codesesh/web test:bundle
pnpm generate:rust-contract
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
pnpm test:rust:platform
pnpm build:rust
node --test scripts/rust/packaging.test.mjs
node --test scripts/rust/publish.test.mjs
pnpm test:backend
pnpm perf:check
pnpm exec playwright install --with-deps chromium
pnpm test:e2e
node scripts/rust/pack.mjs ${{ matrix.target }} target/release/${{ matrix.executable }}
node scripts/rust/smoke.mjs --contracts
node scripts/rust/verify-set.mjs

A local run covers the host platform. Native packaging targets macOS arm64/x64, Linux x64 GNU (glibc 2.35+), and Windows x64; each target still needs its own runner and installed-package checks. See the packaging guide.

Performance Benchmark

# Warm-cache benchmark against an automatically selected representative session
pnpm bench:perf -- --days 0 --iterations 3

# Cold-start benchmark with React render profiling enabled
pnpm bench:perf -- --cold --react-profile --target heaviest --navigation direct

CI and release boundaries

Frontend, contract, coverage, documentation, and the complete Rust suite run once on Linux / Node 24. All four native targets compile and run platform-dependent checks: filesystem discovery, migration, watchers, SQLite persistence, native services, process lifecycle, and packaging. macOS and Windows use pnpm test:rust:platform; npm installation is verified on Node 22.0.0 and Node 24 for each target. See the test policy for the platform selection. Legacy Node differential suites have been retired. The pinned Node package remains available only for manual performance benchmarks.

Version 1.1.0 prepares the native Rust backend for release. Version and changelog updates do not publish packages. The Release workflow only runs for v* tags; publication requires separate authorization and completion of the release checklist.

Dev Workflow

Build and start the native app:

pnpm dev

After backend or embedded Web changes, rebuild and restart the process. pnpm serve starts an existing build. To pass arguments directly after a build:

./target/release/codesesh --cwd . --days 3

The separate Astro site supports pnpm dev:www.

Project Structure

crates/codesesh-core/src/agents/       Agent adapters and source parsing
crates/codesesh-core/src/discovery/    Discovery, incremental scans, and backfill
crates/codesesh-core/src/runtime/      Watcher, single writer, and publication
crates/codesesh-core/src/storage/      SQLite schema, migrations, messages, and FTS
crates/codesesh-core/src/pricing/      Model prices and fixed pricing generations
crates/codesesh-core/src/analytics/    Dashboard and project aggregation
crates/codesesh-core/src/search/       Structured search and file activity
crates/codesesh-core/src/state/        Bookmarks and aliases
crates/codesesh-cli/src/               Clap CLI, Axum HTTP, embedded Web, and logs
crates/codesesh-cli/npm/               Thin npm launcher
packages/contract/src/                Browser-safe contracts and pure logic
packages/contract/src/generated/      Rust-generated TypeScript wire types
apps/web/                            React application
apps/www/                            Astro product site
scripts/rust/                        Native build, packaging, and benchmarks

docs/architecture.md describes how a scan flows through these; docs/design/sqlite-storage.md covers the cache and search index; docs/engineering/performance.md describes what guards performance and where to add a new guard.

Extending

Agent source parsing and browser presentation have explicit registration points:

1. Add a Rust adapter under crates/codesesh-core/src/agents/ and register its scan entry.
2. Add default paths and environment overrides in crates/codesesh-core/src/discovery/paths.rs.
3. Edit public metadata and presentation capabilities in crates/codesesh-core/src/agents/catalog.json, then run pnpm generate:rust-contract. The browser catalog is generated from this single source.
4. Add its SVG to apps/web/public/icon/agent/ and apps/www/public/icon/agent/.
5. Register any custom tool display in apps/web/src/components/session-detail/tool-strategy/.

Use source-format fixtures and process contracts to verify messages, usage, tools, and incremental updates. Registration checks cover icons, resume declarations, and custom tool strategies.

Local databases, model prices, and logs now default to ~/.codesesh/ (%USERPROFILE%\.codesesh\ on Windows). On the first migration, stop older CodeSesh instances and confirm the terminal prompt. For non-interactive runs, pass --migrate-data after stopping older instances. Migration verifies data before removing old files and reports every retained path. Existing CODESESH_STATE_DIR and CODESESH_LOG_DIR overrides remain supported. See data migration.