cc-lens: The Dashboard That Turns Claude Code Into a Readable Ledger
A local-first analytics tool that reconstructs cost, context, and session history from Claude Code’s raw logs, then presents the hidden shape of agent work without cloud telemetry.
- cc-lens is not just a dashboard for Claude Code. It is a local observability layer that turns opaque logs into a private ledger of work, cost, and session behavior.
- Its real trick is reconstruction, not visualization. The app reassembles sessions from raw JSONL files, then infers compaction, cache behavior, and latency from the trail left behind.
- The project’s architecture is shaped by a hard constraint: large local logs must stay fast to scan, so the reader streams files, caches by mtime, and avoids memory-heavy passes.
- By staying on the user’s machine, cc-lens makes AI agent analytics feel inspectable rather than surveilled.
Why a Claude Code dashboard needed to stay local
Claude Code already leaves useful evidence behind. The problem is that the evidence lives in local JSONL logs that are accurate, verbose, and miserable to read. cc-lens starts from a simple reversal: keep the data on the machine, bind to 127.0.0.1, and treat the filesystem as the source of truth.
Claude Code Lens (cc-lens) A real-time monitoring dashboard for Claude Code analytics.
That choice matters because it changes the product category. This is not cloud observability with an agent-shaped logo. It is a forensic tool for a local workflow, built for people who want answers without uploading their working habits somewhere else.
| Option | What you get | What you give up |
|---|---|---|
| Raw Claude Code logs | Exact data from the source | Readability, speed, and any sense of pattern |
| Cloud dashboards | Polished charts and central reporting | Privacy, local control, and often the raw context |
| cc-lens | Readable reconstruction from local logs | Nothing leaves the machine unless you choose Team Mode |
The hidden ledger inside ~/.claude/
The first real aha is that cc-lens does not merely summarize activity. It reconstructs an operational history from files that were never designed to be pleasant to inspect. Sessions, tokens, cache reads, cache writes, replayable turns, and cost estimates all come out of the same local trail.
How cc-lens reads thousands of sessions without choking
The technical heart of the project is in lib/claude-reader.ts. It uses a concurrency-capped map pool to scan a lot of files without running into file descriptor limits, then skips re-parsing sessions whose modification time has not changed. That is a practical design, not a clever one for its own sake. The data is local, but the log volume can still be brutal.
// The shape of the approach, simplified
for (const file of files) {
if (!mtimeChanged(file, sessionCache)) continue
const stream = createReadStream(file)
const rl = readline.createInterface({ input: stream })
for await (const line of rl) {
processJSONL(line)
}
}
The important detail is streaming. Instead of loading large session files into memory, cc-lens reads them line by line. That keeps the app responsive even when a session grows into something much larger than a normal CLI transcript.
Cost is the feature people will actually use
The project gets practical fast because it turns token activity into something closer to a bill. cc-lens combines Claude’s own stats-cache.json with session-derived calculations, then maps model identifiers to pricing tiers and accounts for cache reads and writes. The result is not exact accounting, but it is a useful approximation of where the money goes.
| Signal | What cc-lens adds | Why it matters |
|---|---|---|
| Prompt and completion tokens | Session-level reconstruction | You can see which work was expensive |
| Cache reads and writes | Separate cost treatment | Prompt caching becomes visible instead of implied |
| Session totals | Merged with Claude’s stats cache | The dashboard stays fresher than a plain log viewer |
That is why the product feels less like analytics theater and more like a utility bill. Most users do not wake up wanting token archaeology. They want to know whether the last stretch of agent work was efficient, wasteful, or just unusually busy.
Replay changes the product from dashboard to microscope
Replay is where cc-lens stops being a summary layer and becomes a diagnostic tool. The parser tracks compaction events, sidechains, parent UUIDs, and turn duration, then rebuilds a chat-like sequence that makes long-running agent behavior easier to inspect. You do not just see what happened. You see where the session bent under its own length.
- Compaction boundaries show when context was compressed.
- Sidechains reveal when the session branched and resumed.
- Latency metadata shows where the agent slowed down.
- Cache signals explain which parts of the run were cheaper than they looked.
That is the deeper product idea. Once you can replay the session, you can ask better questions about memory pressure, turn latency, and the real shape of the work.
Team Mode extends the same idea to shared reporting
The team update keeps the original philosophy intact. It still favors local data, redaction, and minimal infrastructure, but now it can aggregate snapshots through a shared folder or a hub. The point is not to become a surveillance layer for a company. The point is to let a team compare usage without forcing everything into a SaaS account.
That makes cc-lens feel like a second-act product. The solo developer gets personal observability first. The team gets a controlled way to share only what they need.
Where cc-lens fits in the broader toolchain
cc-lens occupies a narrow but useful middle ground. Raw logs are faithful but unreadable. Cloud dashboards are readable but external. Generic CLI wrappers can tell you whether something is happening, but not how the session is evolving. cc-lens sits between them: private, reconstruction-heavy, and much closer to the behavior of the agent than a simple status line.
| Tool type | Strength | Blind spot |
|---|---|---|
| Raw logs | Exact source data | No narrative or structure |
| Cloud analytics | Polished reporting | Off-machine by default |
| Generic CLI trackers | Fast status checks | Little historical depth |
| cc-lens | Local reconstruction and replay | Requires local log access |
It is not trying to replace Claude Code. It is trying to make Claude Code inspectable.
The bigger idea: local-first observability for AI agents
cc-lens matters because it points to a category. If AI coding agents are going to live in daily workflows, then the best tools around them may be the ones that sit next to the work, not above it. That is the real lesson here. The future of agent observability may look less like a cloud platform and more like a private rear-view mirror.
