CodeSesh

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

You've been coding with AI agents — Claude Code, Cursor, Kimi, Codex, OpenCode — and the conversations are scattered everywhere on your filesystem. Context is lost. Cost is invisible. History is buried.

CodeSesh fixes that. It scans your local machine, finds every AI agent session, and surfaces them in a unified, beautiful Web UI. Think of it as a time machine for your AI-assisted development workflow.

---

Why CodeSesh?

Modern developers work with multiple AI coding agents simultaneously. Each tool stores its session history in its own proprietary format, in its own hidden directory. There's no way to search across them, compare costs, or revisit that brilliant conversation you had three weeks ago.

CodeSesh believes your session history belongs to you — and you deserve to see it all in one place.

What you get:

• Unified Timeline — Browse sessions across all your AI agents in a single, searchable interface
• Structured Global Search — Search titles, messages, tool output, and file paths with filters for agent, project, smart tag, tool, file activity, and cost
• Dashboard & Activity Trends — Track daily activity, agent distribution, recent sessions, latest activity, token usage, model usage, smart tags, and cost at a glance
• Project Browse Mode — Open a dedicated projects view with project-level metrics, sessions, and cross-agent drill-down
• Project-Aware Session Tree — Group sessions by repository or project identity across every supported agent
• Smart Tags — Automatically label sessions such as bugfix, refactoring, feature work, testing, docs, planning, git operations, build/deploy, and exploration
• Bookmarks — Save important sessions and keep them visible from the dashboard
• Full Conversation Replay — Read every message, tool call, and reasoning step exactly as it happened
• File Activity Index — Jump to files that were read, edited, created, deleted, or moved, and search sessions by file activity
• Keyboard Navigation — Move through views, focus search, and open shortcuts without leaving the keyboard
• Agent Resume Commands — Copy worktree-aware resume commands from supported agent session details
• Cost & Token Visibility — See token totals, cache tokens, recorded costs, and model-based cost estimates
• SQLite Cache, Migrations & Search Index — Restore session lists quickly, upgrade local schemas safely, and reuse the same local store for search
• Zero Configuration — Just run it. CodeSesh auto-discovers everything on your filesystem
• 100% Local & Private — Your data stays on your machine. No accounts, no cloud sync, no cloud telemetry
• Live Refresh — File changes are picked up automatically, and the UI stays in sync without a restart

---

Supported Agents

Agent	Status
Claude Code	Supported
Cursor	Supported
Kimi	Supported
Codex	Supported
OpenCode	Supported

More agents coming soon. Adding a new one is a single file.

---

Quick Start

Prerequisites

• Node.js 18+ for the published CLI
• Node.js 24 and pnpm 11.5.1 for building from source

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.

Build from Source

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

pnpm install
pnpm build
pnpm serve

The local server uses packages/cli/dist/index.js and opens the same Web UI.

---

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 days
npx codesesh --days 3

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

# Show sessions active 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)

# Dump all session data as JSON instead of starting the server
npx codesesh --json
npx codesesh -j

CLI Options Reference

Flag	Alias	Default	Description
--port	-p	4521	HTTP server starting port; falls back to the next available port if busy
--days	-d	7	Only include sessions active in the last N 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 after this date YYYY-MM-DD (overrides --days)
--to	—	—	Sessions active before this date YYYY-MM-DD
--session	-s	—	Directly open a session (agent://session-id)
--json	-j	false	Output JSON and exit (no server)
--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

---

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 distribution, 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 and filter by agent or smart tag.
5. 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.
6. Smart Tags & Bookmarks — Spot session intent quickly, pin sessions you want to revisit, and manage them from the dashboard or session views.
7. 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.
8. Keyboard Shortcuts — Use the shortcuts panel to navigate sessions, open global search, focus search, and move between grouped content faster.
9. 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 Pages
pnpm --filter @codesesh/www deploy:cf

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

Dev Workflow (watch mode)

Open two terminals:

# Terminal 1 — watch & recompile on source changes
pnpm dev

# Terminal 2 — auto-restart server when dist changes
pnpm serve

# Or pass CLI flags directly:
node --watch packages/cli/dist/index.js --cwd . --days 3

Project Structure

packages/core       Core library (framework-agnostic)
  agents/           Agent adapters (one file per agent)
  discovery/        Session path resolution & file scanning
  types/            Shared TypeScript types
  utils/            Utility functions

packages/cli        CLI entry point & HTTP server
  src/commands/     CLI subcommands
  src/api/          Hono route handlers

apps/web            React frontend
  src/components/   UI components
  src/lib/          API client & utilities

Extending

Adding support for a new AI agent takes one file:

1. Create packages/core/src/agents/youragent.ts implementing BaseAgent
2. Register it in packages/core/src/agents/register.ts

No other files need to change. The agent immediately appears in the UI.