cctx-cli 1.19.1

Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md

cctx

Diagnose your Claude Code sessions and OpenTelemetry agent traces — find out when they went wrong, why they cost what they did, and what to add to your CLAUDE.md so it doesn't happen again.

Install

pipx install cctx-cli

Or with pip: pip install cctx-cli. pipx is recommended: it isolates cctx's dependencies from your projects.

No API key required. cctx reads the JSONL logs Claude Code already writes to ~/.claude/projects/ and uses the token counts recorded there.

See it

Point cctx at your most recent session:

$ cctx autopsy --latest

Verdict: RETRY LOOP + SCOPE CREEP + STALE CONTEXT
Session cost: ~$1.42   (~85–95% of actual billing)
Inflection turn: 14

 RETRY LOOP  (high confidence) — Edit→Bash(npm test) repeated across turns
 14–22 with no intervening Read; the same test failed identically each time.

 SCOPE CREEP  (medium confidence) — the prompt was "fix auth bug"; refactoring
 of the user model began at turn 25 with no request observed.

 STALE CONTEXT  (medium confidence) — a 4.8K-token directory listing from
 turn 9 stayed in context 14 turns after its last reference.

──────────────────────────────── CLAUDE.md patches ────────────────────────────

When tests fail  [CLAUDE.md]
+ ## When tests fail
+ If a test fails twice with the same error, stop and re-read the source
+ file before attempting another fix.

Scope  [CLAUDE.md]
+ ## Scope
+ Stick to the task in the prompt. If you spot adjacent issues, name them
+ and ask before fixing.

cctx trace --latest   to step through this session interactively

Every finding ties to specific turns; every patch is a copy-pasteable CLAUDE.md diff. Add --health for an A–F grade plus per-finding savings.

The loop

cctx is forensic: you reach for it after a session that felt off, cost more than expected, or on a weekly review. The payoff comes from running the loop, not a single command:

1. Diagnose — autopsy the session you just finished.

cctx autopsy --latest        # the most recent session in this project
cctx init                    # or: run it automatically at every session end

2. Fix — turn the findings into durable CLAUDE.md rules. Harvest previews the diffs, then applies on confirm. It's idempotent: running it twice never duplicates an entry.

cctx harvest . --since 7d    # patches from the last week of sessions

3. Verify — after the rules have had time to bite, check whether they actually changed behavior.

cctx harvest . --efficacy    # finding rates before vs. after each patch

Two more entry points around the loop:

cctx autopsy --all --since 7d   # weekly digest across every project
cctx watch                      # live waste signals during an active session

cctx also diagnoses OTEL traces from the OpenAI Agents SDK, LangGraph, and any gen_ai.*-instrumented framework (auto-detected, no flags). See Other agent frameworks.

What cctx detects

Pattern	What it means	How it wastes money
Retry loop	The same tool call failing 2+ times with no successful fix	Repeated identical API calls burn input tokens
Scope creep	Assistant expanding scope mid-task without being asked	Unnecessary extra turns and tool calls
Stale context	Large tool results sitting in context long after their last reference	content_tokens × turns_stale — a 22K grep result present 14 turns after last use costs ~308K token-turns
Tool thrash	High tool-call volume with low forward progress	Exploratory calls that don't change the next step burn input tokens and turns
Dead end	Approach abandoned after significant sunk effort	Turns spent on a failing path before backtracking
Fan-out waste	Subagent spawned but result never consumed, or identical retry spawns	Full subagent cost with no new information
Cache hygiene	Frequent prompt-prefix changes that defeat KV-cache reuse	Cold input reads cost 10× a warm cache hit
Compaction	Context-window compaction mid-session	Compaction re-reads context from scratch; reduces effective context window
Exploration thrash	High read/search volume with no writes — circling without progress	Token cost of reads that don't advance the task
Unused context	MCP server loaded at session start but never called	Token overhead on every API request for tools that go unused

Commands

Common invocations below. Run cctx <command> --help for the full flag set.

cctx ls — find your sessions

cctx ls                      # all Claude Code projects
cctx ls ~/Projects/myapp     # sessions in one project

Handles the encoded ~/.claude/projects/ layout for you: no need to navigate it by hand.

cctx autopsy — diagnose a session

cctx autopsy --latest                # most recent session in this project
cctx autopsy session.jsonl           # a specific session file
cctx autopsy ~/Projects/myapp --since 7d   # aggregate one project's recent sessions
cctx autopsy --all --since 7d        # cross-project weekly digest

Runs 10 pattern classifiers and prints findings with attributed cost. Notable flags: --health (A–F grade + savings), --turn N (turn-level detail), --html report.html (self-contained report), --json (machine-readable). --since accepts 7, 7d, 2w, 2026-05-01, or 2026-05-01..2026-05-15.

cctx harvest — write fixes into CLAUDE.md

cctx harvest session.jsonl           # preview, then confirm
cctx harvest . --since 7d            # patches from the last week
cctx harvest . --since 7d --apply    # apply without prompting
cctx harvest . --check               # audit CLAUDE.md for dead refs / empty sections

Turns autopsy findings into copy-pasteable CLAUDE.md additions, deduplicated by fingerprint. --target-dir DIR picks which directory's CLAUDE.md to patch. --emit agents also writes applicable patches to AGENTS.md (add --sync to mirror existing cctx-managed sections). --efficacy measures whether applied patches reduced their target patterns. --check exits 1 when issues meet the severity threshold (useful as a CI gate on a committed CLAUDE.md).

cctx watch — live waste signals

cctx watch                   # the active session in this project
cctx watch ~/Projects/myapp  # a specific project

Tails the active session and prints a one-line alert each time a new waste pattern appears. Exits after 30s of inactivity or Ctrl+C.

cctx init — automatic post-session diagnostics

cctx init            # install the hook for this project
cctx init --global   # install for all projects (~/.claude/settings.json)
cctx init --remove   # uninstall

Installs a SessionEnd hook that runs cctx autopsy --latest --quiet when a session ends. Output appears only when findings exist; idempotent.

cctx trace — interactive TUI

cctx trace --latest          # step through the most recent session
cctx trace session.jsonl     # a specific session

Walks a session turn by turn with autopsy findings overlaid. Press q to quit.

cctx export — machine-readable data

cctx export session.jsonl --format csv --out session.csv   # one row per turn
cctx export session.jsonl --format jsonl                   # one object per session, to stdout

Dumps session analysis as jsonl/csv/json for external tools. Add --no-content to omit patch text and finding summaries.

Going further

Other agent frameworks

cctx diagnoses OTEL traces from the OpenAI Agents SDK, LangGraph, and any framework that emits gen_ai.* semantic-convention spans. It sniffs the file format and routes to the right parser: cctx autopsy agent_trace.jsonl works with no flags. See docs/quickstart-otel.md for wiring the exporter in each framework.

Cost attribution

cctx estimates cost from Anthropic's published billing rates: input tokens at the standard rate, cache reads at 10%, cache writes at 125%. Stale-context waste is attributed turn by turn: every turn a large result lingers after its last reference counts against waste.

These are approximations (~85–95% of actual API billing). The gap is internal prompt framing that isn't observable in the JSONL logs. cctx shows estimated costs, not billing-exact figures.

In CI

cctx is a local forensic tool: session logs are personal history and shouldn't be committed to git. The one exception: when Claude Code runs inside a GitHub Actions job (agentic PR workflows), the logs are written on the runner and cctx can analyze them as a post-step.

- uses: anthropics/claude-code-action@v1
  with:
    # ... your agentic workflow config

- uses: jacquardlabs/cctx@v0
  with:
    fail_on_findings: false   # set true to gate the job on waste findings
    github_summary: true      # write findings to the job summary UI

The action auto-discovers the most recent session on the runner. For a manual step, pipx run cctx-cli autopsy --latest . --github-summary appends findings to the job summary; add --fail-on-findings to exit 1 on detection.

Requirements

• Python 3.10+
• Claude Code session logs at ~/.claude/projects/ (written automatically)
• No API key for analysis. An optional ANTHROPIC_API_KEY enables exact token counts via the Anthropic API; without it, cctx uses the counts already in the logs (the default and recommended mode).

License

MIT