cctx-cli 0.1.0__tar.gz

cctx_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check cctx tests
+
+      - name: Pytest
+        env:
+          CCTX_OFFLINE: "1"
+        run: pytest -v

cctx_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    name: Test before publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Pytest
+        env:
+          CCTX_OFFLINE: "1"
+        run: pytest -v
+
+  publish:
+    name: Publish to PyPI
+    needs: [test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

cctx_cli-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.eggs/
+pip-log.txt
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local Claude Code settings (machine-specific permissions)
+.claude/settings.local.json

cctx_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,176 @@
+# cctx
+
+Open-source Python CLI that diagnoses individual Claude Code sessions: when they went wrong, why they went wrong, what they cost, and what to add to your `CLAUDE.md` so it doesn't happen again. Reads the JSONL session logs Claude Code writes to `~/.claude/projects/` and produces actionable autopsy reports.
+
+The complete product pitch, example outputs, growth staircase, and positioning vs. adjacent tools are in [`cctx-project-brief.md`](cctx-project-brief.md). Read it once.
+
+## Tech stack
+
+- **Python 3.10+**
+- **click** — CLI argument parsing and subcommand routing
+- **rich-click** — re-skins click's `--help` through rich (drop-in: `import rich_click as click`). Pure shininess win on the `--help` surface, no behavioral cost
+- **rich** — terminal output: tables, banners, severity badges, diff blocks
+- **textual** — the TUI for `cctx trace`
+- **anthropic** — token counting only, via `anthropic.messages.count_tokens` in the tokenizer module. **Not imported anywhere else.**
+- **pandas** — optional, only inside the cross-session aggregator if/when row-level work justifies it. Stdlib-first.
+- **Jinja2** — HTML report templates for `cctx autopsy --html`
+
+Explicitly not used: web frameworks, databases, ORMs, async runtimes, cloud SDKs. cctx is a local CLI.
+
+## Architecture
+
+```
+Session log (Claude Code JSONL on disk)
+  ↓
+Parser           ← dependency-free; takes a path, returns SessionTrace
+  ↓
+Tokenizer        ← only place that imports anthropic; offline-mode safe for CI
+  ↓
+Diagnostician    ← per-turn investigation: inflection detection + pattern
+                   classifiers (retry loop, scope creep, stale context).
+                   Produces a Diagnosis.
+  ↓
+Recommender      ← turns Findings into Patches: copy-pasteable CLAUDE.md /
+                   rule / skill diffs, evidence-backed when cross-session.
+  ↓
+Renderers        ← rich (terminal), Jinja2 (HTML report), textual (trace
+                   TUI overlay).
+  ↓
+Exporters        ← jsonl, csv.
+```
+
+## Project layout
+
+```
+cctx/
+├── cli.py              # click + rich-click; routes to autopsy / trace / export
+├── parsers/
+│   └── claude_code.py  # SHIPPED. Parse ~/.claude JSONL logs.
+│                       # Spec: docs/superpowers/specs/2026-05-12-claude-code-parser-design.md
+├── tokenizer.py        # SHIPPED. anthropic.count_tokens wrapper; CCTX_OFFLINE heuristic.
+├── models.py           # SHIPPED. Turn, ToolUse, ToolResult, Usage, Attachment,
+│                       # RawToolResultFile, SessionTrace + group_into_exchanges().
+│                       # M2 extends with Finding, Patch, Diagnosis.
+├── diagnostician/
+│   ├── __init__.py     # public: run(trace) -> Diagnosis
+│   ├── inflection.py   # detect the turn where the session diverged
+│   ├── patterns/
+│   │   ├── retry_loop.py
+│   │   ├── scope_creep.py
+│   │   └── stale_context.py
+│   └── aggregate.py    # cross-session pattern aggregator (--since mode)
+├── recommender/
+│   ├── claude_md.py    # Finding -> Patch (CLAUDE.md diff proposals)
+│   └── evidence.py     # session-count + dollar evidence accumulation
+├── harvest.py          # SHIPPED. apply_patch, preview_patches, apply_patches —
+│                       # append-only, idempotent CLAUDE.md patching with
+│                       # fingerprint-based deduplication.
+├── renderers/
+│   ├── terminal.py     # rich rendering of a Diagnosis
+│   ├── report.py       # Jinja2 HTML report (cctx autopsy --html)
+│   └── trace_tui.py    # textual TUI with autopsy findings overlaid
+└── exporters/
+    ├── jsonl.py
+    └── csv.py
+```
+
+## Layering rules (enforced by convention)
+
+These keep the dependency graph clean so modules stay independently testable and refactorable:
+
+- **Parsers never import the tokenizer, the anthropic SDK, or any analyzer.** A parser takes a path and returns a `SessionTrace` with `token_count: int = 0` placeholders.
+- **Tokenizer is the only module that imports `anthropic`.** Everyone else gets token counts pre-populated on the dataclasses.
+- **Analyzers (diagnostician, recommender, aggregate) never import each other across boundary lines.** Inside the diagnostician package, helpers can compose freely. The recommender takes a Diagnosis and emits Patches without reaching back into the diagnostician's internals.
+- **Renderers never compute analysis.** They take an analyzer's output and render it. Swapping `terminal.py` for `report.py` should not change a single number or finding.
+- **Only `cli.py` imports `click` and `rich_click`.** Everything else uses plain `rich.Console` if it needs to output. Analyzers and parsers return data; the CLI decides how to display it.
+
+## Core design decisions
+
+These came out of the brief, the parser brainstorming session, and the autopsy pivot. They apply across the entire codebase:
+
+- **Diagnose the specific session, not the aggregate.** cctx is forensic. CodeBurn covers daily cost tracking; cctx is "what went sideways here, and what do I add to CLAUDE.md so it doesn't happen again."
+- **Token-turns is a useful metric for stale-content attribution.** `tokens × turns_present`, compaction-aware. A 22K grep result sitting in context for 14 turns after its last reference costs ~310K token-turns of waste. This is how stale-context findings attribute their dollar cost.
+- **Approximate decomposition is fine.** Reconstructing the API request from the JSONL gets you ~85–95% of the actual `input_tokens`. The remainder is internal framing you can't observe. The system internals slice is honest; don't pretend to be exact.
+- **Binary waste detection only in v1.** "Loaded but never called" is high-confidence. "Partially used" is fragile. Ship the binary version.
+- **Patches must be copy-pasteable.** Every Patch carries a unified diff against a target file (CLAUDE.md, rules, skill, ADR). Lower the barrier to action to zero.
+- **Single-session AND cross-session, same diagnostician.** `cctx autopsy <session>` and `cctx autopsy <project> --since <window>` go through the same per-session pipeline; the aggregator runs after.
+- **Group up, never down.** Parse at the finest granularity the source provides (per JSONL line). Aggregate in the view layer. (Originated in the parser design — applies everywhere.)
+- **Empirical evidence collapses speculative complexity.** Before designing for a hypothetical case, scan real data. The parser spec's tool-result handling was simplified by 80% after one 30-line empirical scan.
+- **Deterministic over LLM-assisted in v0.** Pattern classifiers use heuristics, not LLM calls. (Future v1+ harvest may invoke an LLM for summarization, opt-in with API key.) The deterministic core has predictable cost and is testable on fixtures.
+
+## Build order (post-pivot)
+
+1. **M0 — Project setup.** SHIPPED. (#1)
+2. **M1 — Foundation.** SHIPPED — parser, tokenizer, models, fixtures, CI. (#2–#6, plus PR #38)
+3. **M2 — Autopsy v0.** SHIPPED — single-session diagnosis + cross-session pattern detection. The wedge product. (#9, #10, #40–#49)
+4. **M3 — Trace TUI** with autopsy overlay. SHIPPED. (PR #57)
+5. **M4 — Export.** SHIPPED — jsonl + csv exporters (html moved to autopsy --html; json deferred). (PR #54)
+6. **M5 — Harvest v1.** SHIPPED — CLAUDE.md target only in v0; promote autopsy findings to durable CLAUDE.md diffs. (PR #56)
+7. **M6 — Release v0.1.0.** Release prep underway — README, PRODUCT.md, DESIGN.md, version bump, PyPI publish. (#31, #32)
+
+Future, not yet milestoned:
+- **Memory hygiene** (`cctx harvest --check`) — audit existing CLAUDE.md and memory files for staleness / contradictions / dead skills.
+- **Live mode** (`cctx watch`) — filesystem watcher on `~/.claude/projects` to surface waste signals during a session.
+- **Cross-agent layer** — emit the same captured knowledge as `.cursorrules`, `AGENTS.md`, `.windsurfrules`, GitHub Copilot instructions.
+
+## Design docs
+
+Feature designs live in `docs/superpowers/specs/`, dated and committed before implementation begins. Each implementation plan in `docs/superpowers/plans/` references its spec. Don't start a feature without one.
+
+Current specs landed on main:
+- `docs/superpowers/specs/2026-05-12-claude-code-parser-design.md` — the Claude Code JSONL parser.
+
+In progress / pending:
+- `docs/superpowers/specs/<date>-autopsy-design.md` — autopsy v0 design (#40). The next spec to be brainstormed.
+
+## GitHub issue structure
+
+The post-pivot board is anchored to autopsy. New work should follow the same conventions so the board stays coherent.
+
+**Granularity.** One issue = one PR. If a ticket can't reasonably land in a single PR, split it. Cross-cutting infrastructure gets its own ticket rather than being buried inside the first consumer. Test fixtures that block a feature get their own ticket. High-polish or novel surfaces (e.g. the TUI) split into spec + implementation.
+
+**Milestones.** Phases get milestones (`M0 — Project setup` through `M6 — Release v0.1.0`). Every issue belongs to exactly one milestone. Add a new milestone if a phase is genuinely new; don't reuse an existing milestone for unrelated work.
+
+**Labels.** Use `area:*` labels only (parser, analyzer, cli, renderer, exporter, tokenizer, tui, models, infra, docs). An issue can have multiple `area:` labels if it touches multiple layers. Don't invent new label taxonomies (priority, type, status) — milestones + the issue board cover that.
+
+**Body template.** Every issue has these sections, in this order:
+
+```markdown
+**Phase:** Mn — <phase name>
+**Module:** `path/to/file.py` (or files plural)
+
+## Goal
+One paragraph: what this delivers and why.
+
+## Acceptance criteria
+- [ ] Spec at `docs/superpowers/specs/<date>-<slug>.md` reviewed first (if a spec is warranted — see below)
+- [ ] Concrete, testable items
+- [ ] Tests that prove the behavior
+- [ ] Layering invariants honored (e.g. "no imports from `anthropic`")
+
+## Files
+- Exact paths the PR touches
+
+## References
+- Brief sections, prior spec sections, CLAUDE.md sections
+
+## Blocked by
+- (Posted as a comment with `#N` references after all related issues are filed — GitHub auto-links and surfaces the dependency graph.)
+```
+
+**Spec gate inside the ticket.** CLAUDE.md requires specs before implementation. The default is **the spec is the first acceptance-criteria checkbox in the implementation ticket**, not a separate ticket. Exceptions: surfaces big enough that the spec is itself a meaningful deliverable (the autopsy v0 design is #40 — separate from the implementation tickets that consume it).
+
+**Dependencies.** After filing a batch of issues, post a comment on each blocked ticket: `Blocked by #N, #M`. GitHub auto-links and shows the parent/child relationship in the timeline. Don't try to encode the dep graph in the issue body — it goes stale and is painful to maintain.
+
+**Granularity smell tests** (use these when proposing a new ticket):
+- *Too thick* — needs two specs, two reviewers, or PRs in two different areas (`area:parser` + `area:cli`). Split along the layering boundary.
+- *Too thin* — the entire ticket fits in a 5-line PR with no tests. Combine with its sibling.
+- *Hidden dependency* — the work assumes something exists that isn't filed yet. File that first or note it as blocked-by.
+
+## Working in this repo
+
+- The brief is authoritative for product scope. Don't rewrite it during implementation; if scope needs to change, amend the brief deliberately.
+- Specs are authoritative for module design. Don't deviate during implementation without updating the spec.
+- When implementing a feature: write the spec, get it reviewed, then write the plan (via the superpowers `writing-plans` skill), then implement.
+- The parser is dependency-free by design. If you find yourself adding `import anthropic` or `import click` inside `parsers/`, stop — that work belongs in `tokenizer.py` or `cli.py`.
+- The tokenizer's offline mode (`CCTX_OFFLINE=1`) is the default for CI and tests. Live tokenization happens only when the CLI explicitly opts in and `ANTHROPIC_API_KEY` is set.

cctx_cli-0.1.0/DESIGN.md

@@ -0,0 +1,54 @@
+# cctx Design System
+
+Reference for the three output surfaces: Rich terminal, Textual TUI, Jinja2 HTML report.
+
+## Color palette (terminal/TUI)
+
+| State | Rich style |
+|---|---|
+| HIGH severity | `bold red` |
+| MEDIUM severity | `bold yellow` |
+| LOW severity | `bold green` |
+| Applied/success | `green` |
+| Error/failure | `red` |
+| Skipped/neutral | `dim` |
+
+## Cost formatting
+
+| Context | Format | Example |
+|---|---|---|
+| User-facing summary (verdict, totals) | `:.2f` | `$1.42` |
+| Per-finding detail | `:.4f` | `$0.0082` |
+
+## Finding kind labels
+
+Canonical display form is space-separated uppercase. Never use the raw enum value in user-facing output.
+
+| Enum value | Display label |
+|---|---|
+| `retry_loop` | `RETRY LOOP` |
+| `scope_creep` | `SCOPE CREEP` |
+| `stale_context` | `STALE CONTEXT` |
+
+Use `_KIND_LABEL` dict in `renderers/terminal.py` as the source of truth. The HTML template currently uses `.replace("_", " ").upper()` inline — this is equivalent for the three current kinds but will diverge if a new kind uses a non-underscore separator.
+
+## Verdict string
+
+Format across all surfaces: `"Clean session"` (no findings) or `"{n} finding(s) · ${waste:.2f} waste"` (with findings).
+
+The brief examples use `"⚠ retry loop + scope creep"` (kind-based) — that is a future format, not yet implemented.
+
+## Evidence rendering
+
+| Surface | Rendering |
+|---|---|
+| Terminal | `finding.summary` inline text |
+| HTML report | Per-finding `<details>` with evidence as formatted JSON (TODO: structured per-kind in v0.2) |
+| TUI FindingModal | Summary + raw evidence (TODO: structured per-kind in v0.2) |
+
+## Anti-patterns
+
+- **Never** use `red` style for success states (APPLIED patch = success = green)
+- **Never** render evidence dicts as raw `json.dumps` in the primary user-facing path (HTML verdict area is OK for v0; structured per-kind in v0.2)
+- **Never** define CSS syntax-highlighting classes without corresponding template markup to apply them
+- **Never** import `click` or `rich_click` outside `cli.py`

cctx_cli-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: cctx-cli
+Version: 0.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 is 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. 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).
+
+### `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 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.
+
+## License
+
+MIT

cctx_cli-0.1.0/PRODUCT.md

@@ -0,0 +1,109 @@
+# PRODUCT.md — cctx
+
+## What is this
+
+cctx is a local Python CLI that reads Claude Code session logs and tells you what went wrong, why it cost what it did, and what to add to your CLAUDE.md so it doesn't happen again.
+
+It is a forensic tool, not a monitoring tool. You reach for it after a session — when something felt off, when the bill was higher than expected, or on a weekly review pass.
+
+## Primary persona
+
+**The regular Claude Code user** who:
+- Runs multiple Claude Code sessions per day across one or more projects
+- Maintains a CLAUDE.md and wants it to get smarter over time
+- Is willing to read a terminal report and act on its suggestions
+- Cares about cost and session quality but does not need a dashboard
+- Is comfortable with the command line and with `~/.claude/projects/` on disk
+
+This persona is already the target; everything shipped to date serves them directly.
+
+## What cctx is NOT for
+
+- Teams or organizations (no shared reports, no access control, no multi-user state)
+- Real-time monitoring (completed sessions only in v0 and v1)
+- General cost dashboards (CodeBurn covers that; cctx is forensic)
+- Multi-provider support (Claude Code only in v0/v1)
+- Users who do not read session transcripts or maintain CLAUDE.md
+
+## Product principles
+
+**1. Forensic, not ambient.**
+cctx is used after something goes wrong, not as background infrastructure. Every feature should be justified by this use case: "I just ran a session, something went sideways, I want to know what."
+
+**2. Output must be actionable.**
+Every report should produce at least one thing the user can do immediately. Findings without patches are incomplete. Patches must be copy-pasteable or auto-applicable.
+
+**3. Honest about uncertainty.**
+Costs are approximated (85–95% of actual). Pattern classifiers fire only on high-confidence signals. Low-confidence signals are shown with explicit confidence labels. "System internals" token budget is never hidden or misattributed.
+
+**4. Local and stateless.**
+No network calls in the core analysis path (tokenizer may call the API for token counting; that is opt-in). No persistent database. No telemetry. No account. Users own their data.
+
+**5. Deterministic.**
+Pattern classifiers are heuristics, not LLM calls. The same session file produces the same output every time. Testable on fixtures. Predictable cost to run.
+
+**6. Small surface, deep on each command.**
+Four commands. No command is shallow. Users should be able to learn the product in an afternoon and trust what it tells them.
+
+## Feature map (v0.1.0)
+
+### Shipped
+
+| Feature | Command | Status |
+|---|---|---|
+| Single-session diagnosis | `cctx autopsy <session>` | Shipped (M2) |
+| Cross-session pattern detection | `cctx autopsy <project> --since N` | Shipped (M2) |
+| HTML report | `cctx autopsy <session> --html FILE` | Shipped (M2/PR#59) |
+| Session trace TUI | `cctx trace <session>` | Shipped (M3) |
+| JSONL export | `cctx export <session> --format jsonl` | Shipped (M4) |
+| CSV export | `cctx export <session> --format csv` | Shipped (M4) |
+| Harvest (CLAUDE.md patcher) | `cctx harvest <session>` | Shipped (M5) |
+| Cross-session harvest | `cctx harvest <project> --since N` | Shipped (M5) |
+
+### Pattern classifiers (v0.1.0)
+
+| Pattern | Status |
+|---|---|
+| Retry loop | Shipped |
+| Scope creep | Shipped |
+| Stale context | Shipped |
+| Dead-end exploration | Not shipped in v0 |
+| Tool thrashing | Not shipped in v0 |
+
+### NOT in v0.1.0
+
+- `--format json` and `--format html` on `export` (html moved to `autopsy --html`; json not scheduled)
+- `--since` string formats (`7d`, `2w`, date ranges, `--until`, `--top N`) — accepts integer days only
+- Patch targets other than `CLAUDE.md` (rules, skills, ADR — v1+)
+- Interactive aggregate drill-down ("press N to inspect pattern") — read-only in v0
+- `cctx ls` / session discovery helper
+- Dead-end and tool-thrash classifiers
+
+## What we are NOT building
+
+- A SaaS or cloud product
+- An agent (cctx reads logs; it does not call the Anthropic API except optionally for token counting)
+- A real-time watcher (v2+ roadmap item)
+- Multi-provider support (v3+ roadmap item)
+- A fork-and-replay debugger
+- A general eval or testing framework
+
+## Known problems (as of 2026-05-15)
+
+**Release blockers for v0.1.0 (M6):**
+
+1. **No README.md.** `pyproject.toml` uses `cctx-project-brief.md` as the readme. The brief contains architecture diagrams and an internal "First session prompt" that should not be on PyPI. A user-facing README.md is required before publish.
+
+2. **`pyproject.toml` description is inaccurate.** Current: "Profile, debug, and optimize Claude Code and Agent SDK sessions." Accurate: "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md."
+
+3. **Version is `0.0.1`.** M6 requires bumping to `0.1.0`.
+
+4. **Brief example outputs show unshipped features.** The `cctx-project-brief.md` (which currently IS the readme) shows 5 pattern classifiers, 4 export formats, string `--since` arguments, a `Verdict` headline, and interactive aggregate output. None of these are accurate for the shipped CLI. Before PyPI publish, either ship them or update the brief.
+
+**Active gaps (non-blocking for v0.1.0 but worth tracking):**
+
+5. **Cost approximation honesty not surfaced in output.** The terminal renderer shows `$X.XX` total cost with no confidence annotation. The brief says "The system internals slice is honest; don't pretend to be exact" — this is a principle not yet expressed to users in output.
+
+6. **No session discovery helper.** Users must manually navigate URL-encoded project directories in `~/.claude/projects/` to find session files. First-run friction.
+
+7. **Aggregate output is read-only.** The brief's example shows an interactive aggregate view. Shipped aggregate is a static table. The interactive drill-down is a meaningful UX gap that the brief implicitly promises.