cctx-cli 1.3.0

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

cctx

Diagnose your Claude Code sessions — 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 installs cctx in an isolated environment so its dependencies don't conflict with your projects.

Quick start

cctx ls                   # find your sessions
cctx autopsy --latest     # diagnose the most recent one
cctx watch                # live signals during an active session

cctx is primarily a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. cctx watch runs during a session and surfaces patterns as they happen. It reads the JSONL logs Claude Code writes to ~/.claude/projects/ and produces findings with attributed cost and copy-pasteable CLAUDE.md patches.

Commands

cctx ls — list projects and sessions

cctx ls                    # list all Claude Code projects
cctx ls ~/Projects/myapp   # list sessions for a specific project

cctx autopsy — diagnose a session

# Most recent session in the current directory
cctx autopsy --latest

# Specific session file
cctx autopsy ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl

# All sessions from the last 7 days
cctx autopsy ~/Projects/myapp --since 7

# Write a self-contained HTML report
cctx autopsy ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --html report.html

Runs three pattern classifiers (retry loop, scope creep, stale context) and prints findings with attributed cost. Use --since N to aggregate patterns across multiple sessions in a project.

cctx harvest — apply patches to CLAUDE.md

# Interactive: preview then confirm
cctx harvest ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl

# Preview only — don't write anything
cctx harvest ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --dry-run

# Apply without confirmation
cctx harvest ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --apply

# Cross-session: patches from the last 7 days of sessions
cctx harvest ~/Projects/myapp --since 7

Turns autopsy findings into copy-pasteable CLAUDE.md additions. Patches are idempotent — running harvest twice on the same session won't duplicate entries. Use --target-dir DIR to specify which directory's CLAUDE.md to patch (default: current working directory).

# Audit existing CLAUDE.md for dead file references and empty sections
cctx harvest . --check

--check reads the target CLAUDE.md without writing anything. Exits 1 if issues are found (dead file references, dead skill references, empty sections), 0 if clean. Useful as a CI step when CLAUDE.md is committed to the repo.

cctx export — export session data

# CSV to file
cctx export ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --format csv --out session.csv

# JSONL to stdout
cctx export ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --format jsonl

# Omit patch text and finding summaries (smaller output for scripted use)
cctx export ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --format jsonl --no-content

Dumps session analysis as JSONL (one object per session) or CSV (one row per turn) for use in external tools.

cctx watch — live waste signals

cctx watch                    # watch the active session in cwd's project
cctx watch ~/Projects/myapp   # watch a specific project

Tails the active session as it progresses and prints a single-line alert each time a new waste pattern is detected. Exits after 30s of session inactivity or Ctrl+C.

cctx trace — interactive TUI

cctx trace ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl

Steps through a session turn by turn in a terminal UI with autopsy findings overlaid. Press q to quit.

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 × billed_turns_stale — a 22K grep result still present 14 turns later costs ~308K token-turns

Cost attribution

cctx estimates session cost using Anthropic's published billing rates:

• Input tokens: standard rate
• Cache reads: 10% of the input rate
• Cache writes: 125% of the input rate

Stale-context waste is attributed turn by turn: every turn a large result stays in context 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.

Requirements

• Python 3.10+
• Claude Code session logs at ~/.claude/projects/ (written automatically by Claude Code)
• No API key required for analysis

An ANTHROPIC_API_KEY is optional. When set, cctx can call the Anthropic API for exact token counts. Without it, cctx uses the token counts already recorded in the JSONL logs (the default and recommended mode for most users).

Session log location

Claude Code writes logs to ~/.claude/projects/<encoded-path>/<session-id>.jsonl. The project path is URL-encoded with - replacing /, so /Users/you/Projects/myapp becomes -Users-you-Projects-myapp.

cctx ls handles discovery automatically — you don't need to navigate the encoded directory structure by hand.

Using cctx in CI

cctx is primarily a local forensic tool — it reads session logs from ~/.claude/projects/ on your machine. Those logs are personal conversation history and should not be committed to git or uploaded as build artifacts.

The one case where cctx belongs in CI: when Claude Code itself runs inside a GitHub Actions job (agentic PR workflows, automated coding steps). In that case the JSONL logs are written on the runner during the job and cctx can analyse them as a post-step.

GitHub Action (recommended)

- 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 Claude Code session written on the runner. It does not accept arbitrary file paths — that pattern would require committing session logs to the repo, which you should not do.

Manual step

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

- name: Analyse session
  run: pipx run cctx-cli autopsy --latest . --github-summary

--github-summary appends a markdown findings report to the GitHub Actions job summary UI. Add --fail-on-findings to exit 1 when waste patterns are detected.

Commands that make sense as CI steps:

• cctx autopsy — diagnose the session that just ran
• cctx export — archive structured findings as a build artifact

cctx harvest requires session logs AND writes to CLAUDE.md — neither step maps cleanly to CI. Run it locally after a session.

License

MIT