cctx-cli 0.1.0__py3-none-any.whl

cctx_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,31 @@
+cctx/__init__.py,sha256=fgiHMk_CoF0UCot_yu-1KsIyOVOtpvGGBeZ0LkXKi94,100
+cctx/cli.py,sha256=2EOWnN3RFzZCEmcjF3snX3-fOtpPsOUEw8hrXnqvTTg,12315
+cctx/discovery.py,sha256=0Kytb1i9QssHejDWWQ6oTG_FJSqbxrvCdPFbLJsp1r8,5990
+cctx/harvest.py,sha256=_eayKTYJ2F0ke1d35Y-KZ0JWRQOBdyB49EGn3lapGp0,5451
+cctx/models.py,sha256=HZQfkANT1n4F6V8BoG4MbX8MwAnUAoQnXicWT3SiQhM,8207
+cctx/pricing.py,sha256=bL_ExFf6sEZKIpqCvggBix3NbP9iMm4sWbFd-yjEH7E,616
+cctx/tokenizer.py,sha256=OZweLUzPiKdyEQkmQEzQT_K4rQ_CDcnRtCQlcQS09Ww,2313
+cctx/diagnostician/__init__.py,sha256=2oRnaphdsfEiEAj2qxAcWzmzU_vMoHMIOiBwufFVoSM,2808
+cctx/diagnostician/aggregate.py,sha256=AlDzBvMV0EnWF-SSFw3A0VjGA0rrOYkXDuocHLsENxU,1264
+cctx/diagnostician/inflection.py,sha256=662llgSnXj4d8I7t7LZC8Lv6yvp2NYtWNQtZPicr-b8,606
+cctx/diagnostician/patterns/__init__.py,sha256=33Ps2ct4yXXpx-hHg03zGug4DmkgzOlmxoAXmP-GuIk,27
+cctx/diagnostician/patterns/retry_loop.py,sha256=5tNUSD02pms5GSdgzSAX9mF2jNM1iaBiXxSXVrI-yvk,4555
+cctx/diagnostician/patterns/scope_creep.py,sha256=bTNI5nUoRiUZjg5NI5bKslqkH_9vBvP15sJWzTos6as,2500
+cctx/diagnostician/patterns/stale_context.py,sha256=Gq0fxVEmfV9it30IVNYebd9cn1ILIiOOVJ7SCl0goz0,4987
+cctx/exporters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cctx/exporters/csv.py,sha256=0Zhv0z8l7elEf0jdLR_vgT4dT5TG6hJqMj63P-IJLWA,2005
+cctx/exporters/jsonl.py,sha256=6BYdME4-8lVri1CCZy4ravybcghCjACqpxGlZVM1uz8,1841
+cctx/parsers/__init__.py,sha256=i_Y3dbwhGddRB66GTvy29rMmrFcfMktFophCRHplXZM,39
+cctx/parsers/claude_code.py,sha256=13ltJ6mVR1vgjkw02EKEPq51W5Mxu-7GbBkyCKu81H8,23869
+cctx/recommender/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cctx/recommender/claude_md.py,sha256=jUNlPAg6kDGb_MDpHxCZ0prGkmFdeM2U0iO_VwSjtr0,4981
+cctx/recommender/evidence.py,sha256=ND33Z4Z_udqiMMCaPBbyIjAyWBlIQHFJtoUBMD_fRZE,1720
+cctx/renderers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cctx/renderers/report.py,sha256=D9bEnnlxrXWrzn5qcy_oE_seUqxd-Q5O36m3pp9cHAk,1963
+cctx/renderers/terminal.py,sha256=fC0TWv4asOYYey8TvJCNdIZcabMMGEQINEqNvv6AO0w,8055
+cctx/renderers/trace_tui.py,sha256=FmtVT3o4hvB3T9NYyafOb4cw6spv6ts8bPBtVBDBs9c,10636
+cctx/renderers/templates/autopsy.html.j2,sha256=P0ggSvpB7-ykJp6rQGF_MXKJh85iCTY3glI7JSeDBY4,8213
+cctx_cli-0.1.0.dist-info/METADATA,sha256=k4JYA4wsKTTdfoobwg25g69P3Agtag9MNoJ6U_1ZVeU,6117
+cctx_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cctx_cli-0.1.0.dist-info/entry_points.txt,sha256=Jdaxy27-9Top4lGdKW8Oaj_ETIS7sfEc-lw9R4Z_HkM,38
+cctx_cli-0.1.0.dist-info/RECORD,,

cctx_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cctx_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cctx = cctx.cli:cli