KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #codex #typescript #developer-tools #ai-agents #deepseek-harness #claude-code #ai-agent #cli #react #mcp

cclens

★ 79 Open GitHub ↗

cclens — a lens onto your Claude Code usage

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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/`](docs/specs/); this README is how to
run it.

## Install / build

With Homebrew (macOS and Linux, Intel and arm):

```sh
brew install lambdalisue/cclens/cclens
```

With Nix (no toolchain to set up):

```sh
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`:

```sh
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`.

Publishing a GitHub Release for a `vX.Y.Z` tag builds binaries for Linux and
macOS (x86_64 and arm64 each), attaches them to that release with `.sha256`
files, and points the
[`lambdalisue/homebrew-cclens`](https://github.com/lambdalisue/homebrew-cclens)
tap at the new archives. The release is published before its assets are built,
so the notes are visible for a few minutes with nothing attached yet. Windows is
not supported: `~/.claude` is located through the `HOME` environment variable,
which Windows does not set.

## Claude Code plugin

The repository is also a Claude Code plugin marketplace
([`.claude-plugin/`](.claude-plugin/) + [`plugins/cclens/`](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

```sh
# 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.

```sh
cclens waste                 # ranked optimization opportunities, with a suggested action
cclens waste --scope global  # …only what a global-config cleanup should touch
cclens inventory               # every installed surface (with its scope) × its actual usage
cclens overhead               # always-on context per session, reconciled vs your config
cclens usage                  # per-skill usage, most-invoked first
cclens usage --by month       # usage per time bucket (JST: year|month|week|day|hour)
cclens failures               # recurring tool failures by category, ranked, with fixes
cclens failures --scope global          # failures no project owns (a cross-project habit)
cclens failures --scope project:<slug>  # one project's failures (fix lands in its config)
cclens prompts                # how you steer the session (steer/correct/question/instruct)
cclens stuck                 # files Claude got stuck re-editing in rapid bursts
```

### `sql` — query the store directly

Anything the curated views don't cover is a SQL query — the store is the whole
point. The query is an argument, or read from **stdin**:

```sh
# Which tool produces each failure category?
cclens sql "SELECT category, tool, COUNT(*) n FROM tool_errors GROUP BY 1,2 ORDER BY n DESC"

# The actual failing paths behind path-not-found (stdin form):
echo "SELECT excerpt FROM tool_errors WHERE category='path-not-found'" | cclens sql

# Discover the schema:
cclens sql "SELECT sql FROM sqlite_master"
```

The `tool_errors` view names the failure columns (`category`, `excerpt`,
`tool`, `project`); the db is opened read-only, so a query can never mutate the
derived store.

## What it covers

- **Every configuration surface** — skills, rules, agents, MCP servers,
  `CLAUDE.md` — catalogued with its static token cost and load mode, joined
  against actual usage to flag unused (delete), always-on heavy (slim), and
  costly+rare (trim).
- **Where the work stumbles** — recurring tool failures by category and
  originating tool (`failures`), files Claude got stuck re-editing (`stuck`),
  each with concrete examples and the project it concentrates in.
- **Where tokens go** — main-thread skill output vs. subagent cost, and the
  always-on context floor reconciled against your readable config (the residual
  is system + tools + MCP you cannot trim from files).
- **How you prompt** — the steer / correct / question / instruct mix.

## Notes

- Counts are usage signals for ranking, **not a billing ledger**; static cost is
  a token estimate, not a measured runtime figure.
- The store is a regenerable cache. After upgrading cclens across a schema
  change, commands refuse the old file with a hint — delete `cclens.db` (or
  point `--db` somewhere fresh) and it is rebuilt on the next read.
- `optimize` launches `claude` (Claude Code) seeded with the findings; the
  briefing is written to a private temp file, never passed on the command line.
- Not yet implemented (see [`docs/specs/`](docs/specs/)): meta-skill (`loop`)
  nesting — a pending design decision on detecting parent/child from the
  transcript.

cclens

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README