v1.1.0 — a report a normal person can read

The report now explains itself in plain English — no need to know what a "reversal" or "fresh/deep context" means.

• Terminal report is split into labelled stages, each led by one plain sentence saying what it shows and why it matters.
• The opaque "prior reversal count" table is now "Do mistakes snowball?" — it defines a reversal and prints a data-driven takeaway.
• Fill chart, comparison tables, and composition panel gained legends and friendly column names ("Slip rate", "give-or-take" for the 95% CI).
• The HTML report carries the same glosses plus a one-line glossary under the hero.

No change to the analysis, the JSON schema, or any numbers — wording and layout only.

v1.0.2 — actionable 'not enough data'

When a run comes up short of a verdict, contextrot now tells you to widen the window (contextrot --days 90, or --days 0 for all history) instead of only "keep using your agent."

This is the trap a low-volume OpenCode user hit: their data was perfectly readable and gave a clear verdict at --days 90, but the default 30-day window didn't contain enough history. No change to the analysis itself.

v1.0.1 — OpenCode file-storage fix

Fixes active OpenCode users being read as "not enough data."

Recent OpenCode stores sessions as JSON files under <data>/storage/{session,message,part,project}/… instead of the single opencode.db the adapter required, so a daily user's history was invisible and the run fell back to "insufficient."

The OpenCode adapter now:

• reads the current file-based storage, with the SQLite opencode.db path kept as a fallback for older installs
• probes the real per-OS data directories (Linux/macOS ~/.local/share/opencode, Windows %APPDATA%/%LOCALAPPDATA%) plus OPENCODE_DATA_DIR / XDG_DATA_HOME — no --data-dir needed
• supports per-session --days filtering (each session file carries its own mtime)

No API changes. pip install -U contextrot / uvx contextrot@latest.

1.0.0 — contextrot is stable

Your coding agent gets worse as its context fills. contextrot proves it on your own sessions — and tells you exactly what to change. As of today, that's a stable, complete tool.

What 1.0 means

Fifteen releases in ten days, and every capability is now considered stable surface:

Eight agents, one analysis. Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Cline, Roo Code, Kilo Code — contextrot reads the transcripts they already write to disk and normalizes them into one honest report.

Four questions answered:

• Where do I degrade? — the rot curve, your personal knee, Wilson CIs (contextrot)
• What's causing it? — five behavioral failure signals + the reversal axis ("is it what's in your context, or how full it is?")
• What do I change? — quantified prescriptions and contextrot fix (dry-run, backed up, reversible)
• Did it work? — contextrot trends, week-over-week with the same statistical honesty

Three comparison axes. By model (Opus vs Sonnet), by project (which repo rots first), by agent (which CLI rots first) — all on your workload, not a benchmark's.

Live surfaces. A Claude Code statusline colored by your measured curve instead of a hardcoded 70%; a hook that warns once when you cross your threshold; an MCP server so your agent can query your rot mid-session; a local SVG verdict badge.

The contract, unchanged since 0.1.0:

• Zero network calls. Local files in, terminal/HTML/JSON out. Grep the codebase for an HTTP client — there isn't one.
• Statistics that can say "you're fine." Thresholds only get declared when they clear noise. A tool that can honestly report no rot is one you can trust when it reports rot.
• Your config is sacred. Every write is dry-run by default, backed up, and reversible.

From 1.0, the CLI command surface and --json schema are stable — additions stay additive within 1.x.

Get it

uvx contextrot        # or: pip install contextrot / npx contextrot

Thanks to the community contributors who shipped the OpenCode adapter and the reversal axis. An adapter for your agent is still the paved first-contribution path — see CONTRIBUTING.

0.12.1 — fix MCP rate typing

Patch release: the MCP server's rot_report and agents_ranking rounded nullable fresh/deep failure rates, which failed CI's type check. Rates now pass through as null when a curve half has no data. No change when data is present.

uvx contextrot or pip install contextrot.

0.12.0 — local SVG verdict badge

Show your receipts.

contextrot badge writes a shields-style SVG of your measured verdict — context rot | clean ✓, edge · knee ~70%, or rot ✗ 3.2× — rendered entirely on your machine. Embed it in a README, blog post, or GitHub profile without any badge service seeing your data.

• Verdict colors match the terminal and HTML reports.
• contextrot badge out.svg --days 90 — same filters as the report (--project, --data-dir, --window).
• Also in this release: contextrot trends defaults to a 90-day window (a 30-day trend has too few weeks to say anything).

uvx contextrot or pip install contextrot.

0.11.0 — trends: is your context hygiene actually improving?

The report tells you where you degrade. contextrot fix tells you what to change. 0.11.0 tells you whether it worked.

Improving: failure rate 8.9% → 6.6% — the drop clears statistical noise.

│ Week of │ Steps │ Failure │ 95% CI │ Avg fill │ Startup tokens │
│ Jun 15  │  2806 │    8.6% │  8%–10% │      49% │         23,333 │
│ Jun 29  │  4992 │    6.1% │   5%–7% │      53% │         27,793 │
│ Jul 06  │  3142 │    4.5% │   4%–5% │      67% │         41,482 │

contextrot trends

• Week-over-week failure rate with Wilson CIs, average context fill, and session startup overhead — so a creeping CLAUDE.md or MCP schema bloat is visible as a number going up.
• Improving / worsening / flat verdict, declared only when the pooled intervals of the earlier and later halves don't overlap. One good week proves nothing, and the trend says so.
• Closes the loop fix opened: change your setup, keep working, re-run trends, watch the numbers move (or not) — the before/after measurement from the roadmap.
• --json steps now carry an additive per-step timestamp.

uvx contextrot or pip install contextrot.

0.10.0 — MCP server: your agent can now ask how rotted you are

Every contextrot surface so far talked to you. 0.10.0 talks to your agent.

MCP server

claude mcp add contextrot -- contextrot mcp

Any MCP-capable agent (Claude Code, and every other client speaking MCP) gets three tools:

• rot_report — verdict, degradation threshold, fresh-vs-deep failure rates, cost of degraded steps, prescriptions
• agents_ranking — which of your coding agents degrades first, measured on your own workload
• prescriptions — the quantified recommendations from your data

The agent can query mid-session and act on the answer: compact before your measured knee, warn you, or pick a different model for deep-context work.

Implementation notes

• MCP stdio transport (JSON-RPC 2.0, newline-delimited, spec 2025-06-18) implemented in the standard library — dependency count unchanged (typer, rich, jinja2).
• Version negotiation, ping, in-band tool errors per spec.
• Zero network calls, same as always: stdio is a pipe to the parent process, not a socket.

uvx contextrot or pip install contextrot.

0.9.0 — knee-crossing warning hook for Claude Code

0.8.0 put your degradation curve in the statusline. 0.9.0 makes it tap you on the shoulder.

contextrot: context 75% — past your measured degradation threshold (~70%). Your failure rate here is 2.0× fresh-context. Consider /compact or a fresh session.

Knee-crossing hook

• contextrot install hook registers a Claude Code PostToolUse hook that watches the live session and warns once when context fill crosses your measured threshold — the knee contextrot found in your own history, not a hardcoded 70%.
• Fill comes from a tail read of the live transcript (fast even on multi-megabyte sessions); threshold and failure rates come from the calibration cache every report run refreshes.
• Warns once, then stays quiet. Re-arms automatically after /compact drops you back below the knee.
• Honest by design: no calibration, too little data, or no knee in your curve → the hook says nothing. A warning you can trust is one that doesn't cry wolf.
• Installer safety: dry-run by default, --apply + confirm, .contextrot.bak backup, appends without touching your existing hooks, contextrot uninstall hook removes only contextrot's entry.

Pair both: contextrot install statusline --apply && contextrot install hook --apply — passive gauge + active nudge, calibrated to you.

Still zero network calls. uvx contextrot or pip install contextrot.

0.8.0 — live statusline for Claude Code, calibrated to your own curve

The report told you where you degrade. Now the statusline tells you while it's happening.

ctx 72% ███████░░░ · ▲ past your knee (~70%) · fail here 4.8% (1.5× fresh)

Live statusline

• contextrot install statusline wires a context-health segment into Claude Code's status bar: current fill, colored against your measured degradation curve — green below your knee, yellow approaching it, red past it — plus your historical failure rate at the current fill.
• Generic statusline tools go yellow at a hardcoded 70%. This one goes red where your data says you start failing. Uncalibrated setups fall back to generic 70/90 thresholds and say so.
• Same safety contract as contextrot fix: dry-run by default, --apply + confirmation to write, .contextrot.bak backup, and an existing non-contextrot statusLine is never touched without --force. contextrot uninstall statusline reverses it.

Calibration cache

Every full report run snapshots your curve (knee, verdict, per-bucket rates) to ~/.contextrot/calibration.json so live surfaces answer in milliseconds. It's a cache, not state — delete it freely. Runs with --data-dir never write it, so fixtures and other machines' exports can't poison your calibration.

Still zero network calls. Install: uvx contextrot or pip install contextrot.