claude-code-transcripts-ingest

CLI that ingests every Claude Code transcript under ~/.claude/projects into a DuckDB database, with a normalised schema suited for usage / cost analysis across sessions, subagents, tool calls, and cache tokens. Ships with an embedded viewer served over HTTP, plus cct report usage for cost breakdowns and cct extract sessions for structured per-turn JSON dumps.

Installs the cct binary.

Install

cargo install claude-code-transcripts-ingest

The duckdb dependency is bundled (built from C++ sources), so the install is self-contained but takes a minute or two the first time.

Quick start

cct ingest                # scans ~/.claude/projects → ~/.local/share/cct/transcripts.duckdb
cct serve                 # viewer at http://localhost:8766
cct report usage          # token + cost breakdown by model (text or --json)
cct extract sessions      # structured per-turn JSON dump for downstream tooling

Commands

cct ingest

cct ingest [-i <dir>] [-o <file>] [-j <jobs>] [--pricing <toml>] [--no-progress]

cct serve

cct serve [--db <file>] [--port <n>]

Sessions list

Every session at a glance — cost, tokens, tools used, subagent flag. Filter by project, tool, model, or cost range; sort by most recent or highest spend.

Transcripts

Browse by project → session → turn-by-turn timeline. Every assistant turn shows its exact cost: input, output, cache-read, and cache-creation tokens with the resulting dollar amount. Subagent calls expand inline so you can trace the full cost of any delegated task back to the turn that triggered it.

Dashboard

A multi-panel cost dashboard split into two sub-tabs. Switch between them with the Overview and Outliers buttons; the active tab is preserved in the URL (?sub=outliers) so you can bookmark or share a specific view.

Overview — general spend picture:

• Summary (total cost, token breakdown)
• Daily Spend by Model
• Sessions/Week + $/Session (volume vs per-session cost)
• Token-type Cost Split (main-chain vs sidechain)
• First-turn Cache-Creation Distribution (system-prompt size proxy)
• Model Breakdown
• Errors

Outliers — actionable panels for reducing spend:

• Top 1% Most-Expensive Turns (top 30 by cost, click to open session)
• Top Sessions (by cost, click to open in Transcripts)
• Context Size Distribution (peak tokens per session)
• Cache Invalidation Events
• Compaction Events
• Hour-of-Day Cost
• Artifact Leaderboards: Large Writes / Agent Prompts / Tool Results
• Top Reads by Size
• File Hotspots (files re-read across the most sessions)
• Bash Leaderboards
• MCP Tool Result Sizes
• Hook Frequency & Duration
• Skill Invocation Stats
• Agent Model Usage
• Cache Health
• Session Distribution (by turn count)

Cost (/cost)

Cumulative spend split by what's actually being billed: tool result reads, cached assistant output, system prompt, user messages, file attachments. Identifies which content category dominates your bill.

cct report usage

cct report usage [--db <file>] [--project <dir> | --all] [--no-subdirs]
                 [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--json]

Token and cost breakdown by model, computed from assistant_entries_deduped. Default scope is the current working directory plus its subdirectory cwds (worktrees, sub-projects); narrow with --no-subdirs or widen with --all. Defaults to formatted text; --json emits a machine-readable structure.

cct extract sessions

cct extract sessions [--db <file>] [--project <dir> | --all] [--no-subdirs]
                     [--session <id-or-prefix>] [--from YYYY-MM-DD] [--to YYYY-MM-DD]

Dumps structured per-turn session metadata as JSON: conversations grouped by slug, sessions inside each, turns inside each session, with tools / skills / errors / tokens and inlined subagent metadata (model, calls, tokens, tools, skills, errors). Always JSON; pipe to jq or feed to downstream analysis tooling.

cct info

cct info [--db <file>]

Prints the DB path, file size, entry count, session count, and last ingest timestamp. Useful for confirming the DB location and freshness without opening DuckDB manually.

cct update

cct update [--version <vX.Y.Z>] [-y|--yes]

Self-updates the running cct binary from the latest GitHub release for the current OS/arch. Pass --version to install or pin a specific version. Pass -y to skip the confirmation prompt.

Update notifications

cct does a background GitHub-releases check once every 24 hours and prints a banner on stderr if a newer release exists. The check is skipped when:

• stderr is not a TTY (e.g. piped output);
• CCT_NO_UPDATE_CHECK=1 is set; or
• CI=true is set (the standard CI environment marker).

The cache file lives at $XDG_CACHE_HOME/cct/update_check.json (default ~/.cache/cct/update_check.json). Delete it to force a refresh.

Run cct --help / cct <subcommand> --help for the authoritative flag list.

Library

The transcript parser lives in claude-code-transcripts and can be used standalone without DuckDB.

License

Dual-licensed under MIT OR Apache-2.0.