# cc-lens reads your Claude Code history and puts it in a local dashboard

> cc-lens is a TypeScript and Next.js CLI that reads the JSONL files under your ~/.claude directory and serves a local analytics dashboard over them, with no cloud, no telemetry and no API key. It suits individual developers who want to see what their agent sessions cost, and it stops at the local machine.

**Arindam200/cc-lens** — Local analytics dashboard for Claude Code. No cloud, no telemetry.

- Repository: https://github.com/Arindam200/cc-lens
- Website: https://www.youtube.com/watch?v=F01R99FeB5U
- Stars: 599 · Forks: 92
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/arindam200-cc-lens

## A dashboard that reads your ~/.claude directory

Claude Code Lens, published as cc-lens, is described as a local analytics dashboard for Claude Code with no cloud, no telemetry and no API key, just your ~/.claude/ data visualised. The tagline is the architecture. There is no account, no ingest endpoint and no remote service in the flow, because the tool reads the files Claude Code already writes on your disk and renders them in a browser. That makes it a different category of tool from the hosted usage dashboards that ship with coding assistants, and the difference is a security property rather than a feature checkbox: your prompts, replies and tool calls never leave the machine unless you explicitly export them. The primary language is TypeScript, the app is a Next.js project with app, components and lib directories, and the package manifest pins next at 16.2.2 with React 19.2.3, Tailwind 4 and Recharts for the charts. The bin entry points cc-lens at bin/cli.js, and the published files are the bin directory, the standalone Next.js output and the static assets, which is how a CLI can ship a whole web app in an npm tarball.

## The launch path: npx, a free port, a browser window

Running the tool is one command.

```bash
npx cc-lens
```

The CLI finds a free local port, starts the dashboard, and opens it in your browser. On first run, cc-lens prepares a small runtime cache in ~/.cc-lens/, and the documentation notes that after that, launches are faster. That cache is the only thing the tool writes outside the Claude Code directory by default, and it is worth knowing about because it means the tool has a small persistent footprint of its own. The port behaviour is forgiving: the default is 3000 and it auto-increments if the port is taken, so a stale process from an earlier session does not block a new launch. The dashboard data refreshes every five seconds while the app is open, which is what makes the view feel live rather than a static report, and it also means the server is re-reading your session files continuously while you work.

## What the dashboard panels actually show

The view set is wide enough that it is worth separating into groups. The Overview panel tracks sessions, messages, tokens, cost, storage, trends, models, peak hours, projects and recent activity. Costs covers estimated spend, cache savings, project costs, model breakdowns, token usage and pricing references, and Insights derives cache, model, compaction, plan-fit, budget and savings opportunities from local usage patterns. Sessions is the forensic view: you can search sessions, replay JSONL conversations, and inspect Markdown replies, tool calls, costs, tokens and compactions. Projects and Project Trends break activity down by sessions, duration, spend, languages, branches, MCP usage, agents and top tools. Tools and Features compares tool rankings, categories, skill or slash-command usage, MCP servers, feature adoption, errors, versions and git branch usage. Activity provides calendars, streaks, active days, peak hours and day-of-week patterns. Tasks lists Claude Code todos with search, status filters and local file provenance. Workspace inspects workspace state, memory, settings, installed skills, plugins, MCP servers and local storage usage.

## Wrapped, export and the preview-only import

Two panels stand out from the rest. Wrapped creates a yearly card with sessions, usage, spend, favourite tools, active projects and local highlights, which is a novelty feature but also a convenient way to notice a usage pattern you would otherwise miss. Export and Import handle portable .cclens.json files carrying stats, metadata, facets, history, previews and date filters. The important limitation is on the import side, and the documentation is explicit about it: 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. Read that as a deliberate design boundary. The tool is a reader of Claude Code's data, not a writer, and it keeps itself out of the directory that matters. That decision costs you the ability to consolidate profiles into a single archive, and in exchange the worst case of a bug is a wrong chart rather than a damaged session history.

## The files behind every panel

The data source list explains what each panel can possibly know, so it is the section to check first when a view looks empty. cc-lens reads local Claude Code files directly: session JSONL and replay data from ~/.claude/projects/<slug>/*.jsonl, aggregate stats from ~/.claude/stats-cache.json when available, session metadata from ~/.claude/usage-data/session-meta/ as a fallback, command history from ~/.claude/history.jsonl, todo files from ~/.claude/todos/, saved plan files from ~/.claude/plans/, project memory files from ~/.claude/projects/*/memory/, and settings including skills, plugins and MCP configuration from ~/.claude/settings.json. Two things follow from that list. The fallback path for session metadata means a panel can still show something when the aggregate stats cache is absent, and the list is version sensitive, because Claude Code's own directory layout is what defines it. The repository ships a compatibility document listing supported local files and reporting guidance, which is the reference to consult when a panel is empty or a column is missing.

## Multiple profiles, and the environment variable that switches them

By default, cc-lens reads ~/.claude/. To point it at another Claude Code config directory, set CLAUDE_CONFIG_DIR.

```bash
# Default profile
npx cc-lens

# Work profile
CLAUDE_CONFIG_DIR=~/.claude-work npx cc-lens
```

On Windows PowerShell the equivalent sets the environment variable in the session before running the command. The active config directory is shown in the CLI banner on launch, which is a small but genuinely useful detail, since a mis-set variable means you are looking at the wrong history and would otherwise have no obvious way to tell. Multiple profiles matter because a single developer often has a personal configuration and a work one, and a dashboard that silently merges them is worse than no dashboard. The same applies to teams sharing a folder of history, which is what the separate team mode documentation covers, along with the cc-lens push and cc-lens digest subcommands and a shared-folder setup for terminal digests.

## Loopback by default, and what changes when you do not

The dashboard serves your private Claude Code history, so it binds to loopback at 127.0.0.1 by default. The port option defaults to 3000 and the host option to 127.0.0.1, and the documentation is careful about the exposure that opting out creates.

```bash
# 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
```

Two details deserve attention. The host is also settable through a CC_LENS_HOST environment variable, and cc-lens deliberately does not read the shell's HOSTNAME variable, so it behaves the same on WSL, in containers and on CI. That is a small decision with a real purpose: inheriting HOSTNAME would silently bind a container's dashboard to an unexpected interface. The cost of that predictability is that the opt-in has to be explicit, which is the right trade for a tool whose payload includes your conversations. The documentation's own wording is the summary: override the host only if you understand the exposure.

## Running from source, and the shape of the release history

If you want to work on the tool rather than just use it, the prerequisites are Node.js 20 or newer and Claude Code with local data in ~/.claude/.

```bash
npm install
npm run dev
```

Open http://localhost:3000, or the port shown in your terminal. The production path is npm run build followed by npm start, and the packaged standalone bundle that the CLI itself uses comes from a separate script.

```bash
npm run build:dist
```

The scripts section of the manifest explains the split: build is next build, build:dist is next build plus node bin/prepare-standalone.js, and prepublishOnly runs the dist build so a published tarball always contains the standalone output. The release history is a good signal of the project's pace. v0.2.8 added global search and keyboard navigation on 2026-04-05, v0.3.3 shipped a prebuilt standalone bundle with accurate pricing on 2026-05-20, and v0.4.0 brought team mode, savings insights, Wrapped and tasks on 2026-06-12, with the manifest sitting at 0.4.1. The last push to the repository was on 2026-06-27. The licence is MIT, so the code can be read, modified and redistributed with attribution, and the repository also carries separate documents for the roadmap, known limitations, compatibility, contributing, team mode, privacy and security reporting.

## Conclusion

Adopt cc-lens if you are a Claude Code user who wants cost, token and session breakdowns computed from your own local history, and if you are comfortable running a local server over files that contain your prompts and replies. Do not adopt it if you need a shared or hosted view, since the dashboard binds to loopback by default and the import path is preview-only, or if your usage data has to leave the machine through a controlled pipeline. Verify two things first: that the version you install matches the layout of your ~/.claude directory, because the project ships a compatibility document listing supported local files, and that you have read the privacy document, which covers what data is read, exported or edited. The practical first step is npx cc-lens with the default host, confirm the CLI banner shows the config directory you expect, and only then consider changing the bind address, because the dashboard exposes your private conversation history to anyone who can reach the port.

## FAQ

### How do I run cc-lens?

Run npx cc-lens. The CLI finds a free local port, starts the dashboard and opens it in your browser, preparing a small runtime cache in ~/.cc-lens/ on the first run so later launches are faster.

### Does cc-lens send my Claude Code data anywhere?

It is described as a local dashboard with no cloud, no telemetry and no API key, reading your ~/.claude/ files directly. The dashboard binds to loopback by default, and the project ships a privacy document covering what data is read, exported or edited.

### Can I point cc-lens at a different Claude Code profile?

Yes. Set CLAUDE_CONFIG_DIR to the config directory you want, for example CLAUDE_CONFIG_DIR=~/.claude-work npx cc-lens. The active config directory is shown in the CLI banner on launch.

### Can I import a cc-lens export back into Claude Code?

No, not yet. Import is preview-only: it shows which sessions are new or already present, but it does not write merged data back into ~/.claude/, specifically to avoid corrupting live Claude Code files.

### How do I expose the cc-lens dashboard on my local network?

Pass --host 0.0.0.0, or set the CC_LENS_HOST environment variable. The default is 127.0.0.1, loopback only, and the documentation warns to override the host only if you understand the exposure.

### What does cc-lens read from my Claude Code directory?

Session JSONL and replay data from ~/.claude/projects/<slug>/*.jsonl, aggregate stats from ~/.claude/stats-cache.json, session metadata from ~/.claude/usage-data/session-meta/ as a fallback, command history, todos, saved plans, project memory files, and settings covering skills, plugins and MCP configuration.

## Sources

- [Arindam200/cc-lens on GitHub](https://github.com/Arindam200/cc-lens)
- [License: MIT](https://github.com/Arindam200/cc-lens/blob/main/LICENSE)
- [Project website](https://www.youtube.com/watch?v=F01R99FeB5U)
- [README](https://github.com/Arindam200/cc-lens/blob/main/README.md)
- [Releases](https://github.com/Arindam200/cc-lens/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/arindam200-cc-lens