Metadata-Version: 2.4
Name: contextrot
Version: 0.1.1
Summary: Find out where your coding agent starts degrading. Personal context-rot analytics from your own agent sessions.
Project-URL: Homepage, https://github.com/Priyanshu-byte-coder/contextrot
Project-URL: Repository, https://github.com/Priyanshu-byte-coder/contextrot
Project-URL: Issues, https://github.com/Priyanshu-byte-coder/contextrot/issues
Author: Priyanshu Doshi
License: MIT
License-File: LICENSE
Keywords: agents,claude-code,context-engineering,context-rot,developer-tools,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# contextrot

**Your coding agent gets worse as its context fills. contextrot proves it on your own sessions — and tells you exactly what to change.**

[![CI](https://github.com/Priyanshu-byte-coder/contextrot/actions/workflows/ci.yml/badge.svg)](https://github.com/Priyanshu-byte-coder/contextrot/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/contextrot)](https://pypi.org/project/contextrot/)
[![Python](https://img.shields.io/pypi/pyversions/contextrot)](https://pypi.org/project/contextrot/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

```
uvx contextrot
```

No config. No API keys. No uploads. contextrot reads the agent transcripts already sitting on your disk and answers a question no other tool answers:

> **At what context fill does *my* agent start failing, what's causing it, and what is it costing me?**

```
╭──────────────── contextrot — your context rot report ────────────────╮
│                                                                    │
│  Deep-context failure rate: 31.4% vs 14.9% in fresh context        │
│  (2.1×, statistically separated)                                   │
│  Your degradation threshold: ~60% context fill                     │
│  Est. spend on degraded steps: $23.40 of $148.02 total             │
│                                                                    │
╰────────────────────────────────────────────────────────────────────╯

           Failure-signal rate by context fill
   Fill    Rate                                            n   95% CI
  0–10%     9%  ████████                                 214   6%–13%
 10–20%    12%  ███████████                              308   9%–16%
 20–30%    14%  █████████████                            257  10%–18%
 ...
 60–70%    29%  ███████████████████████████              121  22%–37%
 70–80%    34%  ████████████████████████████████          87  25%–44%
```

## What "context rot" is — and why a benchmark can't tell you

Research ([Chroma's context-rot report](https://www.trychroma.com/research/context-rot), several 2026 papers) shows LLM output quality degrades as input context grows — even far below the window limit. But that research runs synthetic tasks in lab conditions. Your degradation point depends on *your* projects, *your* MCP setup, *your* model, *your* prompting style.

contextrot measures it where it actually matters: in your own sessions.

## How it works

Agent CLIs like Claude Code log every session to local JSONL transcripts. Each step in those transcripts carries token accounting *and* behavioral evidence:

- **edit failures** — the agent tried to edit code and missed
- **retry loops** — the same tool call repeated after an error
- **re-reads** — the agent re-reading files it already read (it lost track)
- **self-corrections** — "I apologize, let me fix that"
- **tool errors** — any failed tool call

contextrot extracts these signals per step, computes context fill at that moment, and correlates the two — with Wilson 95% confidence intervals, per-signal breakdowns, and honest n-counts. Then it estimates what degraded steps cost you and emits prescriptions quantified from your own data.

Full method: [docs/methodology.md](docs/methodology.md).

## What contextrot is not

Be suspicious of any tool that won't tell you this, so:

- **Not a spend meter.** [ccusage](https://github.com/ryoppippi/ccusage) is excellent at "how much did I spend" — use it, it's complementary. contextrot answers "where does my agent *degrade* and why."
- **Not Claude Code's `/context`.** That's a point-in-time composition snapshot. contextrot correlates fill with *outcomes* across your whole history.
- **Not an observability platform.** Langfuse/Phoenix/MLflow instrument apps you build. contextrot needs zero instrumentation and analyzes the agent you *use*.
- **Not a controlled experiment.** It's an observational diagnostic on your own data, with the statistical caveats printed right on the report.

## Install & use

```bash
uvx contextrot            # zero-install run
# or
pip install contextrot
```

```bash
contextrot                        # full report, last 30 days
contextrot --days 90              # widen the range
contextrot -p myproject           # one project only
contextrot --html report.html     # shareable single-file report (still local)
contextrot --json                 # machine-readable
contextrot sessions               # list what was parsed
```

Supported agents: **Claude Code** (today). Codex CLI, OpenCode, Gemini CLI, and OpenTelemetry GenAI spans are next — an adapter is one small file, and [writing one is the paved first-contribution path](CONTRIBUTING.md).

## Privacy

contextrot makes **zero network calls**. It reads local transcript files, prints to your terminal, and optionally writes a local HTML file. Nothing leaves your machine. Grep the codebase for `http` — you won't find a client.

## Roadmap

- `contextrot fix` — apply prescriptions interactively (disable unused MCP servers, trim CLAUDE.md) with before/after measurement
- More agent adapters + OTel ingestion
- Opt-in, anonymized aggregate stats → the **State of Context Rot** report: real-workload degradation curves across the community (off by default, documented schema, aggregate-only)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). The most valuable first PR: an adapter for the agent CLI you use.

## License

[MIT](LICENSE)
