Metadata-Version: 2.5
Name: lykos-cctx
Version: 0.3.0
Summary: Claude Code context utility - view, fork, trim, and price session transcripts
Project-URL: Repository, https://github.com/ionite34/cctx
Project-URL: Issues, https://github.com/ionite34/cctx/issues
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,cost,tokens,transcripts
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: orjson>=3.10
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# cctx

Claude Code context utility: see what a session costs, cut it where you want, and put a price on the subscription buckets.

Reads the transcripts Claude Code writes under `~/.claude/projects/` and never modifies them in place unless you ask (`trim`, `repair`). Every other operation writes a new file.

```bash
pip install lykos-cctx
```

The command is `cctx`. A `<session>` argument is a session-id prefix, an agent id, a title fragment, or a path to a `.jsonl`.

## Sessions

| command | what it does |
|---|---|
| `cctx list` | sessions across all projects; `--agents` includes subagent transcripts |
| `cctx show <session>` | numbered turns, so you can pick a cut point |
| `cctx fork <session>` | plain copy, what fork-before-compact does |
| `cctx fork <session> --until 42` | rewind: keep turns 1 to 42 |
| `cctx fork <session> --from 43` | trim: drop turns 1 to 42, insert a native boundary marker |
| `cctx splice <src> --onto <dst>` | append a range of turns onto another session |
| `cctx verify <session>` | integrity check: parse, chain, parent links |
| `cctx repair <session>` | fix broken `parentUuid` links that silently truncate context |

## Cost

| command | what it does |
|---|---|
| `cctx rounds <session>` | context added per turn, carry cost, tool hogs, cold-cache rewrites with their cause, and every subagent the session spawned |
| `cctx tokens <session>` | per-call context growth |
| `cctx compact <session>` | what each compaction saved and what the next turns paid |
| `cctx cost` | spend by day, model, project and session across the machine, fork-deduplicated |
| `cctx limits` | what a percent of the 5h, 7d and Fable buckets costs, from the [cc-shim](https://github.com/ionite34/cc-shim) usage ledger |

Costs are API-equivalent dollars from a built-in price table and ITE, input-token-equivalents, a model-agnostic unit (cache write 1.25×, cache read 0.10×, output 5× an input token).

## What it knows about the format

[docs/FORMAT.md](docs/FORMAT.md) is a measured reference for the transcript format: the linked-list structure, the four kinds of `user` record, how usage is restated across a call's records, subagent transcripts, wake-up records, and what the transcripts do not contain. Everything in it was verified against real files and says so.

## Development

```bash
pip install -e . pytest
pytest -q
```

Releases are tags: push `vX.Y.Z` and CI tests, builds, publishes to PyPI and creates the GitHub release. The version comes from the tag.
