Metadata-Version: 2.4
Name: cctx-cli
Version: 1.1.0
Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
Author: Jacquard Labs
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.25
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0
Requires-Dist: rich-click>=1.8
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.59
Provides-Extra: dev
Requires-Dist: anyio[trio]; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![CI](https://github.com/jacquardlabs/cctx/actions/workflows/ci.yml/badge.svg)](https://github.com/jacquardlabs/cctx/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/cctx-cli)](https://pypi.org/project/cctx-cli/)
[![Python](https://img.shields.io/badge/python-3.10_%7C_3.11_%7C_3.12_%7C_3.13-blue)](https://pypi.org/project/cctx-cli/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

![demo](demo.gif)

## Install

```bash
pipx install cctx-cli
```

Or with pip:

```bash
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

```bash
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

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

### `cctx autopsy` — diagnose a session

```bash
# 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

```bash
# 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).

```bash
# 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

```bash
# 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

```bash
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

```bash
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)

```yaml
- 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

```yaml
- 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
