cclens

cclens

A lens onto your Claude Code usage. cclens reads your session transcripts and live configuration, extracts them into a local SQLite store, and shows where time, tokens, and effort are being wasted — and how to fix it: unused or heavy config, recurring tool failures, where the work gets stuck, and the cost picture behind it all.

The design intent lives in docs/specs/; this README is how to run it.

Install / build

With Nix (no toolchain to set up):

nix run github:lambdalisue/cclens -- doctor   # run without installing
nix profile install github:lambdalisue/cclens  # install `cclens` onto PATH

From source — dev tools are pinned by the Nix flake, tasks run via just:

nix develop          # enter the dev shell (pinned rust, just, sqlite, …)
just                 # list tasks
just check           # rustfmt --check + clippy (the CI gate)
just test            # cargo test
just build           # release binary at target/release/cclens

Plain Cargo also works (cargo build --release) if you have a recent stable Rust; the flake just pins it. CI runs nix develop -c just check / just test, and tagged releases (vX.Y.Z) build native binaries for Linux/macOS/Windows.

Claude Code plugin

The repository is also a Claude Code plugin marketplace (.claude-plugin/ + plugins/cclens/), so you can drive cclens from inside a Claude Code session:

/plugin marketplace add lambdalisue/cclens
/plugin install cclens@cclens

Skill	What it does
/cclens:doctor	Analyze and present the one-screen health check in the session.
/cclens:optimize	The cclens optimize advisor, in the current session: investigate the findings to root cause and propose concrete config fixes.
/cclens:query	Answer an ad-hoc usage question with read-only SQL over the store.

The skills use the cclens binary when it is on PATH and fall back to nix run github:lambdalisue/cclens otherwise. Outside this repository they keep the store at ~/.cache/cclens/cclens.db instead of dropping a cclens.db into your project.

Quick start

# 1. Start here — a one-screen health check, split into what to fix globally
#    (~/.claude) vs per project. Analyzes automatically on first run.
cclens doctor

# 2. Narrow to the layer you're optimizing.
cclens doctor --scope global
cclens doctor --scope project:<slug>

# 3. Act on the findings: hand them to an interactive `claude` session that
#    investigates each root cause and proposes concrete fixes.
cclens optimize --scope global

Analysis reads your transcripts (~/.claude/projects) and live config — ~/.claude/* plus each analyzed project's own .claude/ / CLAUDE.md — read-only and incrementally, writing cclens.db. Nothing is sent anywhere; the store is a local file. Every command takes --db <path> (default cclens.db). Read commands refresh the store automatically before reporting (unchanged transcripts are skipped, so this is fast) and print a freshness line on stderr; pass --frozen to read the store exactly as it is. Running cclens analyze yourself is only needed to refresh without reading.

Commands

Pipeline

Command	What it does
cclens doctor	The health check, split global / per-project — start here.
cclens analyze	Extract transcripts + config into the store (incremental). Reads run it automatically.
cclens sql '<query>'	Run an arbitrary read-only SQL query against the store (see below).
cclens optimize	Hand the findings to an interactive claude session to act on.

--scope global | project | project:<slug> (on doctor, failures, waste, inventory, optimize) restricts a report to the config layer being optimized: an unused/heavy config finding routes by where that file is installed, and a recurring failure belongs to the project that owns a strict majority of it — otherwise it is a cross-project habit and shows up as global.

Views

Each is a curated lens that carries logic a raw query cannot (a classification, an algorithm, a suggestion). Add --format markdown to paste into a PR or note, or --format json (every command, doctor and analyze included) for typed machine-readable output — stdout carries nothing but the JSON, since all freshness chatter goes to stderr. Human output is colorized on a terminal; NO_COLOR or piping turns it off.