agentwaste 0.1.0__py3-none-any.whl

agentwaste/__init__.py

@@ -0,0 +1,3 @@
+"""agentwaste: find where your AI coding agent wastes tokens."""
+
+__version__ = "0.1.0"

agentwaste/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agentwaste/analysis.py

@@ -0,0 +1,68 @@
+"""Rolls streams up into one Report: totals, ranked findings, waste %, grade."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .cost import priced_input
+from .detectors import ALL_DETECTORS, Finding
+from .model import Stream
+from .sources import claude_code
+
+GRADES = [(10, "A"), (20, "B"), (30, "C"), (45, "D")]
+
+
+def grade(waste_pct: float) -> str:
+    for limit, letter in GRADES:
+        if waste_pct < limit:
+            return letter
+    return "F"
+
+
+@dataclass
+class Report:
+    sessions: int = 0
+    streams: int = 0
+    model_calls: int = 0
+    tool_calls: int = 0
+    fresh_input: int = 0
+    cache_write: int = 0
+    cache_read: int = 0
+    output: int = 0
+    priced_input: float = 0.0
+    first_ts: float | None = None
+    last_ts: float | None = None
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def waste(self) -> float:
+        # Detectors can overlap (a huge result that is also a re-read), so cap
+        # the total at what was actually spent.
+        return min(sum(f.waste for f in self.findings if f.counted), self.priced_input)
+
+    @property
+    def waste_pct(self) -> float:
+        return 100.0 * self.waste / self.priced_input if self.priced_input else 0.0
+
+    @property
+    def grade(self) -> str:
+        return grade(self.waste_pct)
+
+
+def analyze(source: list[Stream] | Path | str, since: float | None = None) -> Report:
+    streams = source if isinstance(source, list) else claude_code.load(source, since=since)
+    r = Report(streams=len(streams), sessions=len({s.session_id for s in streams}))
+    for s in streams:
+        for c in s.calls:
+            r.model_calls += 1
+            r.tool_calls += len(c.tool_calls)
+            r.fresh_input += c.input
+            r.cache_write += c.cache_write
+            r.cache_read += c.cache_read
+            r.output += c.output
+            r.priced_input += priced_input(c)
+            r.first_ts = c.ts if r.first_ts is None else min(r.first_ts, c.ts)
+            r.last_ts = c.ts if r.last_ts is None else max(r.last_ts, c.ts)
+    r.findings = sorted((d(streams) for d in ALL_DETECTORS), key=lambda f: (f.counted, f.waste), reverse=True)
+    return r

agentwaste/card.py

@@ -0,0 +1,50 @@
+"""Shareable "Wrapped"-style card: one self-contained HTML file with
+aggregates only. It must never contain file paths, project names, commands
+or any session content -- tests/test_report_and_cli.py enforces this."""
+
+from __future__ import annotations
+
+import html
+from datetime import datetime
+
+from .analysis import Report
+from .report import human
+
+_CSS = """
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+background:#0f1115;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;color:#f5f5f5}
+.card{width:420px;padding:32px;border-radius:20px;background:linear-gradient(160deg,#1d2533,#2a1a2e)}
+.k{font-size:13px;letter-spacing:.08em;text-transform:uppercase;color:#a3a9b8}
+.grade{font-size:96px;font-weight:800;line-height:1;margin:8px 0}
+.big{font-size:28px;font-weight:700}
+.row{display:flex;justify-content:space-between;margin:10px 0;font-size:15px}
+.bar{height:8px;border-radius:4px;background:#ff7a59;margin-top:4px}
+.foot{margin-top:24px;font-size:12px;color:#a3a9b8}
+"""
+
+
+def render_card(r: Report) -> str:
+    rows = []
+    for f in [f for f in r.findings if f.counted][:3]:
+        if not f.count or not r.priced_input:
+            continue
+        pct = 100 * f.waste / r.priced_input
+        rows.append(f'<div class="row"><span>{html.escape(f.title)}</span><span>{pct:.0f}%</span></div>'
+                    f'<div class="bar" style="width:{max(2, min(100, pct)):.0f}%"></div>')
+    span = ""
+    if r.first_ts and r.last_ts:
+        days = max(1, round((r.last_ts - r.first_ts) / 86400))
+        span = f"{days} days"
+    made = datetime.now().strftime("%Y-%m-%d")
+    return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>My agent waste</title>
+<meta name="viewport" content="width=device-width,initial-scale=1"><style>{_CSS}</style></head>
+<body><div class="card">
+<div class="k">My AI coding agent, {html.escape(span)}</div>
+<div class="grade">{r.grade}</div>
+<div class="big">{r.waste_pct:.0f}% of input tokens wasted</div>
+<div class="k" style="margin-top:6px">{human(r.priced_input)} token-equivalents across {r.sessions} sessions</div>
+<div style="margin-top:24px">{''.join(rows)}</div>
+<div class="foot">Made {made} with agentwaste &middot; github.com/nikghodki/agentwaste</div>
+</div></body></html>
+"""

agentwaste/cli.py

@@ -0,0 +1,55 @@
+"""agentwaste command line."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from .analysis import analyze
+from .card import render_card
+from .demo import demo_streams
+from .report import render_text, to_json
+from .sources import claude_code
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agentwaste",
+                                description="Find where your AI coding agent wastes tokens, and how to stop it.")
+    p.add_argument("--path", default=str(claude_code.DEFAULT_ROOT),
+                   help="Claude Code projects directory (default: %(default)s)")
+    p.add_argument("--days", type=float, default=30, help="look back this many days; 0 = all (default: 30)")
+    p.add_argument("--json", action="store_true", help="print machine-readable JSON instead of the report")
+    p.add_argument("--card", metavar="FILE", help="also write a shareable HTML card (aggregates only)")
+    p.add_argument("--usd-per-mtok", type=float, metavar="USD",
+                   help="show dollar estimates at this price per million input tokens")
+    p.add_argument("--top", type=int, default=3, help="examples to show per finding (default: 3)")
+    p.add_argument("--demo", action="store_true", help="run on built-in synthetic sessions instead of your logs")
+    p.add_argument("--version", action="version", version=f"agentwaste {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    root = Path(args.path).expanduser()
+    since = time.time() - args.days * 86400 if args.days else None
+    report = analyze(demo_streams()) if args.demo else analyze(root, since=since)
+    if not report.model_calls:
+        print(f"No Claude Code sessions found in {root}"
+              + (f" in the last {args.days:g} days" if args.days else "")
+              + ". Try --days 0 or --path.", file=sys.stderr)
+        return 1
+    if args.demo and not args.json:
+        print("Showing demo data (synthetic sessions). Run without --demo to analyze your own logs.\n")
+    print(to_json(report, args.usd_per_mtok) if args.json else render_text(report, args.usd_per_mtok, args.top))
+    if args.card:
+        Path(args.card).write_text(render_card(report))
+        if not args.json:
+            print(f"\nShareable card written to {args.card}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentwaste/cost.py

@@ -0,0 +1,23 @@
+"""Priced input-token equivalents ("eq"). One eq = one fresh input token.
+
+Anthropic prompt caching bills cache writes at 1.25x (5-minute TTL) or 2x
+(1-hour TTL) the input price, and cache reads at 0.1x. Dollars are left to
+the caller (--usd-per-mtok) because prices and plans change.
+"""
+
+from __future__ import annotations
+
+from .model import ModelCall
+
+W_INPUT = 1.0
+W_CACHE_WRITE_5M = 1.25
+W_CACHE_WRITE_1H = 2.0
+W_CACHE_READ = 0.1
+
+TTL_5M = 300
+TTL_1H = 3600
+
+
+def priced_input(call: ModelCall) -> float:
+    return (call.input * W_INPUT + call.cache_write_5m * W_CACHE_WRITE_5M
+            + call.cache_write_1h * W_CACHE_WRITE_1H + call.cache_read * W_CACHE_READ)

agentwaste/demo.py

@@ -0,0 +1,58 @@
+"""Deterministic synthetic sessions for `agentwaste --demo`: lets anyone try
+the tool without logs, and keeps screenshots free of real usage."""
+
+from __future__ import annotations
+
+import random
+
+from .model import ModelCall, Stream, ToolCall
+
+DAY = 86400
+START = 1_790_000_000  # a fixed date, so output is identical on every run
+FILES = [f"src/app/{n}.py" for n in ("api", "models", "auth", "db", "views", "utils", "config", "tasks")]
+
+
+def _session(rng: random.Random, n: int, day: int, *, uncached: bool = False, thrash: bool = False,
+             calls: int | None = None) -> Stream:
+    s = Stream(f"demo-{n}", False, "demo-app", "demo")
+    ts = START + day * DAY + rng.randint(8, 18) * 3600
+    context = 12_000
+    calls = calls or rng.randint(60, 140)
+    thrash_at = rng.randint(20, calls - 10) if thrash else -1
+    huge_at = rng.randint(10, calls - 5)
+    for i in range(calls):
+        idle = rng.random() < 0.06
+        ts += rng.randint(360, 2400) if idle else rng.randint(4, 90)
+        delta = rng.randint(800, 4000)
+        c = ModelCall(f"demo-{n}-{i}", ts, model="claude-demo", output=rng.randint(80, 900))
+        if uncached:
+            c.input = context + delta
+        elif i == 0 or idle:
+            c.cache_write_5m, c.input = context + delta, rng.randint(50, 400)
+        else:
+            c.cache_read, c.cache_write_5m, c.input = context, delta, rng.randint(50, 400)
+        context += delta
+        roll = rng.random()
+        if thrash_at <= i < thrash_at + 4:
+            t = ToolCall(f"t{n}-{i}", "Bash", {"command": "npm test"}, True, 600, True)
+        elif i == huge_at:
+            t = ToolCall(f"t{n}-{i}", "Bash", {"command": "grep -rn TODO ."}, True, rng.randint(18_000, 40_000))
+        elif roll < 0.45:
+            t = ToolCall(f"t{n}-{i}", "Read", {"file_path": rng.choice(FILES)}, True, rng.randint(900, 3500))
+        elif roll < 0.60:
+            t = ToolCall(f"t{n}-{i}", "Grep", {"pattern": rng.choice(["TODO", "def get_", "import os"])},
+                         True, rng.randint(200, 1500))
+        elif roll < 0.75:
+            t = ToolCall(f"t{n}-{i}", "Edit", {"file_path": rng.choice(FILES)}, True, 120)
+        else:
+            t = ToolCall(f"t{n}-{i}", "Bash", {"command": "pytest -q"}, True, rng.randint(200, 1200))
+        c.tool_calls.append(t)
+        s.calls.append(c)
+    return s
+
+
+def demo_streams() -> list[Stream]:
+    rng = random.Random(42)
+    streams = [_session(rng, n, day=n, thrash=n in (2, 7)) for n in range(12)]
+    streams.append(_session(rng, 12, day=12, uncached=True, calls=24))  # one session behind a cache-dropping proxy
+    return streams

agentwaste/detectors.py

@@ -0,0 +1,203 @@
+"""Waste detectors. Each takes streams and returns a Finding. Definitions
+match design/2026-10-26-agentwaste-v1.md; change both together."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+
+from .cost import TTL_1H, TTL_5M, W_CACHE_READ, W_CACHE_WRITE_1H, W_CACHE_WRITE_5M, priced_input
+from .model import Stream
+
+MIN_REBUILD = 20_000
+HUGE_TOKENS = 10_000
+HUGE_KEEP = 2_000  # a result this size is reasonable; only the excess counts
+THRASH_RUN = 3
+UNCACHED_MIN = 20_000
+
+EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+MUTATING_TOOLS = EDIT_TOOLS | {"Bash"}
+READ_ONLY_TOOLS = {"Grep", "Glob", "LS", "WebFetch", "WebSearch"}
+
+
+@dataclass
+class Finding:
+    key: str
+    title: str
+    fix: str
+    count: int = 0
+    waste: float = 0.0  # eq
+    examples: list[tuple[str, int]] = field(default_factory=list)  # (label, occurrences)
+    # False for findings whose cost isn't priced like Claude's (self-hosted
+    # models): shown, but excluded from the waste total and the grade.
+    counted: bool = True
+
+
+def _top(counter: Counter, n: int = 3) -> list[tuple[str, int]]:
+    return counter.most_common(n)
+
+
+def detect_idle_rebuilds(streams: list[Stream]) -> Finding:
+    f = Finding("idle_cache_rebuild", "Re-caching after idle breaks",
+                "The prompt cache expires after 5 minutes idle, so the next message re-writes the whole "
+                "context at 1.25x. Run /compact (or /clear) before a break, finish a thought before "
+                "stepping away, or use the 1-hour cache for long sessions.")
+    projects = Counter()
+    for s in streams:
+        for prev, cur in zip(s.calls, s.calls[1:]):
+            if cur.cache_write < MIN_REBUILD:
+                continue
+            ttl = TTL_1H if cur.cache_write_1h > cur.cache_write_5m else TTL_5M
+            if cur.ts - prev.ts > ttl:
+                f.count += 1
+                f.waste += (cur.cache_write_5m * (W_CACHE_WRITE_5M - W_CACHE_READ)
+                            + cur.cache_write_1h * (W_CACHE_WRITE_1H - W_CACHE_READ))
+                projects[s.project] += 1
+    f.examples = _top(projects)
+    return f
+
+
+def detect_rereads(streams: list[Stream]) -> Finding:
+    f = Finding("reread", "Re-reading unchanged files",
+                "The agent read a file it had already read and not changed. Put the facts it keeps "
+                "looking up (config values, key paths, conventions) in CLAUDE.md, or ask it to keep "
+                "notes instead of re-opening the file.")
+    files = Counter()
+    for s in streams:
+        seen: set[str] = set()
+        for c in s.calls:
+            for t in c.tool_calls:
+                path = t.input.get("file_path") if isinstance(t.input, dict) else None
+                if t.name == "Bash":
+                    seen.clear()
+                elif t.name in EDIT_TOOLS and path:
+                    seen.discard(path)
+                elif t.name == "Read" and path:
+                    if path in seen:
+                        f.count += 1
+                        f.waste += t.result_tokens * W_CACHE_WRITE_5M
+                        files[path] += 1
+                    seen.add(path)
+    f.examples = _top(files)
+    return f
+
+
+def detect_duplicate_calls(streams: list[Stream]) -> Finding:
+    f = Finding("duplicate_call", "Repeating identical lookups",
+                "The same search or fetch ran again with nothing changed in between. Ask the agent to "
+                "reuse earlier results, or narrow the first search so it doesn't need repeating.")
+    labels = Counter()
+    for s in streams:
+        seen: set[str] = set()
+        for c in s.calls:
+            for t in c.tool_calls:
+                if t.name in MUTATING_TOOLS:
+                    seen.clear()
+                    continue
+                if t.name not in READ_ONLY_TOOLS:
+                    continue
+                key = t.name + json.dumps(t.input, sort_keys=True, default=str)
+                if key in seen:
+                    f.count += 1
+                    f.waste += t.result_tokens * W_CACHE_WRITE_5M
+                    labels[t.name] += 1
+                seen.add(key)
+    f.examples = _top(labels)
+    return f
+
+
+def detect_huge_results(streams: list[Stream]) -> Finding:
+    f = Finding("huge_result", "Huge tool outputs kept in context",
+                "A command or read returned over 10k tokens, and the agent carried it in every later "
+                "message. Pipe through head/tail, add filters or limits, read files in ranges, or use "
+                "a code-search tool instead of recursive grep.")
+    tools = Counter()
+    for s in streams:
+        n = len(s.calls)
+        for i, c in enumerate(s.calls):
+            later = n - i - 1
+            for t in c.tool_calls:
+                if t.result_tokens > HUGE_TOKENS:
+                    f.count += 1
+                    f.waste += (t.result_tokens - HUGE_KEEP) * (W_CACHE_WRITE_5M + W_CACHE_READ * later)
+                    tools[t.name] += 1
+    f.examples = _top(tools)
+    return f
+
+
+def detect_error_thrash(streams: list[Stream]) -> Finding:
+    f = Finding("error_thrash", "Retry loops on failing commands",
+                "The same tool failed 3+ times in a row. Stop and give the agent the missing context, "
+                "put the fix in CLAUDE.md, or add a hook that halts after repeated failures.")
+    tools = Counter()
+    for s in streams:
+        runs: Counter = Counter()
+        for c in s.calls:
+            for t in c.tool_calls:
+                if not t.has_result:
+                    continue
+                if not t.is_error:
+                    runs[t.name] = 0
+                    continue
+                runs[t.name] += 1
+                if runs[t.name] == THRASH_RUN:
+                    f.count += 1
+                    tools[t.name] += 1
+                if runs[t.name] >= THRASH_RUN:
+                    f.waste += priced_input(c)
+    f.examples = _top(tools)
+    return f
+
+
+def _is_claude(model: str) -> bool:
+    return model.startswith("claude")
+
+
+def _uncached_calls(streams: list[Stream], claude: bool):
+    for s in streams:
+        for c in s.calls[1:]:
+            if c.input >= UNCACHED_MIN and _is_claude(c.model) == claude:
+                yield c
+
+
+def detect_uncached_context(streams: list[Stream]) -> Finding:
+    """Large fresh (uncached) input on a Claude call that follows earlier calls
+    in the same stream: the conversation is re-sent at full price instead of
+    read from the prompt cache -- typically a proxy dropping cache markers."""
+    f = Finding("uncached_context", "Context re-sent without prompt caching",
+                "Each turn re-sent the whole conversation uncached, at ~10x the cached price. If you use a "
+                "proxy or gateway (LiteLLM, Bedrock, a custom base URL), make sure it passes the "
+                "prompt-caching cache_control markers through and that caching is enabled for the model.")
+    models = Counter()
+    for c in _uncached_calls(streams, claude=True):
+        f.count += 1
+        f.waste += c.input * (1 - W_CACHE_READ)
+        models[c.model] += 1
+    f.examples = _top(models)
+    return f
+
+
+def detect_uncached_context_self_hosted(streams: list[Stream]) -> Finding:
+    """The same pattern on non-Claude (typically self-hosted) models. Their cost
+    is GPU prefill time and latency, not Claude-priced tokens, so it is
+    reported but not counted toward waste or the grade."""
+    f = Finding("uncached_context_self_hosted", "Self-hosted model re-processing context", "", counted=False)
+    models = Counter()
+    for c in _uncached_calls(streams, claude=False):
+        f.count += 1
+        f.waste += c.input * (1 - W_CACHE_READ)
+        models[c.model or "unknown model"] += 1
+    f.examples = _top(models)
+    fresh = sum(c.input for s in streams for c in s.calls if not _is_claude(c.model))
+    read = sum(c.cache_read for s in streams for c in s.calls if not _is_claude(c.model))
+    hit = 100 * read / (fresh + read) if fresh + read else 0
+    f.fix = (f"Only {hit:.0f}% of this model's input was served from its prefix cache; the rest was "
+             "re-processed every turn, costing GPU prefill time and latency. Check the server's prefix "
+             "caching is on (default in recent vLLM; SGLang uses RadixAttention), that it has free KV-cache "
+             "memory, and that a session's requests reach the same replica.")
+    return f
+
+ALL_DETECTORS = [detect_idle_rebuilds, detect_rereads, detect_duplicate_calls,
+                 detect_huge_results, detect_error_thrash, detect_uncached_context,
+                 detect_uncached_context_self_hosted]

agentwaste/model.py

@@ -0,0 +1,45 @@
+"""Source-agnostic session model. Sources (sources/*.py) produce these;
+detectors only ever see these."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    input: dict
+    has_result: bool = False
+    result_tokens: int = 0  # estimated: characters / 4
+    is_error: bool = False
+
+
+@dataclass
+class ModelCall:
+    id: str
+    ts: float  # unix seconds
+    model: str = ""
+    input: int = 0
+    cache_write_5m: int = 0
+    cache_write_1h: int = 0
+    cache_read: int = 0
+    output: int = 0
+    tool_calls: list[ToolCall] = field(default_factory=list)
+
+    @property
+    def cache_write(self) -> int:
+        return self.cache_write_5m + self.cache_write_1h
+
+
+@dataclass
+class Stream:
+    """One cache context: a session's main thread, or one of its sidechains
+    (subagents), which keep their own cache."""
+
+    session_id: str
+    sidechain: bool
+    project: str = ""
+    source: str = ""
+    calls: list[ModelCall] = field(default_factory=list)

agentwaste/report.py

@@ -0,0 +1,81 @@
+"""Terminal and JSON rendering. The terminal report is local-only and may show
+file names; the shareable card (card.py) never does."""
+
+from __future__ import annotations
+
+import json
+import os
+import textwrap
+from datetime import datetime
+
+from .analysis import Report
+
+
+def human(n: float) -> str:
+    for unit, size in (("B", 1e9), ("M", 1e6), ("k", 1e3)):
+        if abs(n) >= size:
+            return f"{n / size:.1f}{unit}"
+    return f"{n:.0f}"
+
+
+def _date(ts: float | None) -> str:
+    return datetime.fromtimestamp(ts).strftime("%Y-%m-%d") if ts else "?"
+
+
+def _short(label: str) -> str:
+    home = os.environ.get("HOME", "")
+    return "~" + label[len(home):] if home and label.startswith(home + "/") else label
+
+
+def _usd(eq: float, usd_per_mtok: float | None) -> str:
+    return f" (~${eq / 1e6 * usd_per_mtok:,.0f})" if usd_per_mtok else ""
+
+
+def render_text(r: Report, usd_per_mtok: float | None = None, top: int = 3) -> str:
+    lines = [
+        f"agentwaste: {r.sessions} sessions, {r.model_calls:,} model calls, {r.tool_calls:,} tool calls"
+        f"  ({_date(r.first_ts)} to {_date(r.last_ts)})",
+        "",
+        f"Priced input: {human(r.priced_input)} token-equivalents{_usd(r.priced_input, usd_per_mtok)}"
+        f"   (cache writes {human(r.cache_write)}, cache reads {human(r.cache_read)},"
+        f" fresh {human(r.fresh_input)}; output {human(r.output)})",
+        f"Estimated waste: {human(r.waste)} ({r.waste_pct:.0f}%){_usd(r.waste, usd_per_mtok)}   Grade: {r.grade}",
+        "",
+    ]
+    info_header = False
+    for f in r.findings:
+        if not f.count:
+            continue
+        if not f.counted:
+            if not info_header:
+                lines += ["Not counted in the grade (self-hosted models: the cost is GPU time, not tokens):", ""]
+                info_header = True
+            lines.append(f"  info  {f.title}  ({f.count:,}x, {human(f.waste)} tokens re-processed)")
+        else:
+            pct = 100 * f.waste / r.priced_input if r.priced_input else 0
+            lines.append(f"{pct:5.1f}%  {f.title}  ({f.count:,}x, {human(f.waste)} eq{_usd(f.waste, usd_per_mtok)})")
+        for label, n in f.examples[:top]:
+            lines.append(f"        - {_short(label)}: {n:,}x")
+        lines += ["        " + l for l in textwrap.wrap("Fix: " + f.fix, 88)]
+        lines.append("")
+    if not any(f.count for f in r.findings):
+        lines.append("No waste patterns found. Nice.")
+    lines.append("Token-equivalents weight cache writes 1.25x (1-hour cache 2x) and cache reads 0.1x")
+    lines.append("of fresh input. Estimates; see https://github.com/nikghodki/agentwaste for definitions.")
+    return "\n".join(lines)
+
+
+def to_json(r: Report, usd_per_mtok: float | None = None) -> str:
+    data = {
+        "sessions": r.sessions, "streams": r.streams, "model_calls": r.model_calls,
+        "tool_calls": r.tool_calls, "fresh_input": r.fresh_input, "cache_write": r.cache_write,
+        "cache_read": r.cache_read, "output": r.output, "priced_input": round(r.priced_input),
+        "waste": round(r.waste), "waste_pct": round(r.waste_pct, 2), "grade": r.grade,
+        "first_ts": r.first_ts, "last_ts": r.last_ts, "usd_per_mtok": usd_per_mtok,
+        "findings": [
+            {"key": f.key, "title": f.title, "count": f.count, "waste": round(f.waste), "counted": f.counted,
+             "examples": [{"label": l, "count": n} for l, n in f.examples], "fix": f.fix}
+            for f in r.findings
+        ],
+    }
+    return json.dumps(data, indent=2)

agentwaste/sources/claude_code.py

@@ -0,0 +1,124 @@
+"""Reads Claude Code transcripts: ~/.claude/projects/<project>/<session>.jsonl.
+
+Format notes (observed):
+- One assistant reply is split across several records sharing message.id;
+  usage repeats on each, so it is counted once, while tool_use blocks are
+  collected from all of them.
+- Tool results arrive in later "user" records and link back by tool_use_id.
+- usage.cache_creation may split cache writes into 5-minute and 1-hour TTLs.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+from ..model import ModelCall, Stream, ToolCall
+
+DEFAULT_ROOT = Path("~/.claude/projects").expanduser()
+
+
+def _ts(value) -> float | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return None
+
+
+def _result_tokens(content) -> int:
+    if content is None:
+        return 0
+    text = content if isinstance(content, str) else json.dumps(content)
+    return len(text) // 4
+
+
+def _project(cwd: str | None, file: Path) -> str:
+    if cwd:
+        return os.path.basename(cwd.rstrip("/")) or cwd
+    return file.parent.name
+
+
+def discover(root: Path | str = DEFAULT_ROOT) -> list[Path]:
+    return sorted(Path(root).expanduser().rglob("*.jsonl"))
+
+
+def parse_file(path: Path) -> list[Stream]:
+    streams: dict[tuple[str, bool], Stream] = {}
+    calls: dict[tuple[str, bool, str], ModelCall] = {}
+    tools: dict[str, ToolCall] = {}
+
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except ValueError:
+                continue
+            msg = rec.get("message") if isinstance(rec, dict) else None
+            sid = rec.get("sessionId") if isinstance(rec, dict) else None
+            if not isinstance(msg, dict) or not sid:
+                continue
+            side = bool(rec.get("isSidechain"))
+            key = (sid, side)
+            stream = streams.get(key)
+            if stream is None:
+                stream = streams[key] = Stream(sid, side, _project(rec.get("cwd"), path), "claude-code")
+            content = msg.get("content") if isinstance(msg.get("content"), list) else []
+
+            if rec.get("type") == "assistant":
+                mid = msg.get("id") or rec.get("uuid")
+                ts = _ts(rec.get("timestamp"))
+                # Claude Code writes "<synthetic>" placeholders (errors, interrupts)
+                # with zero usage; they are not model calls.
+                if not mid or ts is None or msg.get("model") == "<synthetic>":
+                    continue
+                call = calls.get((sid, side, mid))
+                if call is None:
+                    usage = msg.get("usage") or {}
+                    written = usage.get("cache_creation_input_tokens") or 0
+                    split = usage.get("cache_creation") or {}
+                    w1h = split.get("ephemeral_1h_input_tokens") or 0
+                    w5m = split.get("ephemeral_5m_input_tokens")
+                    call = ModelCall(
+                        id=mid, ts=ts, model=msg.get("model") or "",
+                        input=usage.get("input_tokens") or 0,
+                        cache_write_5m=(written - w1h) if w5m is None else w5m,
+                        cache_write_1h=w1h,
+                        cache_read=usage.get("cache_read_input_tokens") or 0,
+                        output=usage.get("output_tokens") or 0,
+                    )
+                    calls[(sid, side, mid)] = call
+                    stream.calls.append(call)
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use" and block.get("id"):
+                        tc = ToolCall(block["id"], block.get("name") or "", block.get("input") or {})
+                        call.tool_calls.append(tc)
+                        tools[tc.id] = tc
+
+            elif rec.get("type") == "user":
+                for block in content:
+                    if not (isinstance(block, dict) and block.get("type") == "tool_result"):
+                        continue
+                    tc = tools.get(block.get("tool_use_id"))
+                    if tc is not None:
+                        tc.has_result = True
+                        tc.result_tokens = _result_tokens(block.get("content"))
+                        tc.is_error = bool(block.get("is_error"))
+
+    for stream in streams.values():
+        stream.calls.sort(key=lambda c: c.ts)
+    return [s for s in streams.values() if s.calls]
+
+
+def load(root: Path | str = DEFAULT_ROOT, since: float | None = None) -> list[Stream]:
+    out = []
+    for path in discover(root):
+        for stream in parse_file(path):
+            if since is not None:
+                stream.calls = [c for c in stream.calls if c.ts >= since]
+            if stream.calls:
+                out.append(stream)
+    return out

agentwaste-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,17 @@
+agentwaste/__init__.py,sha256=ILAlddbHEryL1Y-hlvmjxtykD2tFe7Yb2FE8Qip4Y90,88
+agentwaste/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+agentwaste/analysis.py,sha256=6tzRXOlHw6X9o_siv_oBwroBGQTZQb0fmDDvPoYSmF4,2227
+agentwaste/card.py,sha256=LtnSWV409kxao7e0sFEekIshyUsva2zmXycUb6tcThk,2318
+agentwaste/cli.py,sha256=y66EDiaitX1iGzGyROBl4L7eTL3F4AQyYB_Mof8aCz4,2474
+agentwaste/cost.py,sha256=HFILPHI8vcQne80wqSmvywWaXbSrBBLx_wWQTPdwg0k,671
+agentwaste/demo.py,sha256=mccXk3Jdsfe9sC8_HCbjBJzkv4HG8JY9WuJrbpO41KA,2630
+agentwaste/detectors.py,sha256=G1FeXA6D8D1PE2hU226Hd8RuFpnwyl1asDnZdAvRouQ,8673
+agentwaste/model.py,sha256=2TxXTqqNqL9nYT1Q56NNkAijO9xYz3TMUB3j7LKBzOg,1037
+agentwaste/report.py,sha256=UcstOupTra5EsrM_o2J5jh7aMWSebfLxpcoU1Y-B5z8,3512
+agentwaste/sources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentwaste/sources/claude_code.py,sha256=sDa4DT6fzfb4yFHgHATnIDsl4Wv8KU-UHnfHdO4FWu4,4979
+agentwaste-0.1.0.dist-info/METADATA,sha256=TYwi-XToavcBGRfcLOmiLCtURraWVsvAA7a3gpT9LDM,6992
+agentwaste-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentwaste-0.1.0.dist-info/entry_points.txt,sha256=VZpXwBxudinvItJChxXCZMzLO3JIoojcso1yRNWEMgE,51
+agentwaste-0.1.0.dist-info/licenses/LICENSE,sha256=7wf_NTnQqhAnakahKHHkrJHQ3P8a7HzC6TH6DU5xExo,1070
+agentwaste-0.1.0.dist-info/RECORD,,

agentwaste-0.1.0.dist-info/WHEEL

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

agentwaste-0.1.0.dist-info/entry_points.txt

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

agentwaste-0.1.0.dist-info/licenses/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.