cc-history-viewer

A local, browser-based viewer for Claude Code session history. It reads the JSONL session logs that Claude Code writes to ~/.claude/projects/ and presents them in a fast, Anthropic-styled web UI — complete with dashboards, token/cost breakdowns, live message streaming, and per-session drill-down.

Everything runs on your machine. No accounts, no uploads, no telemetry.

Quick start

npx cc-history-viewer

That's it. The command:

1. Starts a local API server on port 3080,
2. Serves the web UI from the same port,
3. Opens http://localhost:3080 in your default browser.

Press Ctrl+C in the terminal to stop.

Requirements

• Node.js 18+
• Claude Code must have been used at least once, so that ~/.claude/projects/ exists with session logs.

Works on macOS, Linux, and Windows.

Features

Dashboard

• Token usage trend — daily line chart across a selectable date range (Today / Last 3 days / Last 7 days, or custom from–to).
• Usage distribution by project — donut chart showing the top projects by token volume.
• Per-project details table — breakdown of tokens & cost by model family (Opus / Sonnet / Haiku), split across input / output / cache-read / cache-creation, plus tool / skill / agent invocation counts, total tokens, and estimated USD cost.
• Cost is computed from the current public Anthropic pricing and displayed per model and in total.

Project History

• Project explorer sidebar — every project under ~/.claude/projects/ with session counts and "last activity" timestamps, infinite-scroll paginated sessions per project.
• Full session view — messages rendered as chat blocks (User / Assistant / System / Tool Use / Tool Result / Attachment), with Markdown-style code blocks and inline code.
• Tool use inspection — expand any tool call to see its JSON input and the tool result payload. Nested subagent (Agent tool) conversations are rendered inline under their parent call.
• Thinking blocks — expandable <thinking> sections for reasoning models.
• Attachments — file reads, diagnostics (with severity), hook outputs (success / non-blocking error / additional context), skill listings, deferred-tool and MCP-instruction deltas, nested memory — each with a tailored summary badge.
• Per-session usage bar — live-updating totals for input / output / cache-read / cache-creation tokens, total USD cost (with a per-model-family breakdown on hover), plus tool / skill / agent counters that break down calls by name and main-vs-subagent origin.
• Filters — filter messages by role (User / Assistant / System / Attachment), by content type (Tool Use), and by specific tool names. Shows only what you want to see.
• Full-text search — search across all messages in the current session.
• Message index panel — a right-side outline of every message in the session; click to jump, filter by keyword.

Live mode

• Click the Live button to open an overlay that streams the tail of the active session in real time.
• Active subagents are surfaced as their own live cards, each with message counts and running transcript.
• The main-session view polls every 1s, so messages appear as Claude Code writes them.

Appearance & language

• Light / dark theme toggle (persisted).
• English / 한국어 language toggle in the header (persisted). All UI strings, date/time formatting, and tooltip labels switch together.

Other niceties

• Collapsible left navigation.
• Keyboard-friendly, responsive layout.
• Anthropic-inspired typography and color palette.

CLI options

npx cc-history-viewer [options]

| Option | Description | | --- | --- | | -p, --port <number> | Port to listen on (default: 3080) | | --no-open | Don't launch the browser automatically | | -h, --help | Show help |

Examples:

# Run on a custom port
npx cc-history-viewer --port 4000

# Headless (no auto-browser) — useful over SSH with port forwarding
npx cc-history-viewer --no-open --port 4000

HTTP API

The same server exposes a small JSON API on the same port. Useful if you want to script over your own session data.

| Method | Path | Description | | --- | --- | --- | | GET | /api/projects | List all projects (id, name, path, session count, last activity) | | GET | /api/projects/:id/sessions?limit=&offset= | List sessions in a project | | GET | /api/projects/:id/sessions/:sessionId | Full session messages (JSONL parsed, subagents resolved) | | GET | /api/usage?from=YYYY-MM-DD&to=YYYY-MM-DD | Aggregate usage (by date, by project, by model) for the dashboard |

Privacy

• Everything runs locally. The server only binds to localhost.
• Session files are read-only — cc-history-viewer never modifies ~/.claude/projects/.
• No data is sent to any external service.

Running from source

git clone <repo>
cd cc-history-viewer/npx
npm install
npm run build
node dist/cli.cjs --port 3080

Development mode

Two terminals:

# Terminal 1 — API server on :3080
npm run dev:server

# Terminal 2 — Vite dev server on :5173 (proxies /api to :3080)
npm run dev:web

Open http://localhost:5173 for HMR.

Troubleshooting

• "Static assets not found" — run npm run build (only relevant when running from source).
• Port already in use — pass --port <other>.
• Browser didn't open — open the printed URL manually, or check --no-open isn't set.
• No projects listed — make sure ~/.claude/projects/ exists and contains JSONL files. Claude Code creates this directory the first time you run a session.

License

MIT © rudaks