@chroxify/eunoe 1.0.0 → 1.2.0

package/README.md

@@ -11,10 +11,6 @@ nothing lost, no pause, no restart.
 
 </div>
 
-> At the top of Dante's Purgatory two rivers run from one spring. **Lethe**
-> washes away the memory of what weighed on you. **Eunoe** — *good mind* —
-> gives back the memory of the good. You drink from both. Lethe first.
-
 ---
 
 ## The problem
@@ -49,6 +45,10 @@ at known depths, such as a value a command printed once, an error, an
 instruction that was later revised or a decision with its rejected options,
 and scored by exact match with no judge involved.
 
+> These numbers come from one developer's sessions. They are a careful
+> measurement, not a general one, so read them as a strong signal rather than
+> a guarantee for your own work.
+
 | | facts remembered | rules followed without a reminder | prompt size when asked | tokens per session | transcript lookups per session | time per session | said "I don't know" | answered wrong |
 |---|---|---|---|---|---|---|---|---|
 | Claude Code's compaction | 70% | 92% | 70k | 741k | 10.1 | 53s | 172 of 600 | 7 of 600 |
@@ -86,6 +86,12 @@ test split ran. The suites, the pre-registered spec, every per-arm table and
 the limits of the study (one developer's repositories, one answering model,
 one run per arm) are in [`bench/`](bench/README.md).
 
+Context management is hard to benchmark well alone, because the honest test
+is many people's real sessions. If you run the bench on your own sessions,
+find a case where eunoe does worse, or have a better way to measure this,
+please open an issue or a pull request. Results from other setups are the
+contribution I'd value most.
+
 ## Install
 
 ```sh
@@ -98,8 +104,10 @@ sessions that were already running pick it up when you restart them.
 `eunoe stop` turns it off again.
 
 Requires [Bun](https://bun.sh). On macOS `start` sets up a launchd agent that
-keeps the proxy alive; on other platforms keep `eunoe serve` running however
-you like and everything else works the same.
+keeps the proxy alive and a watchdog that unroutes Claude Code if the proxy
+should ever be down; on other platforms keep `eunoe serve` running however you like and
+everything else works the same. The proxy listens on 127.0.0.1:38663 (`port`
+in `~/.eunoe/config.json` changes it).
 
 ## How it works
 
@@ -241,7 +249,7 @@ it, so it never disturbs the cache.
 
 ```
 Claude Code  ------>  eunoe  ------>  api.anthropic.com
-CLI, desktop app,     127.0.0.1:8788
+CLI, desktop app,     127.0.0.1:38663
 Agent SDK             rewrites /v1/messages
                       passes everything else through
 ```
@@ -267,8 +275,15 @@ index.md        one line per turn: what you asked and how the turn ended
 turn-0001.md    ## User            your message
 turn-0002.md    ### [tool 3/12]    every tool call, with its full output below it
 ...             ## Final reply     the agent's reply
+turn-0002-subagent-1.md            the whole run of a subagent launched in that turn
 ```
 
+A subagent's run is its own file, indexed under the turn that launched it
+and linked from the Agent call; the turn itself only has the subagent's
+report. What the subagent saw and ran is also part of recall, labelled
+`subagent "…"`, so the agent gets a value only its subagent printed without
+having to look.
+
 Markdown is far easier for an agent to grep and read than Claude Code's raw
 JSONL, and the folder is rebuilt as the session grows. The agent is given the
 path and a short recipe for searching it, so when it needs an exact detail
@@ -321,11 +336,36 @@ eunoe settings               # pick a setting and change it
 eunoe settings list          # show them all
 eunoe settings set keep 5    # change one directly
 eunoe status                 # what's running, every session, context and tokens saved
+eunoe stats                  # tokens and API cost by day (--days 14, --weekly), and what eunoe saved
+eunoe replay                 # replay your whole Claude Code history through eunoe, offline, and see what it saves
 eunoe uninstall              # stop and remove the background proxy
 ```
 
 `ee` is an alias, so `ee status` and `eunoe status` are the same command.
 
+### Earlier sessions
+
+A different big problem with Claude is that new chats always start cold. eunoe
+helps you carry an earlier session into one: run `eunoe sessions`, pick the
+session (type to filter), and paste the copied `{ee:continue:<id>}` marker into
+the chat along with what you want done. eunoe attaches that whole session to
+the message, folded the same way it folds turns in a live session: your
+messages, the key output lines and the agent's replies, in order. From then on
+the earlier session's dropped tool output is searchable too, so an exact value
+from it comes back as recalled context when a later message is about it.
+
+You always name the session. eunoe never guesses which one you mean or injects
+one on its own; in the benchmark that choice was wrong a third of the time,
+while a named session remembered 98% of its facts and kept 95% of its rules.
+
+```sh
+eunoe sessions [words]       # browse earlier sessions here; enter copies {ee:continue:<id>}
+```
+
+The agent is also taught two commands for digging on its own: `eunoe load
+<id>` writes a session to `~/.eunoe/loaded/<id>.md` for it to read whole, and
+`eunoe peek <id> <words>` prints just the excerpts that match.
+
 ### Per session
 
 Everything above takes `--session <id>` to apply to one session only. Session
@@ -350,6 +390,7 @@ session's next request.
 |---|---|---|
 | `keep` | `3` | turns kept whole at the end |
 | `budget` | `100000` | tokens of older detail that trigger a fold |
+| `turnCap` | `100000` | a kept turn larger than this is folded at once, the live turn excepted; `off` to disable |
 | `compactAt` | `0.9` | share of the context window that triggers the full cut |
 | `keepTurns` | `all` | folded turns kept after a full cut |
 | `search` | `markdown` | transcript form for the agent: `markdown`, `xml`, `jsonl` or `qmd` (semantic, via [qmd](https://github.com/tobi/qmd)) |
@@ -376,12 +417,30 @@ Every request is written to `~/.eunoe/requests.jsonl` with what eunoe did
 to it and how much of it the API served from cache, which is also where
 `eunoe status` gets its numbers.
 
+`eunoe stats` reads the usage the API returned, from Claude Code's own session
+files, subagents included, so it covers every session, routed through eunoe or
+not. Claude Code writes one response as several lines, so each response is
+counted once, with its final output count. Cost is at API list prices.
+Its eunoe columns are only what eunoe actually did, from its request log: the
+input tokens it kept out, and what that saved. Those tokens are mostly history
+plain Claude Code would have read from cache, so they are priced as cache
+reads, and every token a fold rewrote is charged back at the cache-write price.
+`eunoe replay` and `eunoe stats` can only see what is still on disk: Claude Code
+deletes sessions that have been idle for 30 days unless `cleanupPeriodDays` in
+its `settings.json` says otherwise.
+
 ## What it doesn't do
 
 - **It is a proxy, which makes it a single point of failure.** If it isn't
   running while `ANTHROPIC_BASE_URL` still points at it, every Claude request
-  fails. launchd keeps it alive, and `stop` leaves it running so sessions
-  already pointed at it keep working.
+  fails. Three things limit the damage: `start` refuses to route Claude Code
+  until the proxy answers, launchd restarts the proxy within a second whenever
+  it dies, and a watchdog that runs every 10 seconds takes eunoe out of
+  `settings.json` after 20 seconds of silence and puts it back when the proxy
+  answers again. A request the proxy can't deliver upstream comes back as a
+  502 that Claude Code retries, never a hang. Sessions that were already
+  running keep the old address until restarted, so they wait for the proxy
+  rather than falling back.
 - **It only understands Claude Code's shape of conversation.** Other
   Anthropic API clients pass through unchanged and get nothing out of it.
 - **It can't recover what Claude Code already compacted,** so turn it on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chroxify/eunoe",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Context management for Claude Code that never forgets what matters.",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,7 @@
     "url": "git+https://github.com/chroxify/eunoe.git"
   },
   "homepage": "https://github.com/chroxify/eunoe#readme",
+  "bugs": "https://github.com/chroxify/eunoe/issues",
   "keywords": [
     "claude-code",
     "claude",
@@ -32,13 +33,28 @@
   "scripts": {
     "start": "bun src/cli/main.ts serve",
     "test": "bun test",
-    "typecheck": "tsc --noEmit -p ."
+    "check-types": "tsc --noEmit -p .",
+    "lint": "biome check . && bun lint:conventions",
+    "lint:conventions": "bun scripts/lint-conventions.ts",
+    "format": "biome check .",
+    "format:fix": "biome check . --write",
+    "prepare": "husky"
   },
   "devDependencies": {
+    "@babel/parser": "7.27.0",
+    "@biomejs/biome": "2.5.9",
     "@types/bun": "^1.4.2",
+    "husky": "9.1.7",
+    "knip": "6.41.0",
+    "lint-staged": "16.4.0",
     "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "lint-staged": {
+    "*.{js,ts,json,jsonc,md,yml}": [
+      "biome check --write --files-ignore-unknown=true --no-errors-on-unmatched"
+    ]
   }
 }

package/src/cli/{types.ts → command.ts}

@@ -1,5 +1,3 @@
-export type Settings = Record<string, any>
-
 export type OptionRow = [flag: string, description: string]
 
 export interface Command {
@@ -10,5 +8,3 @@ export interface Command {
   hidden?: boolean
   run: (args: string[]) => void | Promise<void>
 }
-
-export type RequestRecord = Record<string, any>

package/src/cli/commands/index.ts

@@ -1,11 +1,17 @@
-import type { Command } from "../types"
+import type { Command } from "../command"
+import { load } from "./load"
 import { mode } from "./mode"
+import { peek } from "./peek"
+import { replay } from "./replay"
 import { serve } from "./serve"
+import { sessions } from "./sessions"
 import { settings } from "./settings"
 import { start } from "./start"
+import { stats } from "./stats"
 import { status } from "./status"
 import { stop } from "./stop"
 import { uninstall } from "./uninstall"
+import { watch } from "./watch"
 
 const alias = (target: Command, prefix: string[] = []): Command => ({ ...target, hidden: true, run: (args) => target.run([...prefix, ...args]) })
 
@@ -15,8 +21,14 @@ export const commands: Record<string, Command> = {
   mode,
   settings,
   status,
+  stats,
+  replay,
+  sessions,
+  peek,
+  load,
   uninstall,
   serve,
+  watch,
   enable: alias(start),
   disable: alias(stop),
   set: alias(settings, ["set"]),

package/src/cli/commands/load.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { paths } from "../../config/paths"
+import { FOLD_CAP_CHARS, foldedView } from "../../context/fold"
+import type { Command } from "../command"
+import { candidateOf, candidatesHere, shortId, titleOf } from "../sessions"
+import type { SessionCandidate } from "../sessions/source"
+import { line } from "../terminal/ui"
+
+interface Loaded {
+  file: string
+  lines: number
+  chars: number
+}
+
+export function writeLoaded(cand: SessionCandidate): Loaded {
+  const text = foldedView(cand.messages, FOLD_CAP_CHARS)
+  mkdirSync(paths.loaded, { recursive: true })
+  const file = path.join(paths.loaded, `${cand.id}.md`)
+  writeFileSync(file, text)
+  return { file, lines: text.split("\n").length, chars: text.length }
+}
+
+export const loadedLine = (cand: SessionCandidate, written: Loaded) =>
+  `Session ${shortId(cand.id)} "${titleOf(cand)}" written to ${written.file} (${written.lines} lines, ${Math.round(written.chars / 1000)}k characters). Read the whole file with the Read tool, from line 1 to line ${written.lines}, before acting.`
+
+export const load: Command = {
+  summary: "Write an earlier session to a file for the agent to read",
+  usage: "eunoe load <id>",
+  hidden: true,
+  details: [
+    "Writes the whole record of an earlier session in this directory to a file:",
+    "your messages, the key output lines and the agent's replies. The agent runs",
+    "this when a message continues that session, then reads the file start to",
+    "end. Ids come from eunoe sessions; a unique prefix is enough.",
+  ],
+  run(args) {
+    const cand = candidateOf(
+      args.find((a) => !a.startsWith("-")),
+      candidatesHere(),
+    )
+    line(loadedLine(cand, writeLoaded(cand)))
+  },
+}

package/src/cli/commands/mode.ts

@@ -1,13 +1,16 @@
-import { compactionOwner, loadConfig, saveConfig } from "../../config"
-import { MODES } from "../../config/constants"
-import type { Mode } from "../../config/types"
-import { editSettings, withCompactionOwner } from "../claude-settings"
-import { MODE_DESCRIPTIONS } from "../constants"
-import { routedDirs } from "../inspect"
-import { interactive, select } from "../prompt"
+import { compactionOwner, MODES, type Mode, readConfig, saveConfig } from "../../config"
+import type { Command } from "../command"
+import { editSettings, withCompactionOwner } from "../proxy/claude-settings"
+import { routedDirs } from "../proxy/inspect"
 import { isKnown, sessionArgs, shortId } from "../sessions"
-import type { Command } from "../types"
-import { c, fail, line, note, ok, warn } from "../ui"
+import { interactive, select } from "../terminal/prompt"
+import { c, fail, line, note, ok, warn } from "../terminal/ui"
+
+export const MODE_DESCRIPTIONS: Record<Mode, string> = {
+  default: "Recent turns whole, older turns folded; evidence and recall on",
+  compact: "Claude Code as it is, only its compaction replaced",
+  off: "Passthrough; Claude Code compacts on its own",
+}
 
 function listModes(current: Mode) {
   line()
@@ -17,50 +20,55 @@ function listModes(current: Mode) {
   }
 }
 
-export function applyMode(next: Mode, ids: string[]) {
-  const config = loadConfig()
-  if (ids.length) {
+function applyMode(next: Mode, ids: string[]) {
+  const config = readConfig()
+  if (ids.length > 0) {
     saveConfig({ sessions: { ...config.sessions, ...Object.fromEntries(ids.map((id) => [id, { ...config.sessions[id], mode: next }])) } })
     ok(`Mode ${c.bold(next)} for ${ids.map(shortId).join(", ")}  ${c.dim(MODE_DESCRIPTIONS[next])}`)
-    if (!routedDirs(config).length) warn("Claude Code isn't routed through eunoe. Run `eunoe start --session <id>`.")
+    if (routedDirs(config).length === 0) warn("Claude Code isn't routed through eunoe. Run `eunoe start --session <id>`.")
     const unseen = ids.filter((id) => !isKnown(id))
-    if (unseen.length) note(`Not seen through eunoe yet: ${unseen.map(shortId).join(", ")}. Check the id in Claude Code's /status.`)
+    if (unseen.length > 0) note(`Not seen through eunoe yet: ${unseen.map(shortId).join(", ")}. Check the id in Claude Code's /status.`)
     return
   }
   saveConfig({ mode: next })
-  const updated = loadConfig()
+  const updated = readConfig()
   editSettings(routedDirs(updated), (settings) => withCompactionOwner(settings, compactionOwner(updated)))
   ok(`Mode ${c.bold(next)}  ${c.dim(MODE_DESCRIPTIONS[next])}`)
 }
 
+function printModes(current: Mode) {
+  const config = readConfig()
+  listModes(current)
+  const own = Object.entries(config.sessions).filter(([, settings]) => settings.mode)
+  if (own.length > 0) {
+    line()
+    for (const [id, settings] of own) line(`  ${c.dim(shortId(id))}  ${settings.mode}`)
+  }
+  line()
+}
+
 export const mode: Command = {
   summary: "Pick how eunoe manages context",
   usage: "eunoe mode [default | compact | off] [--session <id>]",
   details: ["Without a mode it opens a picker. Takes effect on the next request; no restart needed."],
   options: [["--session <id>", "Set the mode for just this session (repeatable; a unique prefix is enough)"]],
   async run(args) {
-    const config = loadConfig()
-    const given = args.find((arg, i) => !arg.startsWith("-") && args[i - 1] !== "--session") as Mode | undefined
+    const config = readConfig()
+    const given = args.find((arg, i) => !arg.startsWith("-") && args[i - 1] !== "--session")
     const ids = sessionArgs(args)
     if (given) {
-      if (!MODES.includes(given)) fail(`Unknown mode: ${given}`, `Choose ${MODES.join(", ")}.`)
-      applyMode(given, ids)
-      return
-    }
-    const current = ids.length === 1 ? config.sessions[ids[0]]?.mode ?? config.mode : config.mode
-    if (!interactive) {
-      listModes(current)
-      const own = Object.entries(config.sessions).filter(([, settings]) => settings.mode)
-      if (own.length) {
-        line()
-        for (const [id, settings] of own) line(`  ${c.dim(shortId(id))}  ${settings.mode}`)
-      }
-      line()
+      if (!MODES.includes(given as Mode)) fail(`Unknown mode: ${given}`, `Choose ${MODES.join(", ")}.`)
+      applyMode(given as Mode, ids)
       return
     }
+    const current = ids.length === 1 ? (config.sessions[ids[0]]?.mode ?? config.mode) : config.mode
+    if (!interactive) return printModes(current)
     line()
-    const chosen = await select(ids.length ? `Mode for ${ids.map(shortId).join(", ")}` : "Mode", MODES.map((value) => ({ value, hint: MODE_DESCRIPTIONS[value] })), current)
-    if (chosen === null) return
-    applyMode(chosen, ids)
+    const chosen = await select(
+      ids.length > 0 ? `Mode for ${ids.map(shortId).join(", ")}` : "Mode",
+      MODES.map((value) => ({ value, hint: MODE_DESCRIPTIONS[value] })),
+      current,
+    )
+    if (chosen !== null) applyMode(chosen, ids)
   },
 }

package/src/cli/commands/peek.ts

@@ -0,0 +1,22 @@
+import type { Command } from "../command"
+import { candidateOf, candidatesHere, peekText, shortId } from "../sessions"
+import { fail, line } from "../terminal/ui"
+
+export const peek: Command = {
+  summary: "Show the excerpts of an earlier session that match some words",
+  usage: "eunoe peek <id> <words>",
+  hidden: true,
+  details: [
+    "Searches one earlier session in this directory for the words and prints the",
+    "excerpts that match: tool output and your messages, quoted exactly. For a",
+    "single fact such as an error message or a value. To continue the session's",
+    "work the agent should eunoe load it instead. Ids come from eunoe sessions.",
+  ],
+  run(args) {
+    const [id, ...rest] = args.filter((a) => !a.startsWith("-"))
+    const cand = candidateOf(id, candidatesHere())
+    const words = rest.join(" ").trim()
+    if (!words) fail("Say what to look for: eunoe peek <id> <words>")
+    line(peekText(cand, words) ?? fail(`Nothing in ${shortId(cand.id)} matches "${words}".`))
+  },
+}

package/src/cli/commands/replay.ts

@@ -0,0 +1,245 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs"
+import { cpus } from "node:os"
+import path from "node:path"
+import { claudeConfigDirs, DEFAULTS, parseTunable, readConfig } from "../../config"
+import { listEntries, projectFolderName, projectFolders } from "../../transcript/locate"
+import type { Command } from "../command"
+import { cleanupDays } from "../proxy/claude-settings"
+import { recentRequests } from "../proxy/inspect"
+import type { ReplayedSession, ReplayFailure, ReplayOptions } from "../replay"
+import { shortId } from "../sessions"
+import { c, fail, line, percent, plural, rows, table, tilde, tokens, useColor, warn } from "../terminal/ui"
+
+interface Target {
+  file: string
+  bytes: number
+  lastActive: number
+}
+
+const WINDOW = 1_000_000
+const HEAD_BYTES = 64 * 1024
+const TOP_SESSIONS = 10
+
+function targets(configDirs: string[], ids: string[], here: string | null): Target[] {
+  const seen = new Map<string, Target>()
+  const wanted = (id: string) => ids.length === 0 || ids.some((prefix) => id.startsWith(prefix))
+  const onlyFolder = here ? projectFolderName(here) : null
+  for (const folder of projectFolders(configDirs)) {
+    if (onlyFolder && path.basename(folder) !== onlyFolder) continue
+    for (const name of listEntries(folder)) {
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/.test(name)) continue
+      const id = name.slice(0, -".jsonl".length)
+      if (!wanted(id) || seen.has(id)) continue
+      const file = path.join(folder, name)
+      const stat = statSync(file)
+      seen.set(id, { file, bytes: stat.size, lastActive: stat.mtimeMs })
+    }
+  }
+  return [...seen.values()].sort((a, b) => b.bytes - a.bytes)
+}
+
+function fixedTokens(): { value: number; measured: boolean } {
+  const sizes = recentRequests()
+    .flatMap((r) => (r.charsFixed && r.charsOut && r.input ? [Math.round((r.input * r.charsFixed) / r.charsOut)] : []))
+    .sort((a, b) => a - b)
+  if (sizes.length === 0) return { value: 30_000, measured: false }
+  return { value: sizes[Math.floor(sizes.length / 2)], measured: true }
+}
+
+const day = (ms: number) => new Date(ms).toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" })
+
+const duration = (ms: number) => (ms < 60_000 ? `${Math.max(1, Math.round(ms / 1000))}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`)
+const size = (bytes: number) => (bytes >= 1e9 ? `${(bytes / 1e9).toFixed(1)} GB` : `${Math.round(bytes / 1e6)} MB`)
+const fewer = (plain: number, eunoe: number) => (plain > 0 ? percent(1 - eunoe / plain) : "–")
+
+function startedAt(target: Target): number {
+  const buffer = Buffer.alloc(HEAD_BYTES)
+  let read = 0
+  try {
+    const fd = openSync(target.file, "r")
+    read = readSync(fd, buffer, 0, HEAD_BYTES, 0)
+    closeSync(fd)
+  } catch {
+    return target.lastActive
+  }
+  const found = /"timestamp":"([^"]+)"/.exec(buffer.toString("utf8", 0, read))
+  const at = found ? Date.parse(found[1]) : Number.NaN
+  return Number.isNaN(at) ? target.lastActive : Math.min(at, target.lastActive)
+}
+
+function historyLine(list: Target[], keepDays: number): string {
+  const span = `${day(Math.min(...list.map(startedAt)))} – ${day(Math.max(...list.map((t) => t.lastActive)))}`
+  return `${span}  ${c.dim(`· the sessions still on disk; Claude Code deletes sessions idle for ${keepDays} days (cleanupPeriodDays), so totals cover a moving window`)}`
+}
+
+async function replayAll(list: Target[], options: ReplayOptions, onDone: (done: number, bytes: number) => void): Promise<{ results: ReplayedSession[]; failures: ReplayFailure[] }> {
+  const results: ReplayedSession[] = []
+  const failures: ReplayFailure[] = []
+  const queue = [...list]
+  let bytesDone = 0
+  const workers = Math.max(1, Math.min(8, cpus().length - 1, list.length))
+  await Promise.all(
+    Array.from(
+      { length: workers },
+      () =>
+        new Promise<void>((resolve) => {
+          let worker = new Worker(new URL("../replay/worker.ts", import.meta.url).href)
+          let current: Target | undefined
+          const finish = (target: Target) => {
+            bytesDone += target.bytes
+            onDone(results.length + failures.length, bytesDone)
+          }
+          const next = () => {
+            current = queue.shift()
+            if (!current) {
+              worker.terminate()
+              resolve()
+              return
+            }
+            worker.postMessage({ file: current.file, options })
+          }
+          const listen = () => {
+            worker.onmessage = (event: MessageEvent<ReplayedSession | ReplayFailure>) => {
+              if ("error" in event.data) failures.push(event.data)
+              else results.push(event.data)
+              if (current) finish(current)
+              next()
+            }
+            worker.onerror = (event) => {
+              event.preventDefault()
+              if (current) {
+                failures.push({ file: current.file, error: event.message || "worker crashed" })
+                finish(current)
+              }
+              worker.terminate()
+              worker = new Worker(new URL("../replay/worker.ts", import.meta.url).href)
+              listen()
+              next()
+            }
+          }
+          listen()
+          next()
+        }),
+    ),
+  )
+  return { results, failures }
+}
+
+export const replay: Command = {
+  summary: "Replay your Claude Code history through eunoe and show what it saves",
+  usage: "eunoe replay [session…] [--here] [--window <tokens>]",
+  details: [
+    "Reads every Claude Code session on this machine and replays each request",
+    "through eunoe's folding, without calling Claude. Shows the input tokens",
+    "and the cache-weighted cost plain Claude Code would have paid against what",
+    "eunoe would have sent, the folds it would have made, and the compactions",
+    "Claude Code would have needed. Deterministic and offline.",
+  ],
+  options: [
+    ["--here", "Only sessions from the current directory"],
+    ["--window <tokens>", `Context window to assume (default ${tokens(WINDOW)})`],
+    ["--turn-cap <tokens|off>", "Override the turnCap setting for this replay"],
+  ],
+  async run(args) {
+    const windowAt = args.indexOf("--window")
+    const capAt = args.indexOf("--turn-cap")
+    const optionValues = [windowAt, capAt].filter((at) => at !== -1).map((at) => args[at + 1])
+    const ids = args.filter((a) => !a.startsWith("-") && !optionValues.includes(a))
+    const window = windowAt === -1 ? WINDOW : Number(args[windowAt + 1])
+    if (!(window > 0)) fail("--window needs a token count", "eunoe replay --window 200000")
+    const config = readConfig()
+    const turnCap = capAt === -1 ? config.turnCap : parseTunable("turnCap", args[capAt + 1] ?? "")
+    if (turnCap === null) fail("--turn-cap needs a token count or off", "eunoe replay --turn-cap off")
+    const configDirs = claudeConfigDirs(config)
+    const list = targets(configDirs, ids, args.includes("--here") ? process.cwd() : null)
+    if (list.length === 0) fail("No Claude Code sessions found.")
+    const totalBytes = list.reduce((total, entry) => total + entry.bytes, 0)
+    const fixed = fixedTokens()
+    line()
+    const options: ReplayOptions = { config: { ...config, turnCap, mode: config.mode === "off" ? DEFAULTS.mode : config.mode }, window, fixedTokens: fixed.value }
+    const started = Date.now()
+    const progress = useColor && process.stdout.isTTY
+    const { results, failures } = await replayAll(list, options, (done, doneBytes) => {
+      if (!progress) return
+      const left = doneBytes > 0 ? ` · ~${duration(((Date.now() - started) / doneBytes) * (totalBytes - doneBytes))} left` : ""
+      process.stdout.write(`\r\x1b[K  ${c.dim(`Replaying ${done} / ${list.length} sessions · ${size(doneBytes)} of ${size(totalBytes)}${left}`)}`)
+    })
+    if (progress) process.stdout.write("\r\x1b[K")
+    const sum = results.reduce(
+      (acc, r) => {
+        for (const key of ["requests", "folds", "dropped", "nativeCompactions", "discarded", "plainTokens", "eunoeTokens", "plainCost", "eunoeCost"] as const) acc[key] += r[key]
+        acc.peakPlain = Math.max(acc.peakPlain, r.peakPlain)
+        acc.peakEunoe = Math.max(acc.peakEunoe, r.peakEunoe)
+        return acc
+      },
+      { requests: 0, folds: 0, dropped: 0, nativeCompactions: 0, discarded: 0, plainTokens: 0, eunoeTokens: 0, plainCost: 0, eunoeCost: 0, peakPlain: 0, peakEunoe: 0 },
+    )
+    const compared = results.filter((r) => r.requests > 0)
+    line(`  ${c.bold("eunoe replay")}  ${c.dim("your Claude Code history, as eunoe would have sent it")}`)
+    line()
+    rows(
+      [
+        ["Sessions", `${c.bold(compared.length.toLocaleString())} replayed  ${c.dim("·")}  ${size(totalBytes)}  ${c.dim("·")}  ${duration(Date.now() - started)}`],
+        ["History", historyLine(list, cleanupDays(configDirs))],
+        ["Requests", c.bold(sum.requests.toLocaleString())],
+        ["Window", `${tokens(window)}  ${c.dim(`· ${tokens(fixed.value)} of it system prompt and tools, ${fixed.measured ? "from your logged requests" : "assumed"}`)}`],
+      ],
+      4,
+    )
+    line()
+    rows(
+      [
+        [
+          "History kept",
+          `eunoe ${c.bold(c.green("every turn"))}, folded or whole  ${c.dim("·")}  Claude Code compacted ${c.bold(sum.nativeCompactions.toLocaleString())} time${sum.nativeCompactions === 1 ? "" : "s"}, ${c.bold(tokens(sum.discarded))} tokens of conversation replaced by summaries`,
+        ],
+        [
+          "Input tokens",
+          `plain ${tokens(sum.plainTokens)}  ${c.dim("→")}  eunoe ${c.bold(tokens(sum.eunoeTokens))} tokens   ${c.green(c.bold(`${fewer(sum.plainTokens, sum.eunoeTokens)} fewer`))}  ${c.dim("the conversation; system prompt and tools are the same on both sides")}`,
+        ],
+        ["Cost", `${c.green(c.bold(`${fewer(sum.plainCost, sum.eunoeCost)} cheaper`))}  ${c.dim("cache reads at 0.1×, writes at 1.25×")}`],
+        ["Folds", c.bold(sum.folds.toLocaleString())],
+        ["Folds dropped", `${c.bold(sum.dropped.toLocaleString())} ${c.dim("folded turns removed entirely to fit the window")}`],
+        ["Peak context", `plain ${tokens(sum.peakPlain)}  ${c.dim("→")}  eunoe ${c.bold(tokens(sum.peakEunoe))}`],
+      ],
+      4,
+    )
+    const saved = [...compared]
+      .filter((r) => r.nativeCompactions > 0)
+      .sort((a, b) => b.discarded - a.discarded)
+      .slice(0, TOP_SESSIONS)
+    if (saved.length > 0) {
+      line()
+      line(`  ${c.dim("Sessions Claude Code would have compacted, by history it would have lost")}`)
+      table(
+        saved.map((r) => [
+          c.cyan(shortId(r.id)),
+          (r.title ?? (r.cwd ? tilde(r.cwd) : "")).slice(0, 40),
+          c.bold(c.green(`${plural(r.nativeCompactions, "compaction")} avoided`)),
+          `${tokens(r.discarded)} tokens kept`,
+          c.dim(`${plural(r.folds, "fold")} · ${tokens(r.plainTokens)} → ${tokens(r.eunoeTokens)} tokens`),
+        ]),
+      )
+    }
+    const top = [...compared].sort((a, b) => b.plainTokens - b.eunoeTokens - (a.plainTokens - a.eunoeTokens)).slice(0, TOP_SESSIONS)
+    if (top.length > 1) {
+      line()
+      line(`  ${c.dim("Biggest token savings")}`)
+      table(
+        top.map((r) => [
+          c.cyan(shortId(r.id)),
+          (r.title ?? (r.cwd ? tilde(r.cwd) : "")).slice(0, 40),
+          `${tokens(r.plainTokens)} ${c.dim("→")} ${tokens(r.eunoeTokens)} tokens`,
+          c.green(c.bold(`${tokens(r.plainTokens - r.eunoeTokens)} tokens saved`)),
+          c.dim(`${fewer(r.plainTokens, r.eunoeTokens)} fewer`),
+          c.dim(plural(r.folds, "fold")),
+        ]),
+      )
+    }
+    if (failures.length > 0) {
+      line()
+      warn(`${plural(failures.length, "session")} couldn't be replayed and ${failures.length === 1 ? "is" : "are"} not counted: ${failures.map((f) => `${shortId(path.basename(f.file, ".jsonl"))} (${f.error})`).join(", ")}`)
+    }
+    line()
+  },
+}