🔭 Claude Code Observatory

Local, privacy-first mission control for Claude Code

See your live agents, replay any session trace, and know exactly what every token costs — across every workspace, all on your own machine.

A self-hosted observability & cost dashboard for the Claude Code CLI — token usage, spend, budgets, live agent monitoring, and full transcript replay.

---

Claude Code writes a detailed JSONL transcript for every session under ~/.claude/projects. Observatory reads those files locally and turns them into a real-time dashboard: which agents are running right now, what they're doing, what they've cost, and where your tokens go. Nothing is uploaded — your code and prompts never leave the machine.

Why? Once you run Claude Code across many repos, worktrees, and parallel agents, the terminal can't tell you the whole story: Is something stuck? Which session is burning money? How much did this month cost? Which model and which workspace dominate my spend? Observatory answers all of that from data you already have on disk.

Table of contents

• Features
• Screenshots
• Quick start
• Try it with demo data
• Privacy
• Configuration
• How "live" is detected
• Notes on the data model
• Architecture
• Contributing
• License

Features

• 🟢 Now — a global live view of every workspace: active sessions as glowing agent cards (current activity, live token/cost counters, elapsed time), a Needs you lane (waiting on you · permission prompt · stalled tool · API error), a KPI strip (active agents, spend today/month, total tokens, cache savings), a recent-activity feed, and a spend sparkline.
• 🗂️ Workspaces — switch between projects (⌘K), with git worktrees grouped under their parent. Per-workspace totals, a sessions table, worktree breakdown, and monthly budget bars.
• 🎬 Session replay — open any session for the full transcript (user / thinking / tool calls + results / nested subagents) with per-turn token + cost chips, a files-touched panel, and a replay scrubber (play/pause, 0.5×–4×) that reveals the run over time with a cumulative burn readout.
• 💸 Tokenomics — cost over time, cost by model (donut) and by workspace (bars), token-mix area chart, cache-savings, cost-per-session, and your most expensive sessions. Export to CSV.
• 📊 Timeline — a concurrency Gantt of session lifespans: peak parallelism, overlaps, and how your day actually unfolded.
• 🩺 Anomaly detection — automatic flags for runaway tool loops, context-compaction storms, and tool-error spikes.
• 🗄️ Storage — disk usage per workspace/session, with safe cleanup of old transcripts.
• ⚙️ Settings — editable model pricing and per-workspace monthly budgets.

Screenshots

Workspaces	Tokenomics

Session replay	Timeline

Quick start

Requirements: Node.js 18+ and pnpm. You'll want some existing Claude Code history in ~/.claude/projects (or generate a demo dataset).

git clone https://github.com/vladsawyer/claude-code-observatory.git
cd claude-code-observatory
pnpm install
pnpm dev          # server on :5274, web on :5273

Open http://localhost:5273.

Other scripts:

pnpm build        # production web bundle
pnpm test         # server unit tests (parser + cost engine)

Try it with demo data

No Claude Code history yet — or want clean data for a screenshot? Generate a realistic synthetic ~/.claude/projects tree (fictional English projects, ~6 weeks of activity, live agents, subagents, and anomalies — all deterministic):

node scripts/seed-demo.mjs                                    # writes ./.demo
OBSERVATORY_CONFIG="$PWD/.demo/observatory.config.json" pnpm dev

The seed never touches your real ~/.claude/projects.

Privacy

Observatory is local-first by design:

• It only ever reads ~/.claude/projects/**/*.jsonl from your own disk.
• There is no network egress, no telemetry, no account — your code, prompts, and transcripts never leave the machine.
• The server and web app run entirely on localhost.

Configuration

Pricing, budgets, and the live-detection threshold live in observatory.config.json (created on first save, gitignored) and are editable from the Settings screen.

• Pricing is matched by longest model-id prefix (USD per million tokens). Cache multipliers: write-5m = 1.25× input, write-1h = 2× input, read = 0.1× input. Opus 4.x defaults to $5/$25 (the Opus 4.5+ tier); edit it if your runs were billed at the older $15/$75 tier.
• OBSERVATORY_PROJECTS_DIR overrides the transcripts directory.
• OBSERVATORY_SERVER_PORT overrides the API port (default 5274).
• OBSERVATORY_CONFIG points the server at an alternate config file (used by the demo seed).

How "live" is detected

A session's status comes from its file mtime + the tail of its events: running (fresh + generating/awaiting a tool) · idle (just finished, awaiting you) · stalled (a tool call never returned) · error (last event was an API error) · done (completed and quiet). The watcher pushes updates over SSE; time-based transitions (running → idle → done) are re-evaluated on a heartbeat.

Notes on the data model

• Token usage is deduplicated by message.id — one API message is split across several JSONL lines with identical usage, so naive summing triple-counts.
• Subagents (the Agent/Task tool) are stored as separate files under <session>/subagents/ and are nested under their parent in the transcript.
• <synthetic> model turns are counted in tokens but cost $0.
• Malformed / truncated trailing lines (common while a session is being written) are skipped and surfaced as a count.

Architecture

A small pnpm monorepo:

Package	Stack	Responsibility
server/	Node · Express · chokidar	Streams & parses .jsonl transcripts, caches aggregates by mtime+size, computes cost, and pushes live updates over SSE.
web/	Vite · React · TypeScript · Tailwind v4 · shadcn/ui · Recharts	The dashboard UI.
shared/	TypeScript	The contract (types) shared by both.

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, tests, and the PR workflow. Found a bug or have an idea? Open an issue.

License

MIT © Vlad Sawyer

---

_{A local dashboard for Claude Code — observability, token usage, cost tracking, budgets, live agent monitoring, and session replay. Built for the Anthropic Claude Code CLI.}