cc-session-explorer

Explores Claude Code and Codex session transcripts, plus Claude.ai exports, as context-token timelines, cost ledgers, and project breakdowns. The FastAPI dashboard, CLI tools, and MCP server are built on cc-session-core, which auto-detects both transcript providers behind one typed session model.

By default the explorer discovers Claude sessions under ~/.claude/projects and active plus archived Codex rollouts under ~/.codex/{sessions,archived_sessions}. Setting CC_SESSION_EXPLORER_HOME_DIR consistently rebases all three roots.

Layout

src/cc_session_explorer/   The Python package
  api/                     /timeline lens: context-token replay routes
  usage/                   /api lens: cost + token usage rollups
  ingest/                  Live transcript ingest (watchfiles -> SQLite)
  history/                 Historical ledger store + refresh CLI
  viz/                     Self-contained HTML reports (Sankey, cost ledger)
  mcp/                     Stdio MCP server over the same capabilities
  static/                  Built single-file SPA (output of frontend/app)
frontend/
  ui/                      @cc-session/dashboard-ui — the design-system components
  app/                     @cc-session/dashboard-app — the dashboard SPA (bundles ui from source)
systemd/                   Linux user services for the dashboard and the live watcher
launchd/                   macOS LaunchAgents for the dashboard and the live watcher
tests/

Persistent stores live under ~/.cc-session-explorer (transcripts.db, ledger.db) — the legacy data home, kept so existing installs and the systemd watcher carry over (see src/cc_session_explorer/paths.py).

Install

uv tool install cc-session-explorer

From a checkout:

uv sync --all-groups

Run

Command	What it does
cc-session-explorer	FastAPI dashboard: SPA at /, cost lens at /api/*, context lens at /timeline/*, on 127.0.0.1:9821
cc-session-watch	Live watcher; ingests Claude and active/archived Codex transcripts into SQLite
cc-session-history	Refreshes the historical usage ledger
cc-session-sankey	Per-session token-flow Sankey as a self-contained HTML page
cc-session-ledger	Directory-wide cost ledger as a self-contained HTML page
cc-session-explorer-mcp	Stdio MCP server exposing the explorer's capabilities as tools

Configuration comes from CC_SESSION_EXPLORER_* env vars (or a .env): CC_SESSION_EXPLORER_HOME_DIR (defaults to your home directory) and CC_SESSION_EXPLORER_EXPORT_PATH (a Claude.ai account export zip, only needed for the export timeline).

Context activity trace

Every session opens with an interactive context trace at the top of the dashboard. The line shows reconstructed active-context growth over time, with markers for compactions, subagent activity, context loads, errors, and other lifecycle events. Hovering inspects the nearest event; selecting a point loads an inclusive 30-minute activity window spanning 15 minutes before and after it, including prompts, responses, tool calls and results, hooks, context loads, compactions, and subagent events.

Trace measurements are labeled exact, estimated, or inferred. Exact compaction metadata is used when a provider records it; text contributions use the shared token estimator; inferred boundaries are shown when the transcript exposes a compaction summary without exact before/after counts. The graph models active context, so it intentionally does not mix in billed usage or prompt-cache token totals.

Route	What it returns
GET /timeline/session/{session_id}/trace	The complete provider-normalized context trace
GET /timeline/session/{session_id}/trace-window?center=…&minutes=30	Activity around a selected timestamp

MCP server

Register cc-session-explorer-mcp in a Claude Code .mcp.json:

{
  "mcpServers": {
    "cc-session-explorer": {
      "command": "cc-session-explorer-mcp"
    }
  }
}

Frontend

The SPA is built from frontend/app, which bundles the frontend/ui design system directly from source (a Vite alias — no publish step). frontend/ is an npm workspace (app + ui) so both share one hoisted node_modules — install once at the workspace root. The build emits one self-contained index.html into src/cc_session_explorer/static/, where the FastAPI app serves it as package data.

cd frontend && npm install
cd app && npm run build      # regenerates src/cc_session_explorer/static/index.html
npm run typecheck            # tsc --noEmit across the app (and, from frontend/ui, the design system)
npm run dev                  # dev server proxying to a running dashboard on :9821

Background services (optional)

bin/cc-session-explorer-startup installs and starts the dashboard and the transcript watcher as background services, dispatching to the right one for your OS. It's idempotent (safe to run on every plugin load, and picks up unit changes automatically) and is what the plugin's dashboard-uptime monitor calls on your behalf — running it by hand is only needed outside the Claude Code plugin context.

Linux: systemd

User units live in systemd/. The dashboard is socket-activated (cc-session-explorer.socket holds the port; cc-session-explorer.service starts on demand and exits after an idle period); the watcher is a plain always-on service. Manual install, if not running via the startup script above:

cp systemd/*.service systemd/*.socket ~/.config/systemd/user/
# edit ExecStart in each unit if you run from a checkout rather than `uv tool install`
systemctl --user daemon-reload
systemctl --user enable --now cc-session-explorer.socket cc-session-watch.service

macOS: launchd

LaunchAgents live in launchd/. launchd has no environment-variable-based socket-activation protocol a plain Python process can read (systemd's LISTEN_FDS has no macOS equivalent without private-API C bindings), so both the dashboard and the watcher run always-on here — the app already supports this directly (SystemdActivation degrades to a plain uvicorn.run() when no systemd env vars are present). Manual install, if not running via the startup script above:

mkdir -p ~/Library/LaunchAgents ~/Library/Logs/cc-session-explorer
sed -e "s|@PLUGIN_ROOT@|$(pwd)|g" -e "s|@HOME@|$HOME|g" \
  launchd/com.cc-session-explorer.dashboard.plist > ~/Library/LaunchAgents/com.cc-session-explorer.dashboard.plist
sed -e "s|@PLUGIN_ROOT@|$(pwd)|g" -e "s|@HOME@|$HOME|g" \
  launchd/com.cc-session-explorer.watch.plist > ~/Library/LaunchAgents/com.cc-session-explorer.watch.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.cc-session-explorer.dashboard.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.cc-session-explorer.watch.plist

Logs: ~/Library/Logs/cc-session-explorer/{dashboard,watch}.log.

Development

uv run pytest
uv run ruff check
uv run pyright

Publishing order: cc-session-core goes to PyPI first; this package depends on cc-session-core>=0.2.0,<0.3.0.

License

MIT