@chroxify/eunoe 1.0.0 → 1.2.0

package/src/cli/commands/serve.ts

@@ -1,10 +1,22 @@
-import { loadConfig } from "../../config"
+import { readConfig } from "../../config"
 import { serve as startProxy } from "../../proxy/server"
 import { VERSION } from "../../version"
-import { proxyUrl } from "../claude-settings"
-import { probe } from "../inspect"
-import type { Command } from "../types"
-import { c, fail, line } from "../ui"
+import type { Command } from "../command"
+import { proxyUrl } from "../proxy/claude-settings"
+import { probe } from "../proxy/inspect"
+import { c, fail, line, warn } from "../terminal/ui"
+
+async function bind(port: number) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return startProxy(port)
+    } catch (error) {
+      if (attempt >= 30) throw error
+      warn(`Port ${port} is busy (${String(error)}), trying again in 1000ms`)
+      await Bun.sleep(1_000)
+    }
+  }
+}
 
 export const serve: Command = {
   summary: "Run the proxy in the foreground",
@@ -12,9 +24,12 @@ export const serve: Command = {
   details: ["`eunoe start` runs this for you in the background. Use it directly where there is no launchd."],
   hidden: true,
   async run() {
-    const config = loadConfig()
+    const config = readConfig()
     if (await probe(config.port)) fail(`Something is already serving eunoe on port ${config.port}`, "Stop it first, or set another port in ~/.eunoe/config.json.")
-    startProxy(config.port)
+    const keepGoing = (error: unknown) => warn(`eunoe kept going after an error: ${String(error)}`)
+    process.on("uncaughtException", keepGoing)
+    process.on("unhandledRejection", keepGoing)
+    await bind(config.port)
     line(`${c.bold("eunoe")} ${c.dim(VERSION)}  listening on ${c.cyan(proxyUrl(config.port))}  ${c.dim(`mode ${config.mode} · Ctrl-C to stop`)}`)
   },
 }

package/src/cli/commands/sessions.ts

@@ -0,0 +1,70 @@
+import { readConfig } from "../../config"
+import type { Command } from "../command"
+import { routedDirs } from "../proxy/inspect"
+import { askOf, candidatesHere, continuePrompt, copy, metaOf, shortId } from "../sessions"
+import { browse, filterCandidates, UNTITLED } from "../sessions/browse"
+import type { SessionCandidate } from "../sessions/source"
+import { interactive } from "../terminal/prompt"
+import { c, fail, line, ok, warn, wrap } from "../terminal/ui"
+
+const INDENT = 6
+
+const askWidth = () => Math.max(40, Math.min(100, (process.stdout.columns ?? 100 + INDENT) - INDENT - 12))
+
+function ask(label: string, text: string | undefined) {
+  const [first = "", ...rest] = wrap(askOf(text), askWidth())
+  line(`${" ".repeat(INDENT)}${c.dim(label)}  ${first}`)
+  for (const more of rest) line(`${" ".repeat(INDENT + label.length + 2)}${more}`)
+}
+
+function show(cand: SessionCandidate) {
+  const title = cand.label ? c.bold(cand.label) : c.dim(UNTITLED)
+  line(`  ${c.cyan(shortId(cand.id))}  ${title}  ${c.dim(metaOf(cand))}`)
+  ask("first", cand.asks[0])
+  ask("last ", cand.asks.at(-1))
+  line()
+}
+
+function listSessions(words: string, candidates: SessionCandidate[]) {
+  const order = filterCandidates(words, candidates)
+  line()
+  line(`  ${c.dim(words ? `Earlier sessions here, closest to "${words}" first` : "Earlier sessions here, newest first")}`)
+  line()
+  for (const cand of order) show(cand)
+  if (order.length === 0) line(`  ${c.dim(`Nothing matches "${words}".`)}`)
+}
+
+function handOff(id: string) {
+  const prompt = continuePrompt(id)
+  line()
+  ok(`${c.bold(prompt)}  ${copy(prompt) ? c.dim("copied") : ""}`)
+  if (routedDirs(readConfig()).length === 0) warn("Claude Code isn't routed through eunoe, so the agent won't know to load it (eunoe start).")
+  line()
+}
+
+export const sessions: Command = {
+  summary: "Pick an earlier session for the agent to continue from",
+  usage: "eunoe sessions [words] [--list]",
+  details: [
+    "Browse this directory's earlier Claude Code sessions: type to filter, pick",
+    "one, and a {ee:continue:<id>} marker is copied. Paste it into any Claude Code",
+    "chat along with what you want done: eunoe attaches that whole session to the",
+    "message, and its dropped output stays searchable from then on. Words start",
+    "the filter.",
+    "",
+    "--list, or a pipe, prints the sessions newest first with each one's first",
+    "and last request. That is what the agent reads when it runs this itself.",
+  ],
+  options: [["--list", "Print the sessions instead of browsing them"]],
+  async run(args) {
+    const words = args
+      .filter((a) => !a.startsWith("-"))
+      .join(" ")
+      .trim()
+    const candidates = candidatesHere()
+    if (candidates.length === 0) fail("No earlier sessions in this directory.")
+    if (args.includes("--list") || !interactive) return listSessions(words, candidates)
+    const chosen = await browse("Earlier sessions here", candidates, words, "↑↓ move · type to filter · enter copy the marker · esc quit")
+    if (chosen) handOff(chosen.id)
+  },
+}

package/src/cli/commands/settings.ts

@@ -1,66 +1,95 @@
-import { loadConfig, overrides, parseTunable, saveConfig } from "../../config"
-import { DEFAULTS, TUNABLES } from "../../config/constants"
-import type { Tunable } from "../../config/types"
-import { TUNABLE_DESCRIPTIONS, TUNABLE_HINTS } from "../constants"
-import { input, interactive, select } from "../prompt"
+import { DEFAULTS, overrides, parseTunable, readConfig, saveConfig, TUNABLES, type Tunable } from "../../config"
+import type { Command } from "../command"
 import { sessionArgs, shortId } from "../sessions"
-import type { Command } from "../types"
-import { c, fail, line, ok, rows } from "../ui"
+import { input, interactive, select } from "../terminal/prompt"
+import { c, fail, line, ok, rows } from "../terminal/ui"
+
+const DESCRIPTIONS: Record<Tunable, string> = {
+  keep: "Turns kept whole at the end, in default mode",
+  budget: "Tokens of older detail that trigger a fold, in default mode",
+  turnCap: "A kept turn larger than this many tokens is folded at once, live turn excepted; or off",
+  compactAt: "Share of the context window that triggers the cut",
+  keepTurns: "Earlier turns kept after a cut",
+  search: "How transcripts are written for the agent to search",
+  rerank: "Typesafe model that reorders recall, or off",
+}
+
+const HINTS: Record<Tunable, string> = {
+  keep: "a whole number, 1 or more",
+  budget: "a token count, 1000 or more",
+  turnCap: "a token count, 1000 or more, or off",
+  compactAt: "a number above 0, up to 1",
+  keepTurns: "a whole number or all",
+  search: "markdown, xml, jsonl or qmd",
+  rerank: "a model name such as jev-preview, or off",
+}
 
 const RESET = "default"
 
+const forSessions = (ids: string[]) => ids.map(shortId).join(", ")
+
 function listSettings() {
-  const config = loadConfig()
+  const config = readConfig()
   line()
   const width = Math.max(...TUNABLES.map((name) => String(config[name]).length))
-  rows(TUNABLES.map((name) => {
-    const value = String(config[name])
-    const changed = config[name] !== DEFAULTS[name]
-    return [name, `${c.bold(value.padEnd(width))}  ${c.dim(TUNABLE_DESCRIPTIONS[name])}${changed ? c.dim(`  (default ${DEFAULTS[name]})`) : ""}`]
-  }))
-  const own = Object.entries(config.sessions).map(([id, settings]) => [id, overrides(settings)] as const).filter(([, values]) => Object.keys(values).length)
-  if (own.length) {
+  rows(
+    TUNABLES.map((name) => {
+      const changed = config[name] !== DEFAULTS[name]
+      return [name, `${c.bold(String(config[name]).padEnd(width))}  ${c.dim(DESCRIPTIONS[name])}${changed ? c.dim(`  (default ${DEFAULTS[name]})`) : ""}`]
+    }),
+  )
+  const own = Object.entries(config.sessions)
+    .map(([id, session]) => [id, overrides(session)] as const)
+    .filter(([, values]) => Object.keys(values).length > 0)
+  if (own.length > 0) {
     line()
-    for (const [id, values] of own) line(`  ${c.cyan(shortId(id))}  ${Object.entries(values).map(([name, value]) => `${name} ${c.bold(String(value))}`).join(c.dim("  ·  "))}`)
+    for (const [id, values] of own) {
+      const shown = Object.entries(values).map(([name, value]) => `${name} ${c.bold(String(value))}`)
+      line(`  ${c.cyan(shortId(id))}  ${shown.join(c.dim("  ·  "))}`)
+    }
   }
   line()
 }
 
-function applySetting(name: Tunable, raw: string, ids: string[]) {
-  const config = loadConfig()
-  if (raw === RESET) {
-    if (!ids.length) fail(`\`${RESET}\` only applies with --session`, `eunoe settings set ${name} ${RESET} --session <id>`)
-    const sessions = { ...config.sessions }
-    for (const id of ids) {
-      if (!sessions[id]) continue
-      const { [name]: _, ...rest } = sessions[id]
-      sessions[id] = rest
-    }
-    saveConfig({ sessions })
-    ok(`${name} back to the default (${c.bold(String(config[name]))}) for ${ids.map(shortId).join(", ")}`)
-    return
+function resetSetting(name: Tunable, ids: string[]) {
+  const config = readConfig()
+  if (ids.length === 0) fail(`\`${RESET}\` only applies with --session`, `eunoe settings set ${name} ${RESET} --session <id>`)
+  const sessions = { ...config.sessions }
+  for (const id of ids) {
+    if (!sessions[id]) continue
+    const { [name]: _, ...rest } = sessions[id]
+    sessions[id] = rest
   }
+  saveConfig({ sessions })
+  ok(`${name} back to the default (${c.bold(String(config[name]))}) for ${forSessions(ids)}`)
+}
+
+function applySetting(name: Tunable, raw: string, ids: string[]) {
+  if (raw === RESET) return resetSetting(name, ids)
+  const config = readConfig()
   const value = parseTunable(name, raw)
-  if (value === null) fail(`Not a valid ${name}: ${raw}`, `Expected ${TUNABLE_HINTS[name]}.`)
-  if (ids.length) {
-    saveConfig({ sessions: { ...config.sessions, ...Object.fromEntries(ids.map((id) => [id, { ...config.sessions[id], [name]: value }])) } })
-    ok(`${name} ${c.bold(String(value))} for ${ids.map(shortId).join(", ")}`)
-    if (config.scope === "sessions" && ids.some((id) => !config.sessions[id])) line(`  ${c.dim("eunoe only manages sessions you started it for: eunoe start --session <id>")}`)
+  if (value === null) fail(`Not a valid ${name}: ${raw}`, `Expected ${HINTS[name]}.`)
+  if (ids.length === 0) {
+    saveConfig({ [name]: value })
+    ok(`${name} ${c.bold(String(value))}`)
     return
   }
-  saveConfig({ [name]: value })
-  ok(`${name} ${c.bold(String(value))}`)
+  saveConfig({ sessions: { ...config.sessions, ...Object.fromEntries(ids.map((id) => [id, { ...config.sessions[id], [name]: value }])) } })
+  ok(`${name} ${c.bold(String(value))} for ${forSessions(ids)}`)
+  if (config.scope === "sessions" && ids.some((id) => !config.sessions[id])) line(`  ${c.dim("eunoe only manages sessions you started it for: eunoe start --session <id>")}`)
 }
 
 async function pickSetting(ids: string[]) {
-  const config = loadConfig()
+  const config = readConfig()
   line()
-  const name = await select<Tunable>(ids.length ? `Setting for ${ids.map(shortId).join(", ")}` : "Setting", TUNABLES.map((value) => ({ value, hint: `${String(config[value]).padEnd(12)} ${TUNABLE_DESCRIPTIONS[value]}` })))
+  const name = await select<Tunable>(
+    ids.length > 0 ? `Setting for ${forSessions(ids)}` : "Setting",
+    TUNABLES.map((value) => ({ value, hint: `${String(config[value]).padEnd(12)} ${DESCRIPTIONS[value]}` })),
+  )
   if (name === null) return
-  const current = ids.length === 1 ? config.sessions[ids[0]]?.[name] ?? config[name] : config[name]
-  const raw = await input(`${name}  ${c.dim(TUNABLE_HINTS[name])}`, `${current}  (current)`)
-  if (raw === null || raw === "") return
-  applySetting(name, raw, ids)
+  const current = ids.length === 1 ? (config.sessions[ids[0]]?.[name] ?? config[name]) : config[name]
+  const raw = await input(`${name}  ${c.dim(HINTS[name])}`, `${current}  (current)`)
+  if (raw) applySetting(name, raw, ids)
 }
 
 export const settings: Command = {
@@ -68,33 +97,23 @@ export const settings: Command = {
   usage: "eunoe settings [list | set <key> <value>] [--session <id>]",
   details: [
     "Without arguments it opens a picker. Keys:",
-    ...TUNABLES.map((key) => `  ${key.padEnd(10)} ${TUNABLE_DESCRIPTIONS[key]} ${c.dim(`(${TUNABLE_HINTS[key]})`)}`),
+    ...TUNABLES.map((key) => `  ${key.padEnd(10)} ${DESCRIPTIONS[key]} ${c.dim(`(${HINTS[key]})`)}`),
     "",
     `With --session, the value applies to that session only; \`${RESET}\` removes its own value.`,
     "Takes effect on the next request; no restart needed.",
   ],
   options: [["--session <id>", "Change it for just this session (repeatable; a unique prefix is enough)"]],
-  async run(args) {
-    const words = args.filter((arg, i) => !arg.startsWith("-") && args[i - 1] !== "--session")
+  run(args) {
+    const [verb, key, raw] = args.filter((arg, i) => !arg.startsWith("-") && args[i - 1] !== "--session")
     const ids = sessionArgs(args)
-    const [verb, key, raw] = words
-    if (!verb) {
-      if (interactive) await pickSetting(ids)
-      else listSettings()
-      return
-    }
-    if (verb === "list") {
-      listSettings()
-      return
-    }
-    if (verb !== "set") fail(`Unknown subcommand: ${verb}`, "Use `eunoe settings list` or `eunoe settings set <key> <value>`.")
+    if (verb === "list" || (!verb && !interactive)) return listSettings()
+    if (verb && verb !== "set") fail(`Unknown subcommand: ${verb}`, "Use `eunoe settings list` or `eunoe settings set <key> <value>`.")
     if (!key) {
-      if (interactive) await pickSetting(ids)
-      else fail("set needs a key and a value", "eunoe settings set <key> <value>")
-      return
+      if (!interactive) fail("set needs a key and a value", "eunoe settings set <key> <value>")
+      return pickSetting(ids)
     }
     if (!TUNABLES.includes(key as Tunable)) fail(`Unknown setting: ${key}`, `Choose ${TUNABLES.join(", ")}.`)
-    if (raw === undefined) fail(`${key} needs a value`, `eunoe settings set ${key} <${TUNABLE_HINTS[key as Tunable]}>`)
+    if (raw === undefined) fail(`${key} needs a value`, `eunoe settings set ${key} <${HINTS[key as Tunable]}>`)
     applySetting(key as Tunable, raw, ids)
   },
 }

package/src/cli/commands/start.ts

@@ -1,18 +1,20 @@
 import { existsSync } from "node:fs"
 import path from "node:path"
-import { claudeConfigDirs, compactionOwner, loadConfig, saveConfig } from "../../config"
-import type { Config } from "../../config/types"
-import { flagValues } from "../args"
-import { editSettings, withEunoe } from "../claude-settings"
-import { MODE_DESCRIPTIONS } from "../constants"
-import { routedDirs } from "../inspect"
-import { startService } from "../service"
+import { type Config, claudeConfigDirs, compactionOwner, modeFor, readConfig, saveConfig } from "../../config"
+import { seenSessions } from "../../proxy/sessions"
+import type { Command } from "../command"
+import { editSettings, withEunoe } from "../proxy/claude-settings"
+import { routedDirs } from "../proxy/inspect"
+import { isIdle, isTerminal, type LiveSession, listLiveSessions, restartSessions, unroutedSessions } from "../proxy/live"
+import { startService } from "../proxy/service"
+import { clearWatch } from "../proxy/watch"
 import { isKnown, sessionArgs, shortId } from "../sessions"
-import type { Command } from "../types"
-import { c, fail, line, listFiles, note, ok, rows, tilde } from "../ui"
+import { flagValues } from "../terminal/args"
+import { c, fail, line, listFiles, note, ok, plural, rows, tilde } from "../terminal/ui"
+import { MODE_DESCRIPTIONS } from "./mode"
 
 function scoped(config: Config, ids: string[]): Partial<Config> {
-  if (!ids.length) return { scope: "all" }
+  if (ids.length === 0) return { scope: "all" }
   const managingAll = config.scope === "all" && routedDirs(config).length > 0
   const sessions = { ...config.sessions }
   for (const id of ids) {
@@ -22,13 +24,42 @@ function scoped(config: Config, ids: string[]): Partial<Config> {
   return { scope: managingAll ? "all" : "sessions", sessions }
 }
 
+function managedSessions(config: Config): string {
+  if (config.scope === "all") return "all"
+  const ids = Object.entries(config.sessions)
+    .filter(([, own]) => own.mode !== "off")
+    .map(([id]) => shortId(id))
+  return `only ${ids.join(", ")}`
+}
+
+function restartUnrouted(config: Config, skip: boolean): { restarted: LiveSession[]; busy: LiveSession[] } {
+  const lastSeen = new Map(seenSessions().map(([id, seen]) => [id, seen.lastSeen]))
+  const managed = (id: string) => modeFor(config, id) !== "off"
+  const unrouted = unroutedSessions(listLiveSessions(claudeConfigDirs(config)), lastSeen, managed, process.env.CLAUDE_CODE_SESSION_ID)
+  if (skip) return { restarted: [], busy: unrouted }
+  return { restarted: restartSessions(unrouted.filter(isIdle)), busy: unrouted.filter((session) => !isIdle(session)) }
+}
+
+function reportRestarts({ restarted, busy }: { restarted: LiveSession[]; busy: LiveSession[] }) {
+  if (restarted.length > 0) {
+    ok(`Restarted ${plural(restarted.length, "idle session")} so they go through eunoe`)
+    if (restarted.some((session) => !isTerminal(session))) note("App sessions come back on their next message.")
+    if (restarted.some(isTerminal)) note("Resume the terminal ones with:")
+    for (const session of restarted.filter(isTerminal)) line(`    ${c.dim(`cd ${tilde(session.cwd)} && claude --resume ${session.sessionId}`)}`)
+    line()
+  }
+  if (busy.length > 0) note(`Still on the direct route until restarted: ${busy.map((session) => shortId(session.sessionId)).join(", ")}.`)
+}
+
 export const start: Command = {
   summary: "Route Claude Code through eunoe",
-  usage: "eunoe start [--session <id>] [--config-dir <dir>]",
+  usage: "eunoe start [--session <id>] [--config-dir <dir>] [--no-restart]",
   details: [
     "Starts the background proxy if it isn't running (setting it up the first time)",
     "and points Claude Code at it through ANTHROPIC_BASE_URL in settings.json.",
-    "New sessions pick it up; restart the ones already running.",
+    "New sessions pick it up. Idle sessions already running are restarted so they",
+    "pick it up too: app-hosted ones resume on their next message, terminal ones",
+    "print the command that resumes them. Busy sessions are left alone.",
     "",
     "With --session, eunoe manages only the sessions you name and passes the rest",
     "through untouched. Session ids are in Claude Code's /status, or `eunoe status`.",
@@ -36,29 +67,33 @@ export const start: Command = {
   options: [
     ["--session <id>", "Only manage this session (repeatable; a unique prefix is enough)"],
     ["--config-dir <dir>", "Also manage this Claude config directory (repeatable, remembered)"],
+    ["--no-restart", "Leave running sessions alone"],
   ],
   async run(args) {
     const added = flagValues(args, "--config-dir").map((dir) => path.resolve(dir))
     for (const dir of added) if (!existsSync(dir)) fail(`No such directory: ${tilde(dir)}`)
-    if (added.length) saveConfig({ claudeConfigDirs: [...new Set([...loadConfig().claudeConfigDirs, ...added])] })
+    if (added.length > 0) saveConfig({ claudeConfigDirs: [...new Set([...readConfig().claudeConfigDirs, ...added])] })
     const ids = sessionArgs(args)
-    saveConfig(scoped(loadConfig(), ids))
-    const config = loadConfig()
+    saveConfig(scoped(readConfig(), ids))
+    const config = readConfig()
 
     line()
-    await startService(config)
+    if (!(await startService(config))) fail("Claude Code was left alone because the proxy isn't up.", "Nothing is routed through a proxy that can't answer. Fix the proxy and run `eunoe start` again.")
+    clearWatch()
     const touched = editSettings(claudeConfigDirs(config), (settings) => withEunoe(settings, config.port, compactionOwner(config)))
     ok("Claude Code routed through eunoe")
-    listFiles(touched.length ? touched : routedDirs(config).map((dir) => path.join(dir, "settings.json")))
+    listFiles(touched.length > 0 ? touched : routedDirs(config).map((dir) => path.join(dir, "settings.json")))
     line()
     rows([
       ["Mode", `${c.bold(config.mode)}  ${c.dim(MODE_DESCRIPTIONS[config.mode])}`],
-      ["Sessions", config.scope === "all" ? "all" : `only ${Object.entries(config.sessions).filter(([, own]) => own.mode !== "off").map(([id]) => shortId(id)).join(", ")}`],
+      ["Sessions", managedSessions(config)],
     ])
     line()
-    const unseen = ids.filter((id) => !isKnown(id))
-    if (unseen.length) note(`Not seen through eunoe yet: ${unseen.map(shortId).join(", ")}. It applies once that session's requests come through; one started before routing needs a restart.`)
-    else note(ids.length ? "Takes effect on the session's next request." : "New sessions go through eunoe. Restart any that are already running.")
+    const restarts = restartUnrouted(config, args.includes("--no-restart"))
+    reportRestarts(restarts)
+    const unseen = ids.filter((id) => !isKnown(id) && !restarts.restarted.some((session) => session.sessionId === id))
+    if (unseen.length > 0) note(`Not seen through eunoe yet: ${unseen.map(shortId).join(", ")}. It applies once that session's requests come through; one started before routing needs a restart.`)
+    else note(ids.length > 0 ? "Takes effect on the session's next request." : "New sessions go through eunoe.")
     line()
   },
 }

package/src/cli/commands/stats.ts

@@ -0,0 +1,233 @@
+import { claudeConfigDirs, readConfig } from "../../config"
+import type { Command } from "../command"
+import { cleanupDays } from "../proxy/claude-settings"
+import { type RequestRecord, recentRequests } from "../proxy/inspect"
+import { savedTokens, totals } from "../proxy/stats"
+import { c, fail, line, percent, plural, table, tokens, wrap } from "../terminal/ui"
+import { costOf, ratesOf, readUsage, type UsageEntry, usageFiles } from "../usage"
+
+interface Bucket {
+  start: number
+  label: string
+  usage: UsageEntry[]
+  logged: RequestRecord[]
+}
+
+type Matched = Map<RequestRecord, UsageEntry>
+
+const DAY = 86_400_000
+const MATCH_WITHIN = 10 * 60_000
+const NOTE_WIDTH = 110
+const DEFAULT_DAYS = 7
+const DEFAULT_WEEKS = 8
+
+const midnight = (ms: number) => new Date(new Date(ms).toDateString()).getTime()
+const addDays = (ms: number, days: number) => {
+  const date = new Date(ms)
+  date.setDate(date.getDate() + days)
+  return date.getTime()
+}
+const monday = (ms: number) => addDays(midnight(ms), -((new Date(ms).getDay() + 6) % 7))
+const short = (ms: number) => new Date(ms).toLocaleDateString(undefined, { month: "short", day: "numeric" })
+const dayLabel = (ms: number) => new Date(ms).toLocaleDateString(undefined, { weekday: "short", month: "short", day: "numeric" })
+const dollars = (amount: number) => `$${amount >= 100 ? Math.round(amount).toLocaleString() : amount.toFixed(2)}`
+
+export function buckets(now: number, weekly: boolean, count: number): Bucket[] {
+  const step = weekly ? 7 : 1
+  const last = weekly ? monday(now) : midnight(now)
+  return Array.from({ length: count }, (_, i) => {
+    const start = addDays(last, -step * (count - 1 - i))
+    const label = weekly ? `${short(start)} – ${short(addDays(start, 6))}` : dayLabel(start)
+    return { start, label, usage: [], logged: [] }
+  })
+}
+
+function place(list: Bucket[], at: number, add: (bucket: Bucket) => void) {
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    if (at < list[i].start) continue
+    add(list[i])
+    return
+  }
+}
+
+export function summarize(usage: UsageEntry[]) {
+  const sum = { requests: usage.length, input: 0, output: 0, cacheWrite: 0, cacheRead: 0, cost: 0, unpriced: 0 }
+  for (const entry of usage) {
+    sum.input += entry.input
+    sum.output += entry.output
+    sum.cacheWrite += entry.cacheWrite5m + entry.cacheWrite1h
+    sum.cacheRead += entry.cacheRead
+    const cost = costOf(entry)
+    if (cost === null) sum.unpriced += 1
+    else sum.cost += cost
+  }
+  return sum
+}
+
+const usageKey = (cacheRead: number, cacheWrite: number, uncached: number) => `${cacheRead}:${cacheWrite}:${uncached}`
+
+export function matchLogged(usage: UsageEntry[], logged: RequestRecord[]): Matched {
+  const index = new Map<string, UsageEntry[]>()
+  for (const entry of usage) {
+    const key = usageKey(entry.cacheRead, entry.cacheWrite5m + entry.cacheWrite1h, entry.input)
+    index.set(key, [...(index.get(key) ?? []), entry])
+  }
+  const matched: Matched = new Map()
+  for (const record of logged) {
+    if (!record.input) continue
+    const at = Date.parse(record.ts)
+    const distance = (entry: UsageEntry) => Math.abs(entry.at - at)
+    const nearest = (index.get(usageKey(record.cacheRead ?? 0, record.cacheWrite ?? 0, record.uncached ?? 0)) ?? []).reduce<UsageEntry | null>((best, entry) => (!best || distance(entry) < distance(best) ? entry : best), null)
+    if (nearest && distance(nearest) <= MATCH_WITHIN) matched.set(record, nearest)
+  }
+  return matched
+}
+
+export function costSaved(record: RequestRecord, entry: UsageEntry): number | null {
+  const saved = savedTokens(record)
+  const rates = ratesOf(entry)
+  if (saved === null || !rates) return null
+  const foldRewrite = record.compacted ? (record.cacheWrite ?? 0) * (rates.write - rates.read) : 0
+  return saved * rates.read - foldRewrite
+}
+
+export function savings(logged: RequestRecord[], matched: Matched) {
+  const sum = { handled: 0, priced: 0, unsized: 0, unmatched: 0, actual: 0, saved: 0 }
+  for (const record of logged) {
+    if (!record.input) continue
+    sum.handled += 1
+    const entry = matched.get(record)
+    if (savedTokens(record) === null) sum.unsized += 1
+    else if (!entry) sum.unmatched += 1
+    const saved = entry ? costSaved(record, entry) : null
+    const actual = entry ? costOf(entry) : null
+    if (saved === null || actual === null) continue
+    sum.priced += 1
+    sum.actual += actual
+    sum.saved += saved
+  }
+  return sum
+}
+
+function leftOut(sum: ReturnType<typeof savings>) {
+  const reasons = [
+    sum.unsized ? `${sum.unsized.toLocaleString()} predate size logging` : "",
+    sum.unmatched ? `${sum.unmatched.toLocaleString()} aren't in session files` : "",
+    sum.handled - sum.priced - sum.unsized - sum.unmatched > 0 ? `${sum.handled - sum.priced - sum.unsized - sum.unmatched} to models without a price` : "",
+  ]
+  const listed = reasons.filter(Boolean)
+  return listed.length > 1 ? `${listed.slice(0, -1).join(", ")} and ${listed.at(-1)}` : listed.join("")
+}
+
+function notSentCell(logged: RequestRecord[]) {
+  const sum = totals(logged)
+  if (sum.requests === 0) return c.dim("–")
+  if (sum.saved <= 0) return c.dim("±0")
+  return `${tokens(sum.saved)} ${c.dim(plural(sum.folds, "fold"))}`
+}
+
+function costSavedCell(logged: RequestRecord[], matched: Matched) {
+  const sum = savings(logged, matched)
+  if (sum.priced === 0) return c.dim("–")
+  if (Math.abs(sum.saved) < 0.005) return c.dim("±0")
+  const share = c.dim(percent(sum.saved / (sum.actual + sum.saved)))
+  return sum.saved > 0 ? `${c.green(c.bold(dollars(sum.saved)))} ${share}` : `${c.yellow(`−${dollars(-sum.saved)}`)} ${share}`
+}
+
+function row(label: string, usage: UsageEntry[], logged: RequestRecord[], matched: Matched, bold = false) {
+  const sum = summarize(usage)
+  const strong = (text: string) => (bold ? c.bold(text) : text)
+  const eunoe = [notSentCell(logged), costSavedCell(logged, matched)]
+  if (sum.requests === 0) return [strong(label), c.dim("–"), "", "", "", "", "", ...eunoe]
+  return [strong(label), strong(sum.requests.toLocaleString()), tokens(sum.input), tokens(sum.output), tokens(sum.cacheWrite), tokens(sum.cacheRead), strong(`${dollars(sum.cost)}${sum.unpriced ? c.dim("*") : ""}`), ...eunoe]
+}
+
+function byModel(usage: UsageEntry[]) {
+  const models = new Map<string, UsageEntry[]>()
+  for (const entry of usage) models.set(entry.model, [...(models.get(entry.model) ?? []), entry])
+  const total = summarize(usage).cost
+  return [...models]
+    .map(([model, entries]) => ({ model, sum: summarize(entries) }))
+    .sort((a, b) => b.sum.cost - a.sum.cost || b.sum.requests - a.sum.requests)
+    .map(({ model, sum }) => [
+      model,
+      sum.requests.toLocaleString(),
+      tokens(sum.input),
+      tokens(sum.output),
+      tokens(sum.cacheWrite),
+      tokens(sum.cacheRead),
+      sum.unpriced ? c.dim("no price") : c.bold(dollars(sum.cost)),
+      c.dim(total > 0 && !sum.unpriced ? percent(sum.cost / total) : ""),
+    ])
+}
+
+const countArg = (args: string[], flag: string, fallback: number) => {
+  const at = args.indexOf(flag)
+  if (at === -1) return fallback
+  const value = Number(args[at + 1])
+  if (!Number.isInteger(value) || value < 1) fail(`${flag} needs a whole number`, `eunoe stats ${flag} 14`)
+  return value
+}
+
+export const stats: Command = {
+  summary: "Token usage and cost by day or week, and what eunoe saved",
+  usage: "eunoe stats [--days <n>] [--weekly] [--weeks <n>]",
+  details: [
+    "Reads the usage the API returned for every request in your Claude Code",
+    "sessions, subagents included, counting each response once. Cost is at",
+    "API list prices. The eunoe columns come from its request log: the input",
+    "tokens it kept out of the requests it handled, and what that saved at",
+    "cache-read prices once the cache writes its folds caused are paid for.",
+  ],
+  options: [
+    ["--days <n>", `Days to show (default ${DEFAULT_DAYS})`],
+    ["--weekly", `Group by week, Monday first (default ${DEFAULT_WEEKS} weeks)`],
+    ["--weeks <n>", "Weeks to show; implies --weekly"],
+  ],
+  run(args) {
+    const weekly = args.includes("--weekly") || args.includes("--weeks")
+    const count = weekly ? countArg(args, "--weeks", DEFAULT_WEEKS) : countArg(args, "--days", DEFAULT_DAYS)
+    const now = Date.now()
+    const list = buckets(now, weekly, count)
+    const since = list[0].start
+    const configDirs = claudeConfigDirs(readConfig())
+    const usage = readUsage(usageFiles(configDirs, since), since)
+    const logged = recentRequests(Number.POSITIVE_INFINITY).filter((record) => Date.parse(record.ts) >= since)
+    for (const entry of usage) place(list, entry.at, (bucket) => bucket.usage.push(entry))
+    const matched = matchLogged(usage, logged)
+    for (const record of logged) place(list, Date.parse(record.ts), (bucket) => bucket.logged.push(record))
+
+    line()
+    line(`  ${c.bold("eunoe stats")}  ${c.dim(`the last ${count} ${weekly ? "weeks" : "days"} of Claude Code, from your session files`)}`)
+    line()
+    table([
+      [weekly ? "Week" : "Day", "Requests", "Input", "Output", "Cache write", "Cache read", "API cost", "Not sent by eunoe", "Cost saved"].map((title) => c.dim(title)),
+      ...list.map((bucket) => row(bucket.label, bucket.usage, bucket.logged, matched)),
+      row("Total", usage, logged, matched, true),
+    ])
+
+    const models = byModel(usage)
+    if (models.length > 0) {
+      line()
+      table([["Model", "Requests", "Input", "Output", "Cache write", "Cache read", "API cost", "Share"].map((title) => c.dim(title)), ...models])
+    }
+
+    const keepDays = cleanupDays(configDirs)
+    const handled = savings(logged, matched)
+    const notes: Array<[label: string, text: string]> = [
+      ["API cost", "At list prices, including cache writes and fast mode."],
+      ["Not sent", "Input eunoe kept out, mostly history Claude Code would have read from cache."],
+      ["Cost saved", "Those tokens at cache-read prices, minus what each fold cost to rewrite."],
+      ...(handled.priced < handled.handled ? [["Not priced", `${(handled.handled - handled.priced).toLocaleString()} of ${handled.handled.toLocaleString()} eunoe requests: ${leftOut(handled)}.`] as [string, string]] : []),
+      ...(summarize(usage).unpriced ? [["* No price", "Some models have no known price, so their tokens count but their cost doesn't."] as [string, string]] : []),
+      ...(since < now - keepDays * DAY ? [["History", `Claude Code deletes sessions after ${keepDays} idle days, so older rows may be incomplete.`] as [string, string]] : []),
+    ]
+    const labelWidth = Math.max(...notes.map(([label]) => label.length)) + 3
+    const width = Math.min(process.stdout.columns || NOTE_WIDTH, NOTE_WIDTH) - 2 - labelWidth
+    for (const [label, text] of notes) {
+      line()
+      for (const [index, part] of wrap(text, width).entries()) line(`  ${c.dim((index === 0 ? label : "").padEnd(labelWidth))}${part}`)
+    }
+    line()
+  },
+}