Claude Code Lens (cc-lens)
Local analytics dashboard for Claude Code. No cloud, no telemetry, no API key, just your ~/.claude/ data, visualized.
npx cc-lens
The CLI finds a free local port, starts the dashboard, and opens it in your browser.
[!NOTE] cc-lens 0.4.0 is out
Adds Insights, budgets, team adoption, terminal digest, Wrapped, and expanded project docs.
Quick Start
Run directly with npx:
npx cc-lens
On first run, cc-lens prepares a small runtime cache in ~/.cc-lens/. After that, launches are faster.
What You Can See
| OverviewTrack sessions, messages, tokens, cost, storage, trends, models, peak hours, projects, and recent activity. | SessionsSearch sessions, replay JSONL conversations, inspect Markdown replies, tool calls, costs, tokens, and compactions. |
| CostsReview estimated spend, cache savings, project costs, model breakdowns, token usage, and pricing references. | InsightsFind cache, model, compaction, plan-fit, budget, and savings opportunities from local usage patterns. |
| ProjectsBrowse projects by sessions, duration, spend, languages, branches, MCP usage, agents, and top tools. | Project TrendsAnalyze project sessions, spend, language mix, branch activity, model usage, tools, and activity over time. |
| Tools & FeaturesCompare tool rankings, categories, skill (slash-command) usage, MCP servers, feature adoption, errors, versions, and git branch usage. | ActivityView activity calendars, streaks, active days, peak hours, day-of-week patterns, and usage consistency. |
| TasksBrowse Claude Code todos with search, status filters, task metadata, project context, and local file provenance. | WorkspaceInspect workspace state, memory, settings, installed skills, plugins, MCP servers, and local storage usage. |
| WrappedCreate a yearly card with sessions, usage, spend, favorite tools, active projects, and local highlights. | Export & ImportExport portable .cclens.json files with stats, metadata, facets, history, previews, and date filters. |
Import is preview-only right now. It shows which sessions are new or already present, but it does not write merged data back into ~/.claude/, to avoid corrupting live Claude Code files.
Multiple Claude Profiles
By default, cc-lens reads ~/.claude/. To point it at another Claude Code config directory, set CLAUDE_CONFIG_DIR:
# Default profile
npx cc-lens
# Work profile
CLAUDE_CONFIG_DIR=~/.claude-work npx cc-lens
On Windows PowerShell:
$env:CLAUDE_CONFIG_DIR="C:\Users\you\.claude-work"; npx cc-lens
The active config directory is shown in the CLI banner on launch.
CLI Options
npx cc-lens [options]
| Option | Default | Description |
|---|---|---|
--host <host> |
127.0.0.1 |
Address to bind. Loopback only by default. Set 0.0.0.0 to expose the dashboard on your LAN. Also settable with the CC_LENS_HOST env var. |
--port <port> |
3000 |
Port to listen on. Auto-increments if the port is taken. Also settable with the PORT env var. |
--help, -h |
Print usage and exit. | |
--version, -v |
Print the version and exit. |
The dashboard serves your private Claude Code history, so it binds to loopback (127.0.0.1) by default. cc-lens does not read the shell's HOSTNAME variable, so it works the same on WSL, containers, and CI. Override the host only if you understand the exposure.
# Bind to a fixed port
npx cc-lens --port 4000
# Expose on the local network (opt-in)
npx cc-lens --host 0.0.0.0
There are also cc-lens push and cc-lens digest subcommands for team mode; see Team mode.
Run From Source
Prerequisites
- Node.js 20+
- Claude Code with local data in
~/.claude/
Development
npm install
npm run dev
Open http://localhost:3000, or the port shown in your terminal.
Production Build
npm run build
npm start
For the packaged standalone bundle used by the CLI:
npm run build:dist
Checks
npm run lint
npm test
Project Docs
- Roadmap: planned improvements and non-goals.
- Known limitations: accuracy, compatibility, and runtime caveats.
- Compatibility: supported local files and reporting guidance.
- Contributing: local setup, PR expectations, and manual test notes.
- Team mode: shared-folder team analytics, push hub setup, and terminal team digests.
- Privacy: what data is read, exported, or edited.
- Security: private vulnerability reporting and review checklist.
Data Sources
cc-lens reads local Claude Code files directly:
~/.claude/projects/<slug>/*.jsonl: session JSONL and replay data~/.claude/stats-cache.json: aggregate stats when available~/.claude/usage-data/session-meta/: session metadata fallback~/.claude/history.jsonl: command history~/.claude/todos/: todo files~/.claude/plans/: saved plan files~/.claude/projects/*/memory/: project memory files~/.claude/settings.json: settings, skills, plugins, and MCP config
Dashboard data refreshes every 5 seconds while the app is open.
Privacy
Claude Code Lens runs locally and reads files from your machine. It does not require a login, API key, hosted backend, or telemetry service. Your Claude Code history stays on your computer.
Cost Estimates
Claude Code stores token counts and model identifiers, not final billing totals. cc-lens estimates cost using the pricing table in lib/pricing.ts. If provider pricing changes, update that file to keep estimates current.
To override or add rates without editing source, create ~/.cc-lens/pricing.json. Entries are merged over the defaults, so you can override a single model or add new ones. Values are in dollars per million tokens:
{
"claude-opus-4-8": { "input": 5.0, "output": 25.0, "cacheWrite": 6.25, "cacheRead": 0.5 }
}