agentwaste 0.1.0__tar.gz

agentwaste-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.DS_Store
+docs/node_modules/
+docs/dist/
+docs/.astro/

agentwaste-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release of agentwaste, pivoted from the AgentSight SDK (now in
+`legacy/agentsight`).
+
+- Claude Code transcript reader.
+- Six detectors: idle cache rebuild, uncached context (Claude, and
+  informational for self-hosted models), re-read, duplicate call, huge result,
+  error thrash.
+- Terminal report with fixes, `--json`, shareable `--card`, optional
+  `--usd-per-mtok`, and `--demo` synthetic sessions.
+- Documentation site (Astro Starlight) at https://nikghodki.github.io/agentwaste/.

agentwaste-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NIKHIL GHODKI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentwaste-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: agentwaste
+Version: 0.1.0
+Summary: Find where your AI coding agent wastes tokens, and how to stop it
+Project-URL: Homepage, https://github.com/nikghodki/agentwaste
+Project-URL: Documentation, https://nikghodki.github.io/agentwaste/
+Project-URL: Issues, https://github.com/nikghodki/agentwaste/issues
+Project-URL: Changelog, https://github.com/nikghodki/agentwaste/blob/main/CHANGELOG.md
+Author-email: nikghodki <nikghodki@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,cli,cost,developer-tools,llm,prompt-caching,tokens
+Classifier: Development Status :: 3 - Alpha
+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 :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# agentwaste
+
+**Your AI coding agent is wasting tokens. Find out where, and how to stop it.**
+
+[![CI](https://github.com/nikghodki/agentwaste/actions/workflows/ci.yml/badge.svg)](https://github.com/nikghodki/agentwaste/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-nikghodki.github.io%2Fagentwaste-ff7a59)](https://nikghodki.github.io/agentwaste/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/nikghodki/agentwaste/tree/main/LICENSE)
+
+[**Documentation**](https://nikghodki.github.io/agentwaste/) ·
+[Quickstart](https://nikghodki.github.io/agentwaste/quickstart/) ·
+[How it works](https://nikghodki.github.io/agentwaste/how-it-works/) ·
+[Contributing](https://github.com/nikghodki/agentwaste/blob/main/CONTRIBUTING.md)
+
+<img src="https://raw.githubusercontent.com/nikghodki/agentwaste/main/assets/report.png" alt="agentwaste report: 41% waste, grade D, with re-caching after idle breaks as the top finding and a fix for each pattern" width="820">
+
+</div>
+
+## Try it in 10 seconds
+
+```bash
+uvx --from git+https://github.com/nikghodki/agentwaste agentwaste
+```
+
+That's it: no install, no account, no config. It reads the Claude Code logs
+already on your machine and prints a report. No history yet? Add `--demo`.
+
+Want the `agentwaste` command permanently? Install it once:
+
+```bash
+uv tool install git+https://github.com/nikghodki/agentwaste      # or: pipx install git+https://github.com/nikghodki/agentwaste
+```
+
+The examples below use the installed command. Without installing, put
+`uvx --from git+https://github.com/nikghodki/agentwaste` in front of them.
+
+## Why
+
+Usage trackers tell you **how much** you used. agentwaste tells you **why**,
+and how much of it was avoidable.
+
+On one developer's month of Claude Code use, **about a third of all input cost
+was re-caching the conversation after stepping away for more than five
+minutes.** Nobody noticed, because nothing showed it.
+
+Whether you pay per token or hit subscription limits, that's waste you can fix
+in minutes once you can see it.
+
+## What it finds
+
+| | Pattern | What's happening | The fix |
+|---|---|---|---|
+| ⏸️ | **Idle cache rebuild** | You step away, the 5-minute prompt cache expires, and the next message re-writes the whole context at 1.25x | `/compact` before a break, or the 1-hour cache |
+| 🔁 | **Uncached context** | Every turn re-sends the conversation without caching, often because a proxy drops cache markers | Fix the proxy so caching survives |
+| 📄 | **Re-read** | The agent re-reads a file it already read, with no change in between | Put the facts in `CLAUDE.md` |
+| 🔍 | **Duplicate call** | The same search or fetch runs again with nothing changed | Reuse results, search more precisely |
+| 📦 | **Huge result** | One 10k+ token output, carried in every later message | `head`, filters, ranged reads |
+| 💥 | **Error thrash** | The same tool fails 3+ times in a row | Give the agent the missing context |
+
+Every finding comes with its cost, the worst offenders and a specific fix.
+[Exact definitions →](https://nikghodki.github.io/agentwaste/detectors/overview/)
+
+## Share your grade
+
+<img src="https://raw.githubusercontent.com/nikghodki/agentwaste/main/assets/card.png" alt="Shareable agentwaste card: grade D, 41% of input tokens wasted, top categories re-caching after idle breaks, huge tool outputs and uncached context" width="300" align="right">
+
+```bash
+agentwaste --card my-card.html
+```
+
+A one-file card with your grade and top waste categories, ready to screenshot
+and post. It contains **aggregates only**: no paths, project names, commands
+or code. A test enforces that on every change.
+
+<br clear="right">
+
+## More options
+
+```bash
+agentwaste --days 7               # last week only (default 30; 0 = everything)
+agentwaste --usd-per-mtok 3       # dollar estimates at $3 per million input tokens
+agentwaste --json > waste.json    # machine-readable, for scripts and dashboards
+agentwaste --demo                 # try it on synthetic sessions
+```
+
+Full reference: [CLI](https://nikghodki.github.io/agentwaste/reference/cli/) ·
+[JSON output](https://nikghodki.github.io/agentwaste/reference/json-output/)
+
+## Private by design
+
+- **Local and read-only.** No network requests, nothing uploaded, your logs are never changed.
+- **No dependencies.** Plain Python 3.10+, so there's nothing hidden to audit.
+- **Honest numbers.** Costs are in [token-equivalents](https://nikghodki.github.io/agentwaste/how-it-works/#token-equivalents)
+  that weight cache writes, cache reads and fresh input the way they're actually
+  billed. Self-hosted models are reported separately, since their cost is GPU
+  time, not tokens.
+
+## Roadmap
+
+- [x] Claude Code support, six detectors, report, JSON, shareable card
+- [ ] Codex support
+- [ ] `pip install agentwaste` / `uvx agentwaste` from PyPI
+- [ ] Live warnings while you work ("your cache expires in 1 minute")
+- [ ] Before/after comparison: did the fix actually help?
+
+Ideas and votes welcome in [issues](https://github.com/nikghodki/agentwaste/issues).
+
+## Contributing
+
+Contributions are very welcome, especially **new log sources** (Codex, Gemini
+CLI, OpenCode) and **new detectors**. Start with [CONTRIBUTING.md](https://github.com/nikghodki/agentwaste/blob/main/CONTRIBUTING.md):
+
+```bash
+git clone https://github.com/nikghodki/agentwaste && cd agentwaste
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]" && .venv/bin/pytest
+```
+
+The original AgentSight SDK lives on in [`legacy/agentsight`](https://github.com/nikghodki/agentwaste/tree/main/legacy/agentsight).
+
+## License
+
+[MIT](https://github.com/nikghodki/agentwaste/tree/main/LICENSE)

agentwaste-0.1.0/README.md

@@ -0,0 +1,124 @@
+<div align="center">
+
+# agentwaste
+
+**Your AI coding agent is wasting tokens. Find out where, and how to stop it.**
+
+[![CI](https://github.com/nikghodki/agentwaste/actions/workflows/ci.yml/badge.svg)](https://github.com/nikghodki/agentwaste/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-nikghodki.github.io%2Fagentwaste-ff7a59)](https://nikghodki.github.io/agentwaste/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/nikghodki/agentwaste/tree/main/LICENSE)
+
+[**Documentation**](https://nikghodki.github.io/agentwaste/) ·
+[Quickstart](https://nikghodki.github.io/agentwaste/quickstart/) ·
+[How it works](https://nikghodki.github.io/agentwaste/how-it-works/) ·
+[Contributing](https://github.com/nikghodki/agentwaste/blob/main/CONTRIBUTING.md)
+
+<img src="https://raw.githubusercontent.com/nikghodki/agentwaste/main/assets/report.png" alt="agentwaste report: 41% waste, grade D, with re-caching after idle breaks as the top finding and a fix for each pattern" width="820">
+
+</div>
+
+## Try it in 10 seconds
+
+```bash
+uvx --from git+https://github.com/nikghodki/agentwaste agentwaste
+```
+
+That's it: no install, no account, no config. It reads the Claude Code logs
+already on your machine and prints a report. No history yet? Add `--demo`.
+
+Want the `agentwaste` command permanently? Install it once:
+
+```bash
+uv tool install git+https://github.com/nikghodki/agentwaste      # or: pipx install git+https://github.com/nikghodki/agentwaste
+```
+
+The examples below use the installed command. Without installing, put
+`uvx --from git+https://github.com/nikghodki/agentwaste` in front of them.
+
+## Why
+
+Usage trackers tell you **how much** you used. agentwaste tells you **why**,
+and how much of it was avoidable.
+
+On one developer's month of Claude Code use, **about a third of all input cost
+was re-caching the conversation after stepping away for more than five
+minutes.** Nobody noticed, because nothing showed it.
+
+Whether you pay per token or hit subscription limits, that's waste you can fix
+in minutes once you can see it.
+
+## What it finds
+
+| | Pattern | What's happening | The fix |
+|---|---|---|---|
+| ⏸️ | **Idle cache rebuild** | You step away, the 5-minute prompt cache expires, and the next message re-writes the whole context at 1.25x | `/compact` before a break, or the 1-hour cache |
+| 🔁 | **Uncached context** | Every turn re-sends the conversation without caching, often because a proxy drops cache markers | Fix the proxy so caching survives |
+| 📄 | **Re-read** | The agent re-reads a file it already read, with no change in between | Put the facts in `CLAUDE.md` |
+| 🔍 | **Duplicate call** | The same search or fetch runs again with nothing changed | Reuse results, search more precisely |
+| 📦 | **Huge result** | One 10k+ token output, carried in every later message | `head`, filters, ranged reads |
+| 💥 | **Error thrash** | The same tool fails 3+ times in a row | Give the agent the missing context |
+
+Every finding comes with its cost, the worst offenders and a specific fix.
+[Exact definitions →](https://nikghodki.github.io/agentwaste/detectors/overview/)
+
+## Share your grade
+
+<img src="https://raw.githubusercontent.com/nikghodki/agentwaste/main/assets/card.png" alt="Shareable agentwaste card: grade D, 41% of input tokens wasted, top categories re-caching after idle breaks, huge tool outputs and uncached context" width="300" align="right">
+
+```bash
+agentwaste --card my-card.html
+```
+
+A one-file card with your grade and top waste categories, ready to screenshot
+and post. It contains **aggregates only**: no paths, project names, commands
+or code. A test enforces that on every change.
+
+<br clear="right">
+
+## More options
+
+```bash
+agentwaste --days 7               # last week only (default 30; 0 = everything)
+agentwaste --usd-per-mtok 3       # dollar estimates at $3 per million input tokens
+agentwaste --json > waste.json    # machine-readable, for scripts and dashboards
+agentwaste --demo                 # try it on synthetic sessions
+```
+
+Full reference: [CLI](https://nikghodki.github.io/agentwaste/reference/cli/) ·
+[JSON output](https://nikghodki.github.io/agentwaste/reference/json-output/)
+
+## Private by design
+
+- **Local and read-only.** No network requests, nothing uploaded, your logs are never changed.
+- **No dependencies.** Plain Python 3.10+, so there's nothing hidden to audit.
+- **Honest numbers.** Costs are in [token-equivalents](https://nikghodki.github.io/agentwaste/how-it-works/#token-equivalents)
+  that weight cache writes, cache reads and fresh input the way they're actually
+  billed. Self-hosted models are reported separately, since their cost is GPU
+  time, not tokens.
+
+## Roadmap
+
+- [x] Claude Code support, six detectors, report, JSON, shareable card
+- [ ] Codex support
+- [ ] `pip install agentwaste` / `uvx agentwaste` from PyPI
+- [ ] Live warnings while you work ("your cache expires in 1 minute")
+- [ ] Before/after comparison: did the fix actually help?
+
+Ideas and votes welcome in [issues](https://github.com/nikghodki/agentwaste/issues).
+
+## Contributing
+
+Contributions are very welcome, especially **new log sources** (Codex, Gemini
+CLI, OpenCode) and **new detectors**. Start with [CONTRIBUTING.md](https://github.com/nikghodki/agentwaste/blob/main/CONTRIBUTING.md):
+
+```bash
+git clone https://github.com/nikghodki/agentwaste && cd agentwaste
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]" && .venv/bin/pytest
+```
+
+The original AgentSight SDK lives on in [`legacy/agentsight`](https://github.com/nikghodki/agentwaste/tree/main/legacy/agentsight).
+
+## License
+
+[MIT](https://github.com/nikghodki/agentwaste/tree/main/LICENSE)

agentwaste-0.1.0/docs/sidebar.json

@@ -0,0 +1,18 @@
+[
+  { "label": "Get started", "items": ["quickstart", "how-it-works"] },
+  {
+    "label": "Detectors",
+    "items": [
+      "detectors/overview",
+      "detectors/idle-cache-rebuild",
+      "detectors/uncached-context",
+      "detectors/reread",
+      "detectors/duplicate-call",
+      "detectors/huge-result",
+      "detectors/error-thrash"
+    ]
+  },
+  { "label": "Guides", "items": ["guides/sharing-your-card", "guides/reducing-waste"] },
+  { "label": "Reference", "items": ["reference/cli", "reference/json-output", "privacy", "faq"] },
+  { "label": "Project", "items": ["contributing"] }
+]

agentwaste-0.1.0/docs/src/content/docs/contributing.mdx

@@ -0,0 +1,30 @@
+---
+title: "Contributing"
+description: "How to add a detector, a log source, or a fix."
+---
+
+agentwaste is MIT-licensed and contributions are welcome. The full guide is
+[CONTRIBUTING.md](https://github.com/nikghodki/agentwaste/blob/main/CONTRIBUTING.md); the
+short version:
+
+```bash
+git clone https://github.com/nikghodki/agentwaste
+cd agentwaste
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## Good first contributions
+
+- **A new log source.** Codex, Gemini CLI, OpenCode and others each need a reader in
+  `src/agentwaste/sources/` that returns `Stream` objects. Detectors then work unchanged.
+- **A new detector.** Add it to `src/agentwaste/detectors.py`, document it in
+  `docs/src/content/docs/detectors/`, and add it to the overview table. The docs tests
+  check that every detector key is documented.
+- **Better fixes.** If you know a better way to avoid a pattern, improve its fix text.
+
+## Rules of the road
+
+- Tests use **synthetic transcripts only**. Never commit real logs.
+- The shareable card must never contain paths, project names, commands or content.
+- Numbers quoted in the docs must match the code. `tests/test_docs.py` enforces this.

agentwaste-0.1.0/docs/src/content/docs/detectors/duplicate-call.mdx

@@ -0,0 +1,27 @@
+---
+title: "Duplicate call"
+description: "Running the same search or fetch twice."
+---
+
+**Key:** `duplicate_call`
+
+## What it is
+
+The agent repeats an identical read-only lookup, such as the same search or the same
+web fetch, when nothing could have changed the answer.
+
+## How it's detected
+
+A call to `Grep`, `Glob`, `LS`, `WebFetch` or `WebSearch` is flagged when an
+identical call (same tool, same input) already ran in the stream, with no `Edit`,
+`Write`, `MultiEdit`, `NotebookEdit` or `Bash` call in between.
+
+`Bash` commands are never counted as duplicates. Running `pytest` twice is usually
+deliberate.
+
+**Waste** = result tokens x 1.25.
+
+## How to fix it
+
+- Ask the agent to reuse earlier results.
+- Make the first search more specific so it doesn't need repeating.

agentwaste-0.1.0/docs/src/content/docs/detectors/error-thrash.mdx

@@ -0,0 +1,26 @@
+---
+title: "Error thrash"
+description: "Retrying a failing command over and over."
+---
+
+**Key:** `error_thrash`
+
+## What it is
+
+The agent keeps calling a tool that keeps failing, usually the same command with
+small variations, without the information it needs to fix the cause.
+
+## How it's detected
+
+An episode starts when the same tool fails **3** times in a row within a stream. Any
+success of that tool ends the run.
+
+**Waste** = the priced input of the model calls that issued the 3rd and later failing
+attempts.
+
+## How to fix it
+
+- Interrupt, and give the agent the missing context (an env var, a service that isn't
+  running, the right command).
+- Put the fix in `CLAUDE.md` so it doesn't happen again.
+- Add a hook that stops after repeated failures.

agentwaste-0.1.0/docs/src/content/docs/detectors/huge-result.mdx

@@ -0,0 +1,27 @@
+---
+title: "Huge result"
+description: "One big output, paid for on every later message."
+---
+
+**Key:** `huge_result`
+
+## What it is
+
+A tool returns a very large output: a recursive grep, a whole log file, a big JSON
+response. It's written into the cache once, then read again on every later message
+in the session. A single oversized result can cost more than the rest of the session
+combined.
+
+## How it's detected
+
+A tool result is flagged when it's larger than **10,000** tokens. The first
+**2,000** tokens are treated as reasonable; only the excess counts.
+
+**Waste** = (tokens - 2,000) x (1.25 + 0.1 x number of later calls in the stream).
+
+## How to fix it
+
+- Pipe command output through `head`, `tail` or `grep`.
+- Add limits and filters to API and database queries.
+- Read large files in ranges.
+- Use a code-search tool instead of recursive `grep -r`.

agentwaste-0.1.0/docs/src/content/docs/detectors/idle-cache-rebuild.mdx

@@ -0,0 +1,42 @@
+---
+title: "Idle cache rebuild"
+description: "Paying to re-cache the whole conversation after a break."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**Key:** `idle_cache_rebuild`
+
+## What it is
+
+Claude's prompt cache keeps your conversation for **5 minutes** after its last use
+(or 1 hour with the extended cache). Come back later and the next message has to
+write the whole context into the cache again, at 1.25x the input price, instead of
+reading it at 0.1x.
+
+On long sessions with large contexts, this is often the biggest single source of
+waste. On the author's own logs it was about a third of all priced input.
+
+## How it's detected
+
+A model call is flagged when:
+
+1. it writes at least **20,000** tokens to the cache, and
+2. the previous call in the same stream was more than **300 seconds** earlier, or
+   more than **3,600 seconds** if the call used the 1-hour cache.
+
+**Waste** = tokens written x (write weight - read weight): the extra cost over
+reading the same context from a warm cache.
+
+## How to fix it
+
+- Run `/compact` before a break, so the context you come back to is small.
+- Use `/clear` when you switch tasks, instead of continuing a huge session.
+- For long sessions with breaks, use the 1-hour cache: writes cost more (2x) but
+  survive the break.
+- Finish a thought before stepping away rather than leaving the agent mid-task.
+
+<Aside>
+  Some rebuilds can't be avoided, such as the first message after compaction or a
+  model switch. Treat the number as an upper bound.
+</Aside>

agentwaste-0.1.0/docs/src/content/docs/detectors/overview.mdx

@@ -0,0 +1,19 @@
+---
+title: "Detectors overview"
+description: "The six waste patterns agentwaste looks for."
+---
+
+Each detector looks for one pattern within a [stream](/agentwaste/how-it-works/#where-the-data-comes-from)
+and estimates its avoidable cost in [token-equivalents](/agentwaste/how-it-works/#token-equivalents).
+
+| Detector | Key | What it finds | Counted in grade |
+| --- | --- | --- | --- |
+| [Idle cache rebuild](/agentwaste/detectors/idle-cache-rebuild/) | `idle_cache_rebuild` | The cache expired during a break and the context was re-written | Yes |
+| [Uncached context](/agentwaste/detectors/uncached-context/) | `uncached_context` | Claude conversations re-sent without prompt caching | Yes |
+| [Uncached context, self-hosted](/agentwaste/detectors/uncached-context/#self-hosted-models) | `uncached_context_self_hosted` | The same on non-Claude models | No (informational) |
+| [Re-read](/agentwaste/detectors/reread/) | `reread` | A file read again with no change in between | Yes |
+| [Duplicate call](/agentwaste/detectors/duplicate-call/) | `duplicate_call` | An identical search or fetch repeated | Yes |
+| [Huge result](/agentwaste/detectors/huge-result/) | `huge_result` | A tool output over 10k tokens, carried in every later message | Yes |
+| [Error thrash](/agentwaste/detectors/error-thrash/) | `error_thrash` | The same tool failing 3+ times in a row | Yes |
+
+The key is how each detector appears in the [JSON output](/agentwaste/reference/json-output/).

agentwaste-0.1.0/docs/src/content/docs/detectors/reread.mdx

@@ -0,0 +1,30 @@
+---
+title: "Re-read"
+description: "Reading a file again when nothing changed."
+---
+
+**Key:** `reread`
+
+## What it is
+
+The agent reads a file it already read earlier in the session, although the file
+hasn't changed. Each re-read adds the same content to the context again.
+
+## How it's detected
+
+A `Read` call is flagged when the same file was already read in the stream, with no
+`Edit`, `Write`, `MultiEdit` or `NotebookEdit` of that file and no `Bash` call in
+between. Any `Bash` call resets tracking, because a shell command may have changed
+the file.
+
+Reading a different range of the same file still counts.
+
+**Waste** = result tokens x 1.25, the cost of writing that content into the cache
+again.
+
+## How to fix it
+
+- Put facts the agent keeps looking up (config values, key paths, conventions) in
+  `CLAUDE.md`.
+- Ask the agent to note what it learned from a file rather than re-open it.
+- The report lists the most re-read files; those are the best candidates.

agentwaste-0.1.0/docs/src/content/docs/detectors/uncached-context.mdx

@@ -0,0 +1,42 @@
+---
+title: "Uncached context"
+description: "Re-sending the whole conversation every turn."
+---
+
+**Keys:** `uncached_context` (Claude models), `uncached_context_self_hosted` (other models)
+
+## What it is
+
+When prompt caching is working, each turn reads most of the conversation from the
+cache at 0.1x. When it isn't, every turn re-sends the whole conversation as fresh
+input at full price.
+
+## How it's detected
+
+A model call is flagged when it isn't the first call in its stream and has at least
+**20,000** fresh (uncached) input tokens.
+
+**Waste** = fresh tokens x (1 - 0.1): what caching would have saved.
+
+## Claude models
+
+Counted in the waste total and grade. The usual cause is a proxy or gateway between
+the agent and the API (LiteLLM, Bedrock, a custom base URL) that drops the
+`cache_control` markers, or a model where caching isn't enabled.
+
+**Fix:** make sure your proxy passes prompt-caching markers through, and that
+caching is enabled for the model you use.
+
+## Self-hosted models
+
+Reported as **informational** and not counted in the grade. For a model you run
+yourself, re-processing context costs GPU prefill time and latency rather than
+Claude-priced tokens, so pricing it with Claude's weights would mislead.
+
+The fix quotes the measured share of this model's input served from its prefix
+cache. To raise it:
+
+- check prefix caching is on in your server (it's the default in recent vLLM;
+  SGLang uses RadixAttention),
+- leave enough free KV-cache memory that cached prefixes aren't evicted,
+- route all requests from one session to the same replica.

agentwaste-0.1.0/docs/src/content/docs/faq.mdx

@@ -0,0 +1,42 @@
+---
+title: "FAQ"
+description: "Common questions."
+---
+
+<details>
+<summary>I'm on a subscription, does this matter?</summary>
+
+Yes. Waste doesn't show up as a bill, but it uses up your plan's limits, so you hit them
+sooner. The patterns and fixes are the same.
+</details>
+
+<details>
+<summary>Why token-equivalents instead of dollars?</summary>
+
+Prices and plans change, and cache reads, cache writes and fresh input are all priced
+differently. Token-equivalents compare them fairly. Add `--usd-per-mtok` for a dollar
+estimate. See [How it works](/agentwaste/how-it-works/#token-equivalents).
+</details>
+
+<details>
+<summary>Is the waste figure exact?</summary>
+
+No. It's an estimate of what each pattern cost, and some of it can't be avoided. Each
+detector page explains exactly how it's computed.
+</details>
+
+<details>
+<summary>Why is my self-hosted model "not counted"?</summary>
+
+Its cost is GPU time and latency, not Claude-priced tokens. agentwaste still shows the
+finding and your measured prefix-cache hit rate. See
+[Uncached context](/agentwaste/detectors/uncached-context/#self-hosted-models).
+</details>
+
+<details>
+<summary>Which agents are supported?</summary>
+
+Claude Code today. Codex is next. Each source turns its logs into the same session
+model, so the detectors work unchanged. Want another agent supported? See
+[Contributing](/agentwaste/contributing/).
+</details>

agentwaste-0.1.0/docs/src/content/docs/guides/reducing-waste.mdx

@@ -0,0 +1,21 @@
+---
+title: "Reducing waste"
+description: "The habits that make the biggest difference."
+---
+
+In order of typical impact:
+
+1. **Compact or clear before a break.** The prompt cache lasts 5 minutes. Running
+   `/compact` before you step away means the context you come back to is small, so
+   re-caching it is cheap. Use `/clear` when you switch tasks. See
+   [Idle cache rebuild](/agentwaste/detectors/idle-cache-rebuild/).
+2. **Check your proxy passes cache markers.** If you reach Claude through a gateway,
+   make sure prompt caching survives the hop. See
+   [Uncached context](/agentwaste/detectors/uncached-context/).
+3. **Keep tool output small.** Limit command output with `head`, filter queries, and
+   read big files in ranges. See [Huge result](/agentwaste/detectors/huge-result/).
+4. **Write things down in `CLAUDE.md`.** Facts the agent keeps re-reading, and fixes for
+   errors it keeps hitting, belong there. See [Re-read](/agentwaste/detectors/reread/)
+   and [Error thrash](/agentwaste/detectors/error-thrash/).
+
+Re-run agentwaste a week later with `--days 7` to see whether it worked.