cc-analyzer

Appearance

cc-analyzer Wiki ​

Indexed at commit 51ce1a4 on 2026-08-26 · view on GitHub

Implementation reference — This section documents internals and source-level behavior for contributors and integrators. The snapshot metadata on these pages records when the generated reference was last indexed; verify fast-moving details against the current source. For task-oriented instructions, start with the user guide.

Relevant source files ​

Overview ​

cc-analyzer is a read-only command-line tool that browses, analyzes, and checks the structural health of Claude Code sessions stored under ~/.claude. Claude Code writes each session as a JSONL transcript that records token usage per API call but not cost; cc-analyzer derives cost from those token counts and a per-model pricing table, then surfaces cost, tokens, tools, skills, subagents, a per-turn (and per-step) breakdown, evidence-backed recoverability findings, and a growing suite of portfolio analytics — cache-efficiency insights, time-series trends, tool/skill usage, and session/project charts (README.md).

During ordinary indexing and analysis the tool does not modify Claude's source transcripts or configuration. Its own state — a pricing cache, a SQLite session index, and an update-check cache — lives in the cc-analyzer state directory. The optional Analyze-with-Claude handoff starts a normal Claude Code process and is covered in the user guide. It is written in TypeScript, runs on Bun, and ships as a single self-contained binary bundling the CLI, the terminal UI, the web API, and the web front end.

What is cc-analyzer? ​

cc-analyzer is version 0.20.0, a TypeScript project targeting the Bun runtime (≥ 1.3) and distributed as a compiled binary (package.json:L1-L20). It exposes several ways to consume one analysis core: scriptable CLI commands, an interactive Ink terminal UI, a local Hono web API, and an embedded React single-page application — plus a VitePress documentation site. Dependencies reflect those surfaces: ink (TUI), hono (API), react/react-dom (SPA), zod (tolerant event parsing), and Bun's built-in SQLite driver for the index.

High-Level Architecture ​

Every frontend is a thin presentation layer over src/core. A single session flows .jsonl → parser → SessionEvent[] → analyzeSession() → SessionAnalysis (with a streaming variant for very large sessions), which the frontends render and which indexer.ts flattens into a SQLite row. The index then feeds portfolio analytics: stats.ts and the bun-free stats-types.ts/chart-series.ts modules build metrics and chart series that the TUI and web SPA import directly, so both frontends chart identical data (src/core/analyze.ts:L1-L40).

Repository Layout ​

text
cc-analyzer/
├── src/
│   ├── core/   # Parsing, analysis, steps, pricing, index, analytics, self-update
│   ├── cli/    # Scriptable command router + text renderers
│   ├── tui/    # Ink master-detail UI (portfolio · projects · sessions · insights · trends · tools)
│   └── web/    # Hono API + generated embedded SPA module
├── web/        # React SPA source (built by Vite, separate tsconfig)
├── site/       # VitePress docs site (landing + this wiki) + install scripts
├── scripts/    # compile-with-spa.ts — temporarily embeds the SPA while compiling
├── test/       # Bun tests, mirroring src/
├── docs/       # Design specs
└── .github/    # CI (matrix), release (binaries + checksums + provenance), Pages-deploy

The project uses a plain src/ layout, not a monorepo. Two subtleties: src/web/ is the API server while top-level web/ is the React SPA source; and site/ is an isolated VitePress toolchain with its own package.json/lockfile.

Key Subsystems ​

Core Analysis Engine ​

Parses transcripts, segments them into turns and per-turn steps, derives cost from tokens, and builds the portfolio SQLite index. Details — with pages on parsing & events, cost & pricing, index & aggregation, and the per-turn step timeline.

Command-Line Interface ​

The binary entrypoint and argv router: projects, sessions, analyze, doctor, index, stats, audit, insights, report, serve, pricing, update, version, telemetry, cost-basis, and claude-dir, with --json modes for scripting. Details.

Interactive Terminal UI ​

An Ink master-detail shell launched when the CLI runs with no command: a nav rail across portfolio, projects, sessions, insights, trends, and tools views, with in-terminal charts. Details.

Web Server & API ​

cc-analyzer serve runs a Hono server exposing a JSON API (including analytics endpoints) over the index and serving the embedded SPA. Details.

Web SPA Frontend ​

The React 19 single-page app — dashboard, a full project list, project drill-down, per-session view with charts, and the Insights/Trends/Tools analytics views. Details.

Analytics & Insights ​

The cross-cutting analytics capability: 20+ metrics, cache-efficiency insights, time-series trends, tool/skill/subagent analytics, and session/project charts — built once in bun-free core modules and rendered by both the TUI and the web SPA. Details.

Updates & Distribution ​

Version embedding, latest-release resolution, self-update with a streaming download and checksum verification, a passive update notice, and the cross-platform install scripts. Details.

Docs Site ​

The VitePress site that renders this wiki and the landing page, syncs /wiki as its single source of truth, and hosts the install scripts on GitHub Pages. Details.

Build & Tooling ​

Bun is both the runtime and the package manager. bun test runs the suite, Biome handles lint/format, and TypeScript type-checks in two passes (Bun-targeted core/CLI/TUI/server, and the browser-targeted SPA). bun run build bundles the SPA with Vite, embeds it into a disposable source copy under tmp/ (the tracked src/web/spa.ts placeholder is never modified), then compiles a single binary. See Repository Structure for the full pipeline and the CI/release/deploy workflows.

Child Pages ​

Sources: README.md package.json:L1-L42 src/cli/index.ts:L1-L40 src/core/analyze.ts:L1-L40

Reference links reviewed against cc-analyzer on 2026-08-26; page prose remains an implementation snapshot.