Claude Lens

claude-lens

A local-first observability dashboard for Claude Code sessions — token usage, cost, cache performance, tool calls, and trends across all your projects.

The dashboard reads directly from your ~/.claude transcripts; nothing leaves your machine.

Presentation

https://foyzulkarim.github.io/claude-lens/claude-lens-v2-presentation.html#1

Dashboard

Quick start

This runs the app and opens it in your browser (defaults to ~/.claude for data, and picks a free port starting at 4128 if that one's busy).

To run straight from a branch or commit instead of the published release, use npx github:foyzulkarim/claude-lens[#ref].

Local setup

npm start runs the built CLI (dist/cli.js). If you're developing, use npm run dev instead (see below).

CLI options

- --port — preferred port (default 4128); if taken, the next free port is used.
- --no-open — don't auto-open a browser tab.
- --roots — one or more directories to scan for Claude Code project transcripts instead of the default ~/.claude/projects.

Development

Starts the backend (Fastify + /api/* + /ws) on port 4128 and the Vite dev server on 4129. Set CLAUDE_LENS_PORT_BASE=N to shift the whole block: backend N, Vite N+1, E2E N+2, Storybook N+3.

Other useful scripts:

How it works

- Ingest pipeline: discovers and tails your ~/.claude/projects//*.jsonl transcripts incrementally, parsing them into an in-memory store of API calls, turns, and sessions. A /ws connection pushes lightweight invalidation events so the UI refetches automatically as new activity comes in — no data over the socket, no manual refresh.
- Tiered accuracy: every metric carries a 🟢 observed, 🟡 estimated, or 🔴 locked label. The default install shows 🟡 everywhere; the "Cost capture" section below explains how to unlock 🟢.
- One process, one…