cc-lens

[cc-lens CLI]

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.

View the v0.4.0 release notes

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

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]

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 }
}

Star History