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: 3 findings · $0.98 waste
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 |
Every per-turn pattern above is also detected inside subagents — a retry loop or stale-context buildup within a child session (at any nesting depth) is surfaced, tagged with that subagent, and priced at the subagent's own model.
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.
JSON/JSONL output includes a subagent_costs array — one entry per dispatched subagent, with session_id, label, cost_usd, depth, model, and dispatching_tool_use_id (the parent turn's tool_use_id that dispatched it — a join key for correlating external dispatch-time telemetry against actual cost).
CSV output covers the root session and every subagent at every depth, one row per turn. Row identity is (session_id, turn_number) — turn numbers restart at 1 in each subagent trace. Four columns carry dispatch identity:
| Column | Root row | Subagent row |
|---|---|---|
depth |
0 |
1 = direct child, 2 = grandchild, … |
parent_session_id |
empty | the dispatching session |
dispatching_tool_use_id |
empty | the Agent tool_use_id in the immediate parent that dispatched this session |
root_dispatch_tool_use_id |
empty | the depth-1 ancestor's dispatch id, carried down the whole subtree |
SELECT root_dispatch_tool_use_id, SUM(cost_usd) ... GROUP BY 1 rolls a whole subtree up to the dispatch that spawned it. Filter depth == 0 to get the root-only table.
cost_usd is the full-request figure — input, output, and prompt-cache tokens at the model's own rates, priced per turn so a session that interleaves models bills each turn correctly. It is the same number the analyzer reports, so SUM(cost_usd) over all rows reconciles with total_cost_usd in JSON/JSONL to within rounding. Note input_tokens remains the input component only — cost_usd / input_tokens is not an implied rate.
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 prices both input and output tokens from a built-in table covering Anthropic (Claude) and OpenAI models, so OTEL traces are costed at the right provider's rates — not just Claude sessions. Prompt-cache reads bill at 10% of input, 5-minute cache writes at 125%, 1-hour writes at 200%. Stale-context waste is attributed turn by turn: every turn a large result lingers after its last reference counts against waste.
The price table is stamped with a verification date (shown as "prices as of …" in output) and a CI tripwire flags it when stale; an unrecognized model family is flagged and priced at a default rate rather than silently mis-costed.
These are approximations (~85–95% of actual API billing). The gap is internal prompt framing that isn't observable in the 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@v1.20.0
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_KEYenables exact token counts via the Anthropic API; without it, cctx uses the counts already in the logs (the default and recommended mode).
Contributing
Issues and PRs welcome.
pip install -e ".[dev]"
ruff check cctx tests
CCTX_OFFLINE=1 pytest -v
License
MIT
TODO: no
LICENSEfile exists at the repo root, thoughpyproject.tomldeclareslicense = "MIT"and GitHub's API reports no detected license for this repo. The License badge at the top of this page also links toLICENSE, which doesn't exist yet. Add aLICENSEfile so both are accurate.
Metadata
Release files for cctx-cli 1.24.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cctx_cli-1.24.4.tar.gz | 3.4 MB | With provenance | Details for cctx_cli-1.24.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cctx_cli-1.24.4-py3-none-any.whl | Python 3 | none | any | Details for cctx_cli-1.24.4-py3-none-any.whl |
Total release size: 3.5 MB
Release files / cctx_cli-1.24.4.tar.gz
| Download URL | cctx_cli-1.24.4.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3355df0a8a29177b3c05abf8612cc9af9664d3aa562600daedbc60f26d77549b
|
|
BLAKE2b-256 checksum How to use checksums |
8d1832cf0a90dcf053e8e1b2f6b044115441c98952e923576c2dd28f76d0715a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / cctx_cli-1.24.4-py3-none-any.whl
| Download URL | cctx_cli-1.24.4-py3-none-any.whl |
|---|---|
| Size | 107.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
969754eed1069f76be6d09ac8b56b2069beec2141511e726158010ea703fedbe
|
|
BLAKE2b-256 checksum How to use checksums |
415f6495ee56fa3f8f7074def24ec48474d086ef8eb364f77821e73408b0a21a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logSecurity for cctx-cli 1.24.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cctx_cli-1.24.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.