bloat-report 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan O'Neill
+
+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.

package/README.md

@@ -0,0 +1,199 @@
+# Bloat Report
+
+Your coding agent gets dumber the longer a session runs. Bloat Report is a local, read-only CLI that scans your agent's session transcripts, finds where each one crossed the line, and pairs every finding with the small change that fixes it.
+
+```bash
+npx bloat-report conversations report bloat
+```
+
+## The dumb zone
+
+Past roughly **100k tokens** of context, models get noticeably worse — reasoning slips, instructions get dropped, the agent forgets what you told it ten turns ago. That's the **dumb zone**, and once a session is in it, every new prompt is answered by a worse version of the model.
+
+> **On the name and the idea.** The "dumb zone" was coined by **Dex Horthy**, who put the degradation point at ~40% of the context window. [**Matt Pocock** furthered it](https://finance.biggo.com/news/e7209c094224b09c), pinning the line at ~100k tokens — the figure Bloat Report uses directly.
+
+Catching this is the tool's main job: it flags the sessions that overstayed — where **2+ genuine prompts** were sent into a context already past 100k tokens. One prompt over the line is noise; staying there means the session should have been cleared, compacted, or split before it got dumb. The fix is a `/clear` or `/compact` at the task boundary, or a fresh conversation.
+
+## Context bloat — the same growth, seen from the cost side
+
+The dumb zone is a **quality** problem. Context bloat is the **cost** problem hiding underneath it — the same growing context, measured in dollars instead of degraded reasoning. The two are related but distinct: a session can be expensive long before it's dumb, and watching the cost is how you catch the drift early.
+
+Here's the mechanism. Every assistant turn re-reads the whole conversation so far, so when a session wanders across unrelated tasks you pay full freight, turn after turn, to carry context you no longer need. Bloat Report prices each token class at its own rate and surfaces the *recoverable* slice — the re-read cost a `/clear` or `/compact` would have saved — so you can see the financial impact of bloat and adopt a few simple habits that keep sessions lean. That's the **"small changes, big savings"** pitch: small, boring practices (clear at task boundaries, quiet flags on noisy commands, ranged reads, drop unused MCP servers) that compound into real savings.
+
+> **Estimates, not a bill.** These numbers come from what your machine recorded locally. They are directional estimates, not official provider billing, and can diverge from it.
+
+This bloat analysis builds on **[Tokenoptics](https://tokenoptics.dev)** — the same vocabulary and thresholds as the companion app, brought to the terminal where it can read the transcripts on your disk directly. For a richer look at the financial side — trends over time, breakdowns, and visualisations — head to **[tokenoptics.dev](https://tokenoptics.dev)**.
+
+## Principles
+
+These are non-negotiable (see [CLAUDE.md](CLAUDE.md) for the full set):
+
+- **Local-only, read-only. Nothing leaves your machine.** No network, no telemetry, no uploads. Transcripts are opened read-only. Privacy is the product.
+- **No AI in the detection path.** Everything is deterministic parsing, counting, and sizing. (You *may* choose to export a flagged conversation to an LLM to learn more — that's your call, outside the tool.)
+- **Never overstate savings.** Each token class is priced at its own rate (cached reads are far cheaper than fresh input). No token is counted under two findings. A session's measured total is the ceiling.
+- **Provider-agnostic by design.** Adapters normalise each provider's transcripts into one shared model; detectors never know which provider produced the data. **Claude Code is the first adapter; Codex is next.**
+
+## Install
+
+Requires **Node.js 18+**.
+
+```bash
+npm install -g bloat-report
+```
+
+Or run without installing:
+
+```bash
+npx bloat-report conversations list
+```
+
+## Example output
+
+```
+$ bloat-report conversations report bloat
+
+Dumb Zone — context past 100k tokens, where the model gets noticeably worse.
+3/14 conversations kept going past 100k tokens for 2+ prompts:
+a1b2c3d4  5 prompts in zone   peak 187k   Refactor auth middleware to use JWT
+e5f6a7b8  3 prompts in zone   peak 142k   Add dark mode support to dashboard
+c9d0e1f2  2 prompts in zone   peak 108k   Debug intermittent test failures in CI
+Fix: /clear or /compact at the task boundary, or start a fresh conversation, before context runs past the line.
+
+Bloat (secondary) — recoverable cost from carrying stale context past an early-session baseline.
+Scanned 14 conversations: 4/14 climbing or worse  ·  1 heavy drift  ·  $0.43 recoverable
+a1b2c3d4  Heavy       cost $0.31    bloat $0.21   ramp 8.4×  hit 91%  dumb zone yes   Refactor auth middleware to use JWT
+e5f6a7b8  Climbing    cost $0.18    bloat $0.12   ramp 4.1×  hit 87%  dumb zone yes   Add dark mode support to dashboard
+c9d0e1f2  Climbing    cost $0.14    bloat $0.07   ramp 3.8×  hit 84%  dumb zone yes   Debug intermittent test failures in CI
+f3a4b5c6  Climbing    cost $0.09    bloat $0.03   ramp 3.2×  hit 79%  dumb zone no    Update README and contributing guide
+
+To dig deeper, export flagged conversations and upload to an LLM:
+  conversations export                  (saves export-<date>.md)
+  conversations export <id>             (one specific conversation)
+```
+
+## Where it reads from
+
+The Claude Code adapter reads transcripts from `~/.claude/projects/<project>/<session>.jsonl`. Set `CLAUDE_CONFIG_DIR` to point at a different root (still read-only). If no transcripts are found, the adapter simply reports nothing to scan.
+
+## Commands
+
+All commands hang off the `conversations` group (the singular `conversation` also works).
+
+Global flags (work on any command):
+
+- `--json` — machine-readable JSON instead of the plain-English report
+- `--verbose` — include per-finding detail
+
+### `conversations list`
+
+List discovered conversations, most recent first, with token totals and estimated cost.
+
+```bash
+bloat-report conversations list
+bloat-report conversations list -n 50            # show more
+bloat-report conversations list -p claude        # one provider
+```
+
+- `-n, --limit <count>` — max conversations to show (default 30)
+- `-p, --provider <name>` — limit to one provider (e.g. `claude`)
+
+### `conversations detail <id>`
+
+Show one conversation in detail — model, cwd, time span, token breakdown, and the signals that conversation carries. Accepts an id prefix.
+
+```bash
+bloat-report conversations detail a1b2c3d4
+bloat-report conversations detail a1b2c3d4 --verbose   # per-message timeline
+```
+
+### `conversations report bloat`
+
+The main event. Scans recent conversations and leads with the **Dumb Zone** roundup — who kept working past the ~100k line — then, as secondary detail, a **bloat table** of recoverable cost, biggest opportunity first.
+
+```bash
+bloat-report conversations report bloat
+bloat-report conversations report bloat -a          # show every scanned convo, not just flagged
+bloat-report conversations report bloat --verbose   # per-finding detail
+bloat-report conversations report bloat --json      # structured output
+```
+
+- `-n, --limit <count>` — max conversations to scan (default 30)
+- `-p, --provider <name>` — limit to one provider
+- `-a, --all` — list every scanned conversation, not just the Climbing/Heavy ones
+
+Conversations with no token data are skipped rather than reported as a hollow zero — the report tells you when and why a detector couldn't run (graceful degradation).
+
+### `conversations export [id...]`
+
+Export conversations as markdown ready to paste into an LLM chatbot (Claude.ai, ChatGPT, …) so you can ask *why* the bloat happened and how to avoid it next time. The export bundles Bloat Report's findings at the top, then the conversation with tool calls and result sizes summarised (thinking blocks and raw tool output are stripped to keep it lean).
+
+```bash
+bloat-report conversations export                   # exports what the bloat report flags
+bloat-report conversations export a1b2c3d4 e5f6     # specific conversations
+bloat-report conversations export --all             # include healthy ones too
+bloat-report conversations export --print           # to terminal instead of a file
+bloat-report conversations export -o my-export.md   # custom filename
+```
+
+With no ids, it exports exactly the set the bloat report flags (Climbing/Heavy). By default it saves to `bloat-report-export-<date>.md`.
+
+## What it measures
+
+### The Dumb Zone (primary)
+
+The main detector. It flags conversations that kept going past the ~100k line — specifically, sessions where **2+ genuine prompts** were sent into a context of 100k+ tokens — and tells you where a `/clear`, `/compact`, or fresh conversation at the task boundary would have kept the session sharp. (See [The dumb zone](#the-dumb-zone) above for the concept and its origins.)
+
+### Context bloat (secondary)
+
+Alongside the Dumb Zone, the report surfaces *recoverable cost*. Bloat is **not** "total cost is high." It's the *recoverable* slice — the cache-read cost **above an early-session baseline** — and it's only counted when a drift signal fires (evidence the session wandered across topics and a `/clear` or `/compact` would have saved money). The report classifies each conversation:
+
+| Health        | Meaning                                                              |
+| ------------- | ------------------------------------------------------------------- |
+| **No bloat**  | Cost per turn is steady; context is being used, not wasted.         |
+| **Climbing**  | Late turns cost ~3×+ the early baseline — drift is starting.        |
+| **Heavy**     | Late turns cost ~6×+ the baseline, or a long session with a low cache hit ratio. |
+
+Each finding comes with the small change that fixes it — e.g. `/compact` at a task boundary, splitting a session that's drifted into a new topic, quiet flags on noisy commands, ranged reads on big files, or disconnecting MCP servers a session never calls.
+
+> **Where this comes from.** The bloat analysis — the early-session baseline, the ramp ratios, and the Climbing/Heavy thresholds — is shared with **[Tokenoptics](https://tokenoptics.dev)**, the companion app this CLI builds on. For trends over time and richer breakdowns of the same numbers, see [tokenoptics.dev](https://tokenoptics.dev).
+
+## How pricing works
+
+Each message is priced at **its own model's rate** (a session can mix models) and summed — never recomputed from aggregated token totals. Cached reads, fresh input, output, and the two cache-write TTLs (5-minute and 1-hour) are each priced separately. Unknown model ids fall back to a sane mid rate rather than crashing, and an unrecognised newer minor version is priced at its newest known sibling rather than collapsing onto a pricier legacy entry.
+
+## Architecture
+
+```
+adapters/      provider-specific: read transcripts, normalise to the shared model,
+               supply the exact fix wording (Claude today, Codex next)
+core/          the shared model (sessions → messages → blocks, token usage),
+               adapter interface, and the provider registry
+analyze/       provider-agnostic detectors: cache/bloat analysis, dumb zone
+commands/      the Commander.js CLI surface
+```
+
+The design rule: **adapters normalise, detectors stay provider-agnostic.** Each adapter declares which signals it supplies (token usage, cache split, tool-output sizes, …); a detector runs only where its required signals exist. Provider-specific fixes (slash commands, flags) come from the adapter, never hard-coded into shared code. New providers plug in behind the shared interface without touching detectors or commands.
+
+## Development
+
+```bash
+git clone <this-repo>
+cd bloat-report
+npm install
+
+npm run dev -- conversations list   # run from source (tsx)
+npm run build                       # bundle to dist/cli.js
+npm run typecheck                   # tsc --noEmit
+npm test                            # run analysis tests
+```
+
+To publish a new version:
+
+```bash
+npm version patch   # or minor / major
+npm publish
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,1024 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/conversations.ts
+import fs from "fs";
+
+// src/core/registry.ts
+var adapters = /* @__PURE__ */ new Map();
+function registerAdapter(adapter) {
+  adapters.set(adapter.id, adapter);
+}
+function resolveAdapters(provider) {
+  if (provider) {
+    const a = adapters.get(provider);
+    return a ? [a] : [];
+  }
+  return [...adapters.values()];
+}
+
+// src/adapters/claude/pricing.ts
+var PRICING = {
+  // Fable 5 — flagship tier above Opus. cacheWrite (5m) is the standard 1.25x
+  // input ($12.50, not in the public table); cacheWrite1h is 2x input ($20),
+  // and cacheRead is the 90%-off-input read ($1.00).
+  "claude-fable-5": { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5, cacheWrite1h: 20 },
+  // Opus 4.8 — 1M context at standard pricing (no long-context premium); same
+  // rates as 4.7/4.6/4.5. Without this row the dash-walk falls through to the
+  // legacy "claude-opus-4" entry (15/75), overstating cost ~3x.
+  "claude-opus-4-8": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  "claude-opus-4-7": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  "claude-opus-4-6": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  "claude-opus-4-5": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  "claude-opus-4-1": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75, cacheWrite1h: 30 },
+  "claude-opus-4": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75, cacheWrite1h: 30 },
+  "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  "claude-sonnet-4-5": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  "claude-sonnet-4": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  "claude-3-7-sonnet": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  "claude-3-5-sonnet": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  "claude-haiku-4-5": { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25, cacheWrite1h: 2 },
+  "claude-3-5-haiku": { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1, cacheWrite1h: 1.6 }
+};
+var FALLBACK_PRICING = PRICING["claude-sonnet-4-6"];
+function newestSiblingPricing(candidate) {
+  const m = candidate.match(/^(.*)-\d+$/);
+  if (!m) return void 0;
+  const prefix = m[1] + "-";
+  let bestMinor = -1;
+  let best;
+  for (const key of Object.keys(PRICING)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (!/^\d+$/.test(rest)) continue;
+    const minor = Number(rest);
+    if (minor > bestMinor) bestMinor = minor, best = PRICING[key];
+  }
+  return best;
+}
+function pricingForModel(model) {
+  if (!model) return FALLBACK_PRICING;
+  if (PRICING[model]) return PRICING[model];
+  const stripped = model.replace(/\[.*\]$/, "");
+  const parts = stripped.split("-");
+  while (parts.length > 1) {
+    const candidate = parts.join("-");
+    if (PRICING[candidate]) return PRICING[candidate];
+    const sibling = newestSiblingPricing(candidate);
+    if (sibling) return sibling;
+    parts.pop();
+  }
+  return FALLBACK_PRICING;
+}
+function costForUsage(model, usage) {
+  const p = pricingForModel(model);
+  return (usage.inputTokens * p.input + usage.outputTokens * p.output + usage.cacheReadTokens * p.cacheRead + usage.cacheWrite5mTokens * p.cacheWrite + usage.cacheWrite1hTokens * p.cacheWrite1h) / 1e6;
+}
+function formatUSD(amount) {
+  if (amount === 0) return "$0.00";
+  if (amount < 0.01) return `$${amount.toFixed(4)}`;
+  if (amount < 1) return `$${amount.toFixed(3)}`;
+  return `$${amount.toFixed(2)}`;
+}
+
+// src/analyze/cache.ts
+var HEALTH_MIN_TURNS = 5;
+var LONG_SESSION_TURNS = 20;
+var HEALTHY_CACHE_HIT_RATIO = 0.7;
+var RAMP_WARN_RATIO = 3;
+var RAMP_CRITICAL_RATIO = 6;
+function dominantBucket(inputCost, outputCost, cacheReadCost, cacheWrite5mCost, cacheWrite1hCost) {
+  let best = "output";
+  let bestVal = outputCost;
+  const candidates = [
+    ["input", inputCost],
+    ["cache_read", cacheReadCost],
+    ["cache_write_5m", cacheWrite5mCost],
+    ["cache_write_1h", cacheWrite1hCost]
+  ];
+  for (const [bucket, val] of candidates) {
+    if (val > bestVal) {
+      best = bucket;
+      bestVal = val;
+    }
+  }
+  return best;
+}
+function buildTrajectory(messages, pricing) {
+  const out = [];
+  let cumulative = 0;
+  let turnIndex = 0;
+  for (const m of messages) {
+    if (m.role !== "assistant" || !m.usage) continue;
+    turnIndex += 1;
+    const p = pricing.pricingForModel(m.model);
+    const inputCost = m.usage.inputTokens * p.input / 1e6;
+    const outputCost = m.usage.outputTokens * p.output / 1e6;
+    const cacheReadCost = m.usage.cacheReadTokens * p.cacheRead / 1e6;
+    const cacheWrite5mCost = m.usage.cacheWrite5mTokens * p.cacheWrite / 1e6;
+    const cacheWrite1hCost = m.usage.cacheWrite1hTokens * p.cacheWrite1h / 1e6;
+    const cost = inputCost + outputCost + cacheReadCost + cacheWrite5mCost + cacheWrite1hCost;
+    cumulative += cost;
+    out.push({
+      turnIndex,
+      model: m.model ?? null,
+      cost,
+      cumulativeCost: cumulative,
+      inputTokens: m.usage.inputTokens,
+      outputTokens: m.usage.outputTokens,
+      cacheReadTokens: m.usage.cacheReadTokens,
+      cacheWrite5mTokens: m.usage.cacheWrite5mTokens,
+      cacheWrite1hTokens: m.usage.cacheWrite1hTokens,
+      dominantBucket: dominantBucket(
+        inputCost,
+        outputCost,
+        cacheReadCost,
+        cacheWrite5mCost,
+        cacheWrite1hCost
+      )
+    });
+  }
+  return out;
+}
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2 : sorted[mid] ?? 0;
+}
+function mean(values) {
+  if (values.length === 0) return 0;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+function buildRecommendations(report, pricing) {
+  const recs = [];
+  const bloatSuffix = report.aboveBaselineContextCost > 0 ? ` Likely recoverable: ${pricing.formatUSD(report.aboveBaselineContextCost)} (${(report.aboveBaselineContextShare * 100).toFixed(0)}% of session cost) \u2014 drop it with /clear or /compact at the topic boundary.` : "";
+  if (report.assistantTurnCount > LONG_SESSION_TURNS && report.cacheHitRatio < HEALTHY_CACHE_HIT_RATIO) {
+    recs.push({
+      severity: "critical",
+      title: "Long session with low cache hit ratio",
+      message: `Cache hit ratio is ${(report.cacheHitRatio * 100).toFixed(0)}% across ${report.assistantTurnCount} assistant turns. That means turns are paying full input price for context that should've been cached. Use /clear or /compact between unrelated tasks instead of letting one session drift across topics.${bloatSuffix}`
+    });
+  }
+  if (report.finalRampRatio >= RAMP_CRITICAL_RATIO) {
+    recs.push({
+      severity: "critical",
+      title: "Cost per turn climbed sharply",
+      message: `Late turns in this session cost about ${report.finalRampRatio.toFixed(1)}\xD7 as much as early turns. Most of the extra is cumulative cache_read on a growing context window. Split the session at the topic boundary or run /clear to drop history that isn't needed anymore.${bloatSuffix}`
+    });
+  } else if (report.finalRampRatio >= RAMP_WARN_RATIO) {
+    recs.push({
+      severity: "warn",
+      title: "Cost per turn climbing",
+      message: `Late turns cost about ${report.finalRampRatio.toFixed(1)}\xD7 the early-session baseline. Cache_read on a growing context is doing the work. Consider splitting at task boundaries when one session drifts into a new topic.${bloatSuffix}`
+    });
+  }
+  if (report.cacheReadTokens > 0 && report.cacheWrite5mTokens > report.cacheReadTokens) {
+    recs.push({
+      severity: "info",
+      title: "Cache is churning (5-minute TTL expiring)",
+      message: `5-minute cache writes (${report.cacheWrite5mTokens.toLocaleString()} tokens) exceed cache reads (${report.cacheReadTokens.toLocaleString()}). The session is rebuilding cache more often than reusing it \u2014 usually caused by long pauses between turns or by prompt prefixes that change shape between calls.`
+    });
+  }
+  return recs;
+}
+function computeCacheReport(messages, pricing) {
+  const trajectory = buildTrajectory(messages, pricing);
+  let totalCost = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWrite5mTokens = 0;
+  let cacheWrite1hTokens = 0;
+  let cacheReadCost = 0;
+  for (const point of trajectory) {
+    totalCost += point.cost;
+    inputTokens += point.inputTokens;
+    outputTokens += point.outputTokens;
+    cacheReadTokens += point.cacheReadTokens;
+    cacheWrite5mTokens += point.cacheWrite5mTokens;
+    cacheWrite1hTokens += point.cacheWrite1hTokens;
+  }
+  for (const m of messages) {
+    if (m.role !== "assistant" || !m.usage) continue;
+    const p = pricing.pricingForModel(m.model);
+    cacheReadCost += m.usage.cacheReadTokens * p.cacheRead / 1e6;
+  }
+  const cacheHitDenom = inputTokens + cacheReadTokens;
+  const cacheHitRatio = cacheHitDenom > 0 ? cacheReadTokens / cacheHitDenom : 0;
+  const cacheReadCostShare = totalCost > 0 ? cacheReadCost / totalCost : 0;
+  const baselineSample = trajectory.slice(0, 3).map((p) => p.cost);
+  const baselineTurnCost = median(baselineSample);
+  const tailSample = trajectory.slice(-3).map((p) => p.cost);
+  const tailMeanCost = mean(tailSample);
+  const finalRampRatio = baselineTurnCost > 0 ? tailMeanCost / baselineTurnCost : 0;
+  const perTurnCacheReadCost = trajectory.map((p) => {
+    const pricingForTurn = pricing.pricingForModel(p.model ?? void 0);
+    return p.cacheReadTokens * pricingForTurn.cacheRead / 1e6;
+  });
+  const baselineCacheReadCost = median(perTurnCacheReadCost.slice(0, 3));
+  let aboveBaselineContextCost = 0;
+  for (const cost of perTurnCacheReadCost) {
+    aboveBaselineContextCost += Math.max(0, cost - baselineCacheReadCost);
+  }
+  const aboveBaselineContextShare = totalCost > 0 ? aboveBaselineContextCost / totalCost : 0;
+  let totalCostCheck = 0;
+  for (const m of messages) {
+    if (m.role !== "assistant" || !m.usage) continue;
+    totalCostCheck += pricing.costForUsage(m.model, m.usage);
+  }
+  const baseReport = {
+    assistantTurnCount: trajectory.length,
+    totalCost: totalCostCheck,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWrite5mTokens,
+    cacheWrite1hTokens,
+    cacheHitRatio,
+    cacheReadCost,
+    cacheReadCostShare,
+    baselineCacheReadCost,
+    aboveBaselineContextCost,
+    aboveBaselineContextShare,
+    recoverableBloatCost: 0,
+    trajectory,
+    baselineTurnCost,
+    finalRampRatio
+  };
+  const recommendations = buildRecommendations(baseReport, pricing);
+  const driftDetected = recommendations.some(
+    (r) => r.severity === "critical" || r.severity === "warn"
+  );
+  return {
+    ...baseReport,
+    recoverableBloatCost: driftDetected ? aboveBaselineContextCost : 0,
+    recommendations
+  };
+}
+function cacheHealthFromReport(report) {
+  if (report.assistantTurnCount < HEALTH_MIN_TURNS) return null;
+  for (const rec of report.recommendations) {
+    if (rec.severity === "critical") return "poor";
+  }
+  for (const rec of report.recommendations) {
+    if (rec.severity === "warn") return "climbing";
+  }
+  return "good";
+}
+
+// src/analyze/dumbzone.ts
+var DUMB_ZONE_TOKENS = 1e5;
+var DUMB_ZONE_MIN_PROMPTS = 2;
+function inputContextTokens(m) {
+  const u = m.usage;
+  if (!u) return 0;
+  return u.inputTokens + u.cacheReadTokens + u.cacheWrite5mTokens + u.cacheWrite1hTokens;
+}
+function computeDumbZoneReport(messages) {
+  let promptsInZone = 0;
+  let totalPrompts = 0;
+  let peakContextTokens = 0;
+  let enteredAtTokens = null;
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (m?.role !== "user" || !m.isGenuinePrompt) continue;
+    let ctx = null;
+    for (let j = i + 1; j < messages.length; j++) {
+      const next = messages[j];
+      if (next?.role === "user" && next.isGenuinePrompt) break;
+      if (next?.role === "assistant" && next.usage) {
+        ctx = inputContextTokens(next);
+        break;
+      }
+    }
+    if (ctx === null) continue;
+    totalPrompts += 1;
+    if (ctx > peakContextTokens) peakContextTokens = ctx;
+    if (ctx >= DUMB_ZONE_TOKENS) {
+      promptsInZone += 1;
+      if (enteredAtTokens === null) enteredAtTokens = ctx;
+    }
+  }
+  return {
+    promptsInZone,
+    totalPrompts,
+    inDumbZone: promptsInZone >= DUMB_ZONE_MIN_PROMPTS,
+    enteredAtTokens,
+    peakContextTokens
+  };
+}
+
+// src/commands/conversations.ts
+var claudePricing = { pricingForModel, costForUsage, formatUSD };
+var DEFAULT_LIMIT = 100;
+function bloatHealthLabel(health) {
+  switch (health) {
+    case null:
+      return "n/a";
+    case "good":
+      return "No bloat";
+    case "climbing":
+      return "Climbing";
+    case "poor":
+      return "Heavy";
+  }
+}
+function globalOpts(cmd) {
+  let root = cmd;
+  while (root.parent) root = root.parent;
+  return root.opts();
+}
+function renderExport(convo) {
+  const report = computeCacheReport(convo.messages, claudePricing);
+  const health = cacheHealthFromReport(report);
+  const dumbZone = computeDumbZoneReport(convo.messages);
+  const lines = [];
+  lines.push(`# Bloat Report Export \u2014 ${convo.title}`);
+  lines.push("");
+  lines.push(`**Session:** ${convo.sessionId}`);
+  lines.push(`**Date:** ${convo.startedAt.slice(0, 10)}`);
+  lines.push(`**Model:** ${convo.primaryModel}`);
+  lines.push(`**Total cost:** ${formatUSD(convo.totalCost)}`);
+  lines.push(`**Messages:** ${convo.messageCount} (${convo.userPromptCount} user prompts)`);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("## What Bloat Report found");
+  lines.push("");
+  if (dumbZone.inDumbZone) {
+    const tokK = Math.round(DUMB_ZONE_TOKENS / 1e3);
+    lines.push(
+      `**Dumb zone:** ${dumbZone.promptsInZone} prompt${dumbZone.promptsInZone === 1 ? "" : "s"} past ${tokK}k tokens (peak ${Math.round(dumbZone.peakContextTokens / 1e3)}k)`
+    );
+  } else {
+    lines.push("**Dumb zone:** clear \u2014 context stayed under the line");
+  }
+  lines.push(
+    `**Context bloat (secondary):** ${bloatHealthLabel(health)}` + (report.recoverableBloatCost > 0 ? ` \u2014 ~${formatUSD(report.recoverableBloatCost)} recoverable` : "")
+  );
+  lines.push(`**Cache hit ratio:** ${(report.cacheHitRatio * 100).toFixed(0)}%`);
+  lines.push(`**Context ramp:** ${report.finalRampRatio.toFixed(1)}\xD7 baseline`);
+  if (report.recommendations.length > 0) {
+    lines.push("");
+    lines.push("### Findings");
+    for (const rec of report.recommendations) {
+      lines.push(`- **[${rec.severity}] ${rec.title}:** ${rec.message}`);
+    }
+  }
+  lines.push("");
+  lines.push(
+    "> Please review this conversation. Explain why each finding above occurred, which specific exchanges caused it, and what the user could have done differently to avoid the wasted cost."
+  );
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("## Conversation");
+  lines.push("");
+  for (const msg of convo.messages) {
+    lines.push(`### ${msg.role === "user" ? "User" : "Assistant"}`);
+    lines.push(`*${msg.timestamp.slice(0, 19).replace("T", " ")}*`);
+    if (msg.usage) {
+      lines.push(
+        `*tokens: in ${msg.usage.inputTokens.toLocaleString()} \xB7 out ${msg.usage.outputTokens.toLocaleString()} \xB7 cache-read ${msg.usage.cacheReadTokens.toLocaleString()}*`
+      );
+    }
+    lines.push("");
+    for (const block of msg.blocks) {
+      if (block.kind === "text") {
+        lines.push(block.text.trimEnd());
+      } else if (block.kind === "thinking") {
+      } else if (block.kind === "tool_use") {
+        const inputSummary = JSON.stringify(block.input).slice(0, 120);
+        lines.push(`*[Tool call: **${block.name}** \u2014 \`${inputSummary}\`]*`);
+      } else if (block.kind === "tool_result") {
+        const label = block.toolName ? `${block.toolName} result` : "Tool result";
+        const size = block.charCount.toLocaleString();
+        const errFlag = block.isError ? " (error)" : "";
+        lines.push(`*[${label}${errFlag} \u2014 ${size} chars]*`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function totalTokens(c) {
+  return c.totalInputTokens + c.totalOutputTokens + c.totalCacheReadTokens + c.totalCacheWriteTokens;
+}
+function registerConversations(program2) {
+  const conversations = program2.command("conversations").alias("conversation").description("Inspect locally-recorded agent conversations");
+  conversations.command("list").description("List discovered conversations (most recent first)").option("-p, --provider <name>", "limit to one provider (e.g. claude, codex)").option("-n, --limit <count>", "max conversations to show", String(DEFAULT_LIMIT)).action(async (opts, cmd) => {
+    const g = globalOpts(cmd);
+    const limit = Number.parseInt(opts.limit, 10) || 30;
+    const adapters2 = resolveAdapters(opts.provider);
+    if (opts.provider && adapters2.length === 0) {
+      console.error(`Unknown provider: ${opts.provider}`);
+      process.exitCode = 1;
+      return;
+    }
+    const rows = [];
+    for (const adapter of adapters2) {
+      if (!await adapter.isAvailable()) continue;
+      rows.push(...await adapter.listConversations());
+    }
+    rows.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+    const shown = rows.slice(0, limit);
+    if (g.json) {
+      console.log(JSON.stringify(shown, (k, v) => v instanceof Set ? [...v] : v, 2));
+      return;
+    }
+    if (shown.length === 0) {
+      console.log("No conversations found.");
+      return;
+    }
+    for (const c of shown) {
+      const date = c.startedAt ? c.startedAt.slice(0, 10) : "??????????";
+      const tokens = totalTokens(c).toLocaleString();
+      const cost = formatUSD(c.totalCost).padStart(9);
+      console.log(
+        `${date}  ${c.sessionId.slice(0, 8)}  ${tokens.padStart(9)} tok  ${cost}  ${c.title}`
+      );
+    }
+    const grandTotal = shown.reduce((sum, c) => sum + c.totalCost, 0);
+    console.log(
+      `${" ".repeat(34)}${formatUSD(grandTotal).padStart(9)}  ${shown.length} conversation${shown.length === 1 ? "" : "s"} total`
+    );
+    if (rows.length > shown.length) {
+      console.log(`
+\u2026and ${rows.length - shown.length} more (raise --limit to see them).`);
+    }
+  });
+  conversations.command("detail").description("Show one conversation in detail").argument("[conversationId]", "id (or id prefix) of the conversation to inspect").option("-p, --provider <name>", "provider to load from (e.g. claude, codex)").action(async (conversationId, opts, cmd) => {
+    const g = globalOpts(cmd);
+    if (!conversationId) {
+      console.error("Pass a conversation id \u2014 see `conversations list`.");
+      process.exitCode = 1;
+      return;
+    }
+    const adapters2 = resolveAdapters(opts.provider);
+    let convo = null;
+    for (const adapter of adapters2) {
+      if (!await adapter.isAvailable()) continue;
+      const summaries = await adapter.listConversations();
+      const match = summaries.find(
+        (s) => s.sessionId === conversationId || s.sessionId.startsWith(conversationId)
+      );
+      if (match) {
+        convo = await adapter.loadConversation(match.sessionId);
+        break;
+      }
+    }
+    if (!convo) {
+      console.error(`No conversation matching "${conversationId}".`);
+      process.exitCode = 1;
+      return;
+    }
+    if (g.json) {
+      console.log(JSON.stringify(convo, (k, v) => v instanceof Set ? [...v] : v, 2));
+      return;
+    }
+    console.log(convo.title);
+    console.log(`  session   ${convo.sessionId}`);
+    console.log(`  model     ${convo.primaryModel}`);
+    console.log(`  cwd       ${convo.cwd}`);
+    console.log(`  span      ${convo.startedAt.slice(0, 19)} \u2192 ${convo.endedAt.slice(0, 19)}`);
+    console.log(`  messages  ${convo.messageCount} (${convo.userPromptCount} user prompts)`);
+    console.log(
+      `  tokens    in ${convo.totalInputTokens.toLocaleString()} \xB7 out ${convo.totalOutputTokens.toLocaleString()} \xB7 cache-read ${convo.totalCacheReadTokens.toLocaleString()} \xB7 cache-write ${convo.totalCacheWriteTokens.toLocaleString()}`
+    );
+    console.log(`  signals   ${[...convo.capabilities].join(", ")}`);
+    if (g.verbose) {
+      console.log("");
+      for (const m of convo.messages) {
+        const kinds = m.blocks.map((b) => b.kind).join(",");
+        console.log(`  ${m.timestamp.slice(11, 19)}  ${m.role.padEnd(9)}  ${kinds}`);
+      }
+    }
+  });
+  conversations.command("report").description("Find context-bloat patterns and the small change that fixes each").option("-p, --provider <name>", "limit to one provider (e.g. claude, codex)").option("-n, --limit <count>", "max conversations to scan", String(DEFAULT_LIMIT)).option("-a, --all", "show every scanned conversation, not just Climbing/Heavy ones").action(async (opts, cmd) => {
+    const g = globalOpts(cmd);
+    const limit = Number.parseInt(opts.limit, 10) || 30;
+    const adapters2 = resolveAdapters(opts.provider);
+    if (opts.provider && adapters2.length === 0) {
+      console.error(`Unknown provider: ${opts.provider}`);
+      process.exitCode = 1;
+      return;
+    }
+    const summaries = [];
+    for (const adapter of adapters2) {
+      if (!await adapter.isAvailable()) continue;
+      summaries.push(...await adapter.listConversations());
+    }
+    summaries.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+    const rows = [];
+    for (const summary of summaries.slice(0, limit)) {
+      if (!summary.capabilities.has("tokenUsage")) continue;
+      const owner = adapters2.find((a) => a.id === "claude") ?? adapters2[0];
+      if (!owner) continue;
+      const convo = await owner.loadConversation(summary.sessionId);
+      if (!convo) continue;
+      const report = computeCacheReport(convo.messages, claudePricing);
+      const dumbZone = computeDumbZoneReport(convo.messages);
+      rows.push({ summary, report, health: cacheHealthFromReport(report), dumbZone });
+    }
+    if (g.json) {
+      console.log(
+        JSON.stringify(
+          rows.map((r) => ({
+            sessionId: r.summary.sessionId,
+            title: r.summary.title,
+            totalCost: r.report.totalCost,
+            recoverableBloatCost: r.report.recoverableBloatCost,
+            aboveBaselineContextCost: r.report.aboveBaselineContextCost,
+            finalRampRatio: r.report.finalRampRatio,
+            cacheHitRatio: r.report.cacheHitRatio,
+            health: r.health,
+            dumbZone: r.dumbZone,
+            recommendations: r.report.recommendations
+          })),
+          null,
+          2
+        )
+      );
+      return;
+    }
+    if (rows.length === 0) {
+      console.log("No conversations with token data to analyse.");
+      return;
+    }
+    const climbingOrWorse = rows.filter(
+      (r) => r.health === "climbing" || r.health === "poor"
+    ).length;
+    const heavyBloat = rows.filter((r) => r.health === "poor").length;
+    const totalRecoverable = rows.reduce((sum, r) => sum + r.report.recoverableBloatCost, 0);
+    const scanned = rows.length;
+    const climbingFraction = `${climbingOrWorse}/${scanned} climbing or worse`;
+    const heavyFraction = heavyBloat > 0 ? `  \xB7  ${heavyBloat} heavy drift` : "";
+    const recoverableStr = totalRecoverable > 0 ? `  \xB7  ${formatUSD(totalRecoverable)} recoverable` : "";
+    const tokK = `${Math.round(DUMB_ZONE_TOKENS / 1e3)}k`;
+    const inZone = rows.filter((r) => r.dumbZone.inDumbZone).sort((a, b) => b.dumbZone.promptsInZone - a.dumbZone.promptsInZone);
+    console.log(`
+Dumb Zone \u2014 context past ${tokK} tokens, where the model gets noticeably worse.`);
+    if (inZone.length === 0) {
+      console.log(`No conversations lingered there. (Flagged at ${DUMB_ZONE_MIN_PROMPTS}+ prompts past ${tokK}.)`);
+    } else {
+      console.log(
+        `${inZone.length}/${rows.length} conversation${inZone.length === 1 ? "" : "s"} kept going past ${tokK} tokens for ${DUMB_ZONE_MIN_PROMPTS}+ prompts:`
+      );
+      for (const { summary, dumbZone } of inZone) {
+        const id = summary.sessionId.slice(0, 8);
+        const prompts = `${dumbZone.promptsInZone} prompt${dumbZone.promptsInZone === 1 ? "" : "s"} in zone`.padEnd(20);
+        const peak = `peak ${Math.round(dumbZone.peakContextTokens / 1e3)}k`.padEnd(11);
+        console.log(`${id}  ${prompts}${peak}${summary.title}`);
+      }
+      console.log("Fix: /clear or /compact at the task boundary, or start a fresh conversation, before context runs past the line.");
+    }
+    console.log("\nBloat (secondary) \u2014 recoverable cost from carrying stale context past an early-session baseline.");
+    console.log(`Scanned ${scanned} conversations: ${climbingFraction}${heavyFraction}${recoverableStr}`);
+    rows.sort((a, b) => b.report.recoverableBloatCost - a.report.recoverableBloatCost);
+    const listed = opts.all ? rows : rows.filter((r) => r.health === "climbing" || r.health === "poor");
+    let totalBloat = 0;
+    for (const { summary, report, health, dumbZone } of listed) {
+      totalBloat += report.recoverableBloatCost;
+      const id = summary.sessionId.slice(0, 8);
+      const cost = `cost ${formatUSD(report.totalCost)}`.padEnd(14);
+      const bloat = `bloat ${formatUSD(report.recoverableBloatCost)}`.padEnd(15);
+      const ramp = `ramp ${report.finalRampRatio.toFixed(1)}\xD7`.padEnd(11);
+      const hit = `hit ${(report.cacheHitRatio * 100).toFixed(0)}%`.padEnd(9);
+      const dz = `dumb zone ${dumbZone.inDumbZone ? "yes" : "no"}`.padEnd(15);
+      const healthLabel = bloatHealthLabel(health);
+      console.log(
+        `${id}  ${healthLabel.padEnd(12)}${cost}${bloat}${ramp}${hit}${dz}${summary.title}`
+      );
+      if (g.verbose) {
+        for (const rec of report.recommendations) {
+          console.log(`            [${rec.severity}] ${rec.title}`);
+          console.log(`              ${rec.message}`);
+        }
+      }
+    }
+    if (listed.length === 0) {
+      console.log("Nothing Climbing or Heavy \u2014 every scanned conversation looks healthy. (--all to list them.)");
+    }
+    console.log("\nTo dig deeper, export flagged conversations and upload to an LLM:");
+    console.log("  conversations export                  (saves export-<date>.md)");
+    console.log("  conversations export <id>             (one specific conversation)");
+  });
+  conversations.command("export").description(
+    "Export conversations as markdown ready to paste into an LLM chatbot. Pass id(s) for specific ones, or no ids to export everything the bloat report flags."
+  ).argument("[id...]", "session id(s) or prefixes (omit to export from the bloat report)").option("-p, --provider <name>", "limit to one provider (e.g. claude, codex)").option("-n, --limit <count>", "max conversations to scan (no-id mode)", String(DEFAULT_LIMIT)).option("-a, --all", "include healthy conversations too (no-id mode)").option("-o, --output <file>", "custom filename (default: bloat-report-export-<date>.md)").option("--print", "print to the terminal instead of saving a file").action(async (ids, opts) => {
+    const adapters2 = resolveAdapters(opts.provider);
+    if (opts.provider && adapters2.length === 0) {
+      console.error(`Unknown provider: ${opts.provider}`);
+      process.exitCode = 1;
+      return;
+    }
+    const owner = adapters2.find((a) => a.id === "claude") ?? adapters2[0];
+    const exports = [];
+    if (ids.length > 0) {
+      const summaries = [];
+      for (const adapter of adapters2) {
+        if (!await adapter.isAvailable()) continue;
+        summaries.push(...await adapter.listConversations());
+      }
+      for (const id of ids) {
+        const match = summaries.find(
+          (s) => s.sessionId === id || s.sessionId.startsWith(id)
+        );
+        if (!match) {
+          console.error(`No conversation matching "${id}".`);
+          process.exitCode = 1;
+          continue;
+        }
+        const convo = await owner?.loadConversation(match.sessionId);
+        if (!convo) {
+          console.error(`Could not load conversation "${id}".`);
+          process.exitCode = 1;
+          continue;
+        }
+        exports.push(renderExport(convo));
+      }
+    } else {
+      const limit = Number.parseInt(opts.limit, 10) || 30;
+      const summaries = [];
+      for (const adapter of adapters2) {
+        if (!await adapter.isAvailable()) continue;
+        summaries.push(...await adapter.listConversations());
+      }
+      summaries.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+      const rows = [];
+      for (const summary of summaries.slice(0, limit)) {
+        if (!summary.capabilities.has("tokenUsage")) continue;
+        const convo = await owner?.loadConversation(summary.sessionId);
+        if (!convo) continue;
+        const report = computeCacheReport(convo.messages, claudePricing);
+        const health = cacheHealthFromReport(report);
+        const inScope = opts.all || health === "climbing" || health === "poor";
+        if (inScope) exports.push(renderExport(convo));
+        rows.push({ summary, health });
+      }
+      const flagged = rows.filter((r) => r.health === "climbing" || r.health === "poor").length;
+      const exported = exports.length;
+      process.stderr.write(
+        `Scanned ${rows.length} conversations, exporting ${exported}` + (opts.all ? "" : ` flagged (${flagged} climbing/heavy)`) + ".\n"
+      );
+      if (exported === 0) {
+        process.stderr.write("Nothing to export \u2014 no climbing or heavy conversations found. (--all to export everything.)\n");
+        return;
+      }
+    }
+    if (exports.length === 0) return;
+    const content = exports.join("\n\n---\n\n");
+    if (opts.print) {
+      process.stdout.write(content + "\n");
+    } else {
+      const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const filename = opts.output ?? `bloat-report-export-${date}.md`;
+      fs.writeFileSync(filename, content, "utf8");
+      process.stderr.write(`Saved to ${filename}
+`);
+    }
+  });
+}
+
+// src/adapters/claude/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+import { readdir, access } from "fs/promises";
+function claudeRoot() {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+function projectsDir() {
+  return join(claudeRoot(), "projects");
+}
+async function hasProjects() {
+  try {
+    await access(projectsDir());
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function listTranscriptFiles() {
+  const root = projectsDir();
+  let projects;
+  try {
+    projects = await readdir(root);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const projectId of projects) {
+    let entries;
+    try {
+      entries = await readdir(join(root, projectId));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".jsonl")) continue;
+      files.push({
+        projectId,
+        sessionId: entry.slice(0, -".jsonl".length),
+        path: join(root, projectId, entry)
+      });
+    }
+  }
+  return files;
+}
+
+// src/adapters/claude/parse.ts
+import { readFile } from "fs/promises";
+function mapUsage(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const cc = raw.cache_creation ?? {};
+  const has5m = typeof cc.ephemeral_5m_input_tokens === "number";
+  const has1h = typeof cc.ephemeral_1h_input_tokens === "number";
+  const lump = !has5m && !has1h ? raw.cache_creation_input_tokens ?? 0 : 0;
+  return {
+    inputTokens: raw.input_tokens ?? 0,
+    outputTokens: raw.output_tokens ?? 0,
+    cacheReadTokens: raw.cache_read_input_tokens ?? 0,
+    cacheWrite5mTokens: (cc.ephemeral_5m_input_tokens ?? 0) + lump,
+    cacheWrite1hTokens: cc.ephemeral_1h_input_tokens ?? 0
+  };
+}
+function userPromptText(content) {
+  const parts = [];
+  if (typeof content === "string") {
+    if (content) parts.push(content);
+  } else if (Array.isArray(content)) {
+    for (const b of content) {
+      if (b?.type === "text" && typeof b.text === "string") parts.push(b.text);
+    }
+  }
+  if (parts.length === 0) return null;
+  let text = parts.join("\n");
+  text = text.replace(/<command-name>([^<]*)<\/command-name>/g, "$1");
+  text = text.replace(
+    /<command-args>([\s\S]*?)<\/command-args>/g,
+    (_, args) => args.trim() ? ` ${args.trim()}` : ""
+  );
+  text = text.replace(/<command-message>[\s\S]*?<\/command-message>/g, "").replace(/<local-command-stdout>[\s\S]*?<\/local-command-stdout>/g, "").replace(/<local-command-stderr>[\s\S]*?<\/local-command-stderr>/g, "").replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "").trim();
+  return text || null;
+}
+function charCountOf(content) {
+  if (typeof content === "string") return content.length;
+  if (Array.isArray(content)) {
+    return content.reduce(
+      (n, b) => n + (typeof b?.text === "string" ? b.text.length : 0),
+      0
+    );
+  }
+  return 0;
+}
+function mapBlocks(content, toolNames) {
+  if (typeof content === "string") {
+    return content ? [{ kind: "text", text: content }] : [];
+  }
+  if (!Array.isArray(content)) return [];
+  const blocks = [];
+  for (const b of content) {
+    switch (b?.type) {
+      case "text":
+        blocks.push({ kind: "text", text: b.text ?? "" });
+        break;
+      case "thinking":
+        blocks.push({ kind: "thinking", text: b.thinking ?? "" });
+        break;
+      case "tool_use":
+        if (b.id && b.name) toolNames.set(b.id, b.name);
+        blocks.push({ kind: "tool_use", toolUseId: b.id ?? "", name: b.name ?? "", input: b.input });
+        break;
+      case "tool_result":
+        blocks.push({
+          kind: "tool_result",
+          toolUseId: b.tool_use_id ?? "",
+          isError: !!b.is_error,
+          charCount: charCountOf(b.content),
+          toolName: b.tool_use_id ? toolNames.get(b.tool_use_id) : void 0
+        });
+        break;
+    }
+  }
+  return blocks;
+}
+function* readLines(text) {
+  for (const line of text.split("\n")) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      yield JSON.parse(s);
+    } catch {
+    }
+  }
+}
+function newAccumulator() {
+  return {
+    modelCounts: /* @__PURE__ */ new Map(),
+    totals: {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWrite5mTokens: 0,
+      cacheWrite1hTokens: 0
+    },
+    totalCost: 0,
+    messageCount: 0,
+    userPromptCount: 0,
+    seenUsageIds: /* @__PURE__ */ new Set(),
+    caps: /* @__PURE__ */ new Set()
+  };
+}
+function accumulate(acc, raw) {
+  if (raw.type === "ai-title" && raw.aiTitle) {
+    acc.title = raw.aiTitle;
+    return;
+  }
+  if (raw.type !== "user" && raw.type !== "assistant") return;
+  if (raw.timestamp) {
+    if (!acc.startedAt) acc.startedAt = raw.timestamp;
+    acc.endedAt = raw.timestamp;
+  }
+  if (raw.cwd && !acc.cwd) acc.cwd = raw.cwd;
+  if (raw.gitBranch && !acc.gitBranch) acc.gitBranch = raw.gitBranch;
+  const msg = raw.message;
+  if (raw.type === "user" && userPromptText(msg?.content) !== null) {
+    acc.userPromptCount += 1;
+  }
+  if (raw.type === "assistant" && msg?.model) {
+    acc.modelCounts.set(msg.model, (acc.modelCounts.get(msg.model) ?? 0) + 1);
+    acc.caps.add("modelPerTurn");
+  }
+  const usage = mapUsage(msg?.usage);
+  if (usage && raw.type === "assistant") {
+    const id = msg?.id ?? raw.uuid;
+    if (id && !acc.seenUsageIds.has(id)) {
+      acc.seenUsageIds.add(id);
+      acc.totals.inputTokens += usage.inputTokens;
+      acc.totals.outputTokens += usage.outputTokens;
+      acc.totals.cacheReadTokens += usage.cacheReadTokens;
+      acc.totals.cacheWrite5mTokens += usage.cacheWrite5mTokens;
+      acc.totals.cacheWrite1hTokens += usage.cacheWrite1hTokens;
+      acc.totalCost += costForUsage(msg?.model, usage);
+      acc.caps.add("tokenUsage");
+      if (usage.cacheReadTokens || usage.cacheWrite5mTokens || usage.cacheWrite1hTokens) {
+        acc.caps.add("cacheSplit");
+      }
+    }
+  }
+}
+function primaryModel(counts) {
+  let best = "";
+  let n = -1;
+  for (const [model, c] of counts) if (c > n) best = model, n = c;
+  return best;
+}
+function toSummary(file, acc) {
+  acc.caps.add("toolOutputSize");
+  return {
+    projectId: file.projectId,
+    sessionId: file.sessionId,
+    title: acc.title || acc.cwd || file.sessionId,
+    cwd: acc.cwd ?? "",
+    gitBranch: acc.gitBranch,
+    startedAt: acc.startedAt ?? "",
+    endedAt: acc.endedAt ?? "",
+    messageCount: acc.messageCount,
+    userPromptCount: acc.userPromptCount,
+    primaryModel: primaryModel(acc.modelCounts),
+    totalCost: acc.totalCost,
+    totalInputTokens: acc.totals.inputTokens,
+    totalOutputTokens: acc.totals.outputTokens,
+    totalCacheReadTokens: acc.totals.cacheReadTokens,
+    totalCacheWriteTokens: acc.totals.cacheWrite5mTokens + acc.totals.cacheWrite1hTokens,
+    cacheHealth: null,
+    // analysis fills this
+    capabilities: acc.caps
+  };
+}
+async function summarizeTranscript(file) {
+  let text;
+  try {
+    text = await readFile(file.path, "utf8");
+  } catch {
+    return null;
+  }
+  const acc = newAccumulator();
+  let messages = 0;
+  for (const raw of readLines(text)) {
+    accumulate(acc, raw);
+    if (raw.type === "user" || raw.type === "assistant") messages++;
+  }
+  acc.messageCount = messages;
+  return toSummary(file, acc);
+}
+async function loadTranscript(file) {
+  let text;
+  try {
+    text = await readFile(file.path, "utf8");
+  } catch {
+    return null;
+  }
+  const acc = newAccumulator();
+  const toolNames = /* @__PURE__ */ new Map();
+  const messages = [];
+  const byAssistantId = /* @__PURE__ */ new Map();
+  for (const raw of readLines(text)) {
+    accumulate(acc, raw);
+    if (raw.type !== "user" && raw.type !== "assistant") continue;
+    const msg = raw.message;
+    const blocks = mapBlocks(msg?.content, toolNames);
+    if (raw.type === "assistant") {
+      const id = msg?.id ?? raw.uuid ?? "";
+      const existing = byAssistantId.get(id);
+      if (existing) {
+        existing.blocks.push(...blocks);
+        continue;
+      }
+      const message = {
+        uuid: raw.uuid ?? id,
+        parentUuid: raw.parentUuid ?? null,
+        role: "assistant",
+        timestamp: raw.timestamp ?? "",
+        model: msg?.model,
+        blocks,
+        usage: mapUsage(msg?.usage)
+      };
+      byAssistantId.set(id, message);
+      messages.push(message);
+    } else {
+      messages.push({
+        uuid: raw.uuid ?? "",
+        parentUuid: raw.parentUuid ?? null,
+        role: "user",
+        timestamp: raw.timestamp ?? "",
+        blocks,
+        // Same gate that drives userPromptCount — mark genuine prompts so
+        // detectors (e.g. the dumb-zone scan) can count them without re-deriving
+        // which "user" lines are real human input vs. tool results / wrappers.
+        isGenuinePrompt: userPromptText(msg?.content) !== null
+      });
+    }
+  }
+  acc.messageCount = messages.length;
+  return { ...toSummary(file, acc), messages };
+}
+
+// src/adapters/claude/index.ts
+var RECOMMENDATIONS = {
+  uncompactedSession: {
+    fix: "Run /compact at task boundaries to summarise and shrink the running context.",
+    command: "/compact"
+  },
+  noisyToolOutput: {
+    fix: "Pipe noisy commands through a quiet flag or `head` so only the useful slice enters context."
+  },
+  rereadUnchangedFile: {
+    fix: "Read a file once; don't re-read it while it's unchanged in context."
+  },
+  fullFileRead: {
+    fix: "Use a ranged read on large files instead of pulling the whole thing."
+  },
+  idleMcpServer: {
+    fix: "Disconnect MCP servers a session never calls so their tool definitions stop costing tokens.",
+    command: "/mcp"
+  }
+};
+var ClaudeAdapter = class {
+  id = "claude";
+  displayName = "Claude Code";
+  isAvailable() {
+    return hasProjects();
+  }
+  async listConversations() {
+    const files = await listTranscriptFiles();
+    const summaries = await Promise.all(files.map(summarizeTranscript));
+    return summaries.filter((s) => s !== null).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+  }
+  async loadConversation(sessionId) {
+    const files = await listTranscriptFiles();
+    const file = files.find((f) => f.sessionId === sessionId);
+    return file ? loadTranscript(file) : null;
+  }
+  recommend(pattern) {
+    return RECOMMENDATIONS[pattern];
+  }
+};
+
+// src/adapters/index.ts
+function registerAdapters() {
+  registerAdapter(new ClaudeAdapter());
+}
+
+// src/cli.ts
+registerAdapters();
+var program = new Command();
+program.name("bloat-report").description(
+  "Scan local coding-agent transcripts for wasteful token patterns \u2014 small changes, big savings. Local-only, read-only."
+).version("1.0.0");
+program.option("--json", "emit machine-readable JSON instead of the plain-English report").option("--verbose", "include per-finding detail");
+registerConversations(program);
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "bloat-report",
+  "version": "1.0.0",
+  "description": "Inspect agent conversations to see how you can make big savings from small changes",
+  "type": "module",
+  "bin": {
+    "bloat-report": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup src/cli.ts --format esm --clean",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/cli.js",
+    "test": "tsx --test src/analyze/cache.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Brendan O'Neill <brendanoneill94@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}