@chroxify/eunoe 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christo Todorov
+
+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

@@ -1,3 +1,328 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![eunoe, an axolotl holding a glowing pearl](assets/logo.svg)
+
+# eunoe
+
+**Context management for Claude Code that never forgets what matters.**
+
+A local proxy that replaces Claude Code's context compaction. No summary call,
+no two-minute pause, no agent that wakes up having forgotten what you told it.
+
+</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
+
+Fill up a long Claude Code session and it compacts. The agent writes a summary
+of everything so far, throws the conversation away, and continues from the
+summary.
+
+You can feel it the moment it happens.
+
+```
+you    (turn 6)   from now on, deploy to staging yourself, don't ask me
+...
+you    (turn 41)  ok ship it
+agent             Here's the deploy command — want me to run it?
+```
+
+The instruction was five turns old and three paragraphs into a 21,000-character
+summary. So were the exact version ID from the last deploy, the error you spent
+two turns tracking down, and the approach you already ruled out.
+
+Compaction keeps the gist. The gist is not what you need.
+
+It also costs real time. A measured compaction at 922k tokens: **the full
+context read for the summary call, 2½ minutes of generation**, then a brand-new
+prefix written to cache anyway.
+
+## Install
+
+```sh
+bun add -g @chroxify/eunoe   # puts `eunoe` on your PATH
+eunoe install                # background proxy + ANTHROPIC_BASE_URL in ~/.claude/settings.json
+```
+
+Then use Claude Code exactly as before. New sessions go through eunoe; restart
+any that are already running. `eunoe uninstall` reverses it.
+
+Requires [Bun](https://bun.sh). `install` sets up a launchd agent on macOS; on
+other platforms, keep `eunoe serve` running however you like (systemd, a
+terminal) and the rest works the same.
+
+## What it does instead
+
+Nothing, until the context is nearly full. Every request up to that point goes
+upstream byte for byte as Claude Code built it.
+
+At the limit, eunoe rewrites the conversation once. Your first message stays.
+Every turn after it collapses to **what you asked and what the agent answered**.
+The turn in progress is kept whole, down to the last tool call.
+
+```
+WHAT CLAUDE CODE HOLDS (~900k)          WHAT eunoe SENDS
+──────────────────────────────          ────────────────────────────────────────
+turn 1   first message                  turn 1   first message, byte for byte
+         + the agent's work + reply      ┌──────────────────────────────────────┐
+turn 2   prompt, 14 tool calls, reply    │ <context-compacted>                  │
+turn 3   prompt, 6 tool calls, reply     │ Tool calls before this point were    │
+  ⋮                                      │ removed. Earlier turns follow as     │
+turn 38  prompt, 9 tool calls ✋          │ your message + the final reply.      │
+         (you interrupted mid-work)      │ Instructions you gave still apply.   │
+turn 39  prompt, 3 tool calls, reply     │ Exact details → search the           │
+turn 40  prompt, 22 tool calls  ← LIMIT  │ transcript: <how>                    │
+                                         └──────────────────────────────────────┘
+                                        turn 2   your message → final reply
+                                        turn 3   your message → final reply
+                                          ⋮      every turn, ~580 tokens each
+                                        turn 38  your message → [interrupted:
+                                                 last words + its tool calls]
+                                        turn 39  your message → final reply
+                                        turn 40  your message + every tool call
+                                                 and result, exactly as it was
+                                        turn 41+ grows normally until the next cut
+```
+
+**Every turn survives.** A message plus its final reply averages ~580 tokens, so
+a hundred turns is ~60k. There is no reason to throw them away. This is what
+keeps *"what did we do about the Stripe thing"* and *"you told me to deploy it
+yourself"* answerable after a cut.
+
+**The first message is kept verbatim.** Claude Code packs `CLAUDE.md`, your git
+status, your identity and the skill list into it. Dropping it drops your
+instructions. Its hash also travels in a billing header, so eunoe never edits it.
+
+**The turn in progress is untouched.** The agent is mid-work: it needs the actual
+tool calls, their output and its own thinking blocks to carry on. If you
+interrupted it, the interruption marker is right there too, so it resumes from
+where it stopped rather than starting the turn over.
+
+## How it plugs in
+
+```
+ Claude CLI ─┐
+ Desktop app ┼──►  eunoe (127.0.0.1:8788)  ──►  api.anthropic.com
+ Agent SDK ──┘      rewrites /v1/messages
+                    passes everything else straight through
+```
+
+Claude Code honours `ANTHROPIC_BASE_URL` from its `settings.json`, so every
+harness built on it works with no code changes. Auth headers are forwarded
+untouched — your existing login keeps working, subscription or API key.
+
+Claude Code still keeps the whole conversation in memory and on disk at
+`~/.claude/projects/<project>/<session>.jsonl`. eunoe only changes what goes out
+on the wire. That untouched file is the transcript the agent gets pointed at.
+
+## Modes
+
+| mode | before the limit | at the limit |
+|---|---|---|
+| **`compact`** (default) | everything, unchanged | the cut, above |
+| **`trim`** | every finished turn is already just your message + the final reply | rarely reached |
+| **`off`** | passthrough | Claude Code's own compaction |
+
+`trim` is the aggressive option: tool output leaves context the moment a turn
+ends, so a long session never grows past a few tens of thousands of tokens. It
+is noticeably cheaper and, in benchmarks, no less accurate — but the agent has
+to search its transcript more often, so turns start slower.
+
+```sh
+eunoe mode compact   # or trim, or off
+```
+
+Whichever is on owns compaction: eunoe disables Claude Code's auto-compact while
+active and hands it back on `off` or `uninstall`.
+
+## What counts as a final reply
+
+A **turn** starts with a message you sent — text or an image, not a tool result —
+and runs until your next one.
+
+Its **final reply** is the last assistant message of that turn, if the turn ended
+on text with no tool call in it. Only the text is kept; thinking is dropped.
+
+Across 18,966 real turns:
+
+| how the turn ended | share | what eunoe keeps |
+|---|---|---|
+| on a text reply | 73% | that reply (median 1.9k chars; 57% name a file path) |
+| still running | 17% | nothing — it's the live turn, never reduced |
+| interrupted or steered | 10% | last words + the list of tool calls |
+
+Only 1% of finished work turns end in a reply shorter than 120 characters.
+Agents already close turns with something usable; eunoe just stops throwing it
+away.
+
+In `trim` mode the system prompt tells the agent its final reply is the only
+thing it carries forward, and what belongs in it.
+
+## Interruptions and steering
+
+Interrupted turns are where naive summarisation loses the most, so they get
+handled explicitly.
+
+| what happened | how eunoe treats it |
+|---|---|
+| **Esc mid-work**, then a new message | The interrupted turn ends there. Your new message, marker included, opens the next turn. |
+| **Typing while the agent works** | Claude Code sends a mid-conversation `system` message. It stays inside the running turn; in a reduced turn it is merged in right before the final reply. |
+| **An interrupted turn gets reduced** | No final reply exists, so eunoe writes one: `[This turn was interrupted before a final reply.] Last thing you said: … Tool calls (12): Edit src/app.ts; Bash \`bun test\`; …` |
+| **The cut lands on an interrupted turn** | Kept verbatim. The agent sees exactly where it stopped. |
+| **Esc-Esc rewind past the cut** | eunoe notices its cut turn is gone from the history and starts over from whatever Claude Code sends. |
+
+## Searching the transcript
+
+Nothing is lost, so the agent is told where everything is and how to look.
+`search` picks the form:
+
+| `search` | what the agent gets |
+|---|---|
+| `jsonl` | Claude Code's raw session file. Complete, but one long JSON-escaped line per entry. |
+| **`markdown`** (default) | `index.md` — one line per turn, what was asked and how it ended — plus `turn-0001.md`… with the message, every tool call tagged `[tool 3/12]` with its output, and the final reply. |
+| `xml` | The same, as `<turn>` / `<user>` / `<tool n name>` / `<output>` / `<final_reply>`. Easier for the model to parse, slightly harder to grep. |
+| `qmd` | The markdown folder indexed by [qmd](https://github.com/tobi/qmd) for semantic search, for when the agent doesn't know the exact words. |
+
+Rendering is fast and idempotent — a 199-turn session takes 0.13s — so it just
+runs again as the session grows. qmd's embedding pass takes ~83s and runs in the
+background; queries take 3–20s.
+
+## Prompt caching
+
+A compaction scheme that breaks the cache costs more than it saves. Cache writes
+are 1.25× the input price and reads are 0.05×, so rewriting a cached prefix is
+25× more expensive than reading it.
+
+eunoe's output is deterministic. The same history always produces the same bytes,
+a reduced turn always reduces identically, and nothing time-based is ever
+inserted. The prefix changes only at a cut.
+
+```
+turns 1–39   byte-identical to no proxy at all   → cache hits as usual
+turn 40      CUT: one new prefix, written once   → one cache write
+turns 41+    same prefix + new turns appended    → reads hit again
+```
+
+Measured through the proxy, right after a cut: **180k tokens read from cache,
+1.5k written.** Claude Code's own compaction instead reads the entire ~900k
+context into a summary call and *then* writes a new prefix.
+
+## Edge cases
+
+The interesting ones are all about what happens when the cut itself doesn't fit.
+
+| case | behaviour |
+|---|---|
+| **Where a cut lands** | It aims for 30% of the room available — the window minus the fixed system prompt and tool definitions. Land at 70% and you compact again two turns later. |
+| **The cut doesn't fit** | Shrink in order, stopping as soon as it fits. **1.** Drop reduced turns, oldest first. **2.** Only then clear the *oldest* tool outputs of the live turn, half of what remains per step, shortening oversized inputs too. |
+| **Never removed from the live turn** | Your message, the agent's own text, every tool call, and the **latest 5 tool outputs** — what it is actually working from. |
+| **Compaction loops** | Impossible by construction. A cut only ever moves to a newer turn, every shrink step only removes more, and each step is persisted so the bytes stay cache-stable. |
+| **Nothing left to remove** | Sends anyway and logs `stuck`. |
+| **Context window** | Asked once per model via the Models API (`max_input_tokens`) and cached in `~/.eunoe/models.json`. If the lookup fails the window is unknown and **eunoe does not compact** — it won't cut against a limit it can't verify. |
+| **Images and PDFs** | Counted at ~1.6k tokens each, not at their base64 length. |
+| **Subagents, titles, side calls** | Each conversation is its own thread (session id + a fingerprint of its first turn) with its own cut. |
+| **Mid-conversation system messages** | Never dropped. The API only accepts them directly before an assistant message, so they are merged into that position. |
+| **Thinking blocks** | Kept with their signatures in the live turn, where tool use requires them. Dropped from reduced turns. |
+| **eunoe is down** | Every Claude request fails. launchd keeps it alive; `uninstall` leaves it running as a passthrough so sessions already pointed at it survive, and `stop` removes it once they're restarted. |
+
+## Early results
+
+A full, pre-registered benchmark is in progress and will be published with its
+harness, raw data and every per-point result. Until then, here is what an
+earlier internal run showed, with its limits stated.
+
+**Setup.** 45 cut points across 14 projects, from one developer's real Claude
+Code history: real auto-compactions, plus long sessions cut where they crossed
+350k tokens. At each point, every strategy answered the same 10 questions about
+the session — recent details, what was worked on 5–15 turns earlier, standing
+instructions, decisions, and what was in progress — through a real Claude Code
+session, with read-only access to a transcript that stopped at the cut. Answers
+were judged blind.
+
+| strategy | score | context after the cut | vs native, 95% CI |
+|---|---|---|---|
+| Claude Code's compaction | 84% | 82k | — |
+| **eunoe** | **95%** | 183k | **+11.0%** [+8.1, +13.9] |
+| eunoe, `trim` mode | 95% | 179k | +11.6% [+8.8, +14.4] |
+| eunoe, last 5 turns only | 90% | 164k | +6.4% [+2.4, +10.1] |
+| no compaction at all (ceiling) | 97% | 348k | — (7 points) |
+
+eunoe came within two points of never compacting at all, at about half the
+context. Claude Code's compaction lost most on what was worked on mid-session
+(74%), decisions (77%) and what was in progress (77%).
+
+**What this does not show yet.** The run had no budget-matched baseline — a plain
+sliding window given the same token budget — so it can't separate "eunoe keeps
+the right things" from "eunoe keeps more". It also used one judge, and many of its
+questions were easy enough that every strategy passed them. The full benchmark
+adds that baseline, a second judge, harder questions vetted before scoring, and a
+task-continuation test, and reports whatever it finds.
+
+## Usage
+
+```sh
+eunoe serve              # run in the foreground
+eunoe mode compact       # off | trim | compact
+eunoe status             # config, plus cache stats for recent requests
+eunoe install            # background proxy + Claude Code settings
+eunoe uninstall          # new sessions bypass eunoe; proxy stays up as a passthrough
+eunoe stop               # remove the background proxy
+```
+
+`~/.eunoe/config.json`:
+
+```json
+{
+  "mode": "compact",
+  "compactAt": 0.9,
+  "keepTurns": "all",
+  "search": "markdown",
+  "port": 8788,
+  "claudeConfigDirs": []
+}
+```
+
+Tools that run Claude Code with their own config directory (one per account,
+say) need eunoe to know about it, both to find their transcripts and to route
+them through the proxy:
+
+```sh
+eunoe install --config-dir ~/.my-tool/claude-account-1
+```
+
+The directory is remembered in `claudeConfigDirs`.
+
+`compactAt` is a share of the model's real context window. Claude Code compacts
+around 93%, so eunoe goes slightly earlier at 90% to win the race.
+
+Every request is logged to `~/.eunoe/requests.jsonl` with what eunoe did to it
+and the cache read/write that came back.
+
+## What it doesn't do
+
+- **It is a proxy, so it is a single point of failure.** If it isn't running, and
+  `ANTHROPIC_BASE_URL` still points at it, every Claude request fails.
+- **It only understands Claude Code's shape** of conversation — first-message
+  system reminders, mid-conversation system messages, interruption markers. Other
+  Anthropic API clients pass through unchanged but get nothing out of it.
+- **It can't recover what Claude Code already compacted.** Turn it on before a
+  long session, not after.
+- **`trim` mode changes how the agent should write.** It's told to put state in
+  its final reply, and it mostly does — but a sloppy final reply costs more in
+  `trim` than in `compact`.
+
+## Prior art
+
+Claude Code's own compaction is the thing being replaced, and the summary format
+it produces is a reasonable piece of prompt engineering — it just runs after the
+conversation is already gone. [qmd](https://github.com/tobi/qmd) does the local
+semantic search for the `qmd` mode.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@chroxify/eunoe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Context management for Claude Code that never forgets what matters.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chroxify/eunoe.git"
+  },
+  "homepage": "https://github.com/chroxify/eunoe#readme",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "anthropic",
+    "context",
+    "compaction",
+    "proxy"
+  ],
+  "type": "module",
+  "bin": {
+    "eunoe": "src/cli/main.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "scripts": {
+    "start": "bun src/cli/main.ts serve",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli/args.ts

@@ -0,0 +1,17 @@
+import { fail } from "./ui"
+
+export function flagValues(args: string[], flag: string): string[] {
+  const values: string[] = []
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] !== flag) continue
+    const value = args[i + 1]
+    if (!value || value.startsWith("-")) fail(`${flag} needs a value`, `eunoe install ${flag} <dir>`)
+    values.push(value)
+    i += 1
+  }
+  return values
+}
+
+export function wantsHelp(args: string[]) {
+  return args.includes("--help") || args.includes("-h")
+}

package/src/cli/claude-settings.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import type { Settings } from "./types"
+
+export const proxyUrl = (port: number) => `http://127.0.0.1:${port}`
+
+export function withEunoe(settings: Settings, port: number, mode: string): Settings {
+  const next = { ...settings, env: { ...settings.env, ANTHROPIC_BASE_URL: proxyUrl(port) } }
+  return withCompactionOwner(next, mode)
+}
+
+export function withoutEunoe(settings: Settings, port: number): Settings {
+  const next = { ...settings }
+  if (next.env?.ANTHROPIC_BASE_URL === proxyUrl(port)) {
+    const { ANTHROPIC_BASE_URL: _, ...env } = next.env
+    if (Object.keys(env).length > 0) next.env = env
+    else delete next.env
+  }
+  delete next.autoCompactEnabled
+  return next
+}
+
+export function withCompactionOwner(settings: Settings, mode: string): Settings {
+  const next = { ...settings }
+  if (mode === "off") delete next.autoCompactEnabled
+  else next.autoCompactEnabled = false
+  return next
+}
+
+export function editSettings(dirs: string[], edit: (settings: Settings) => Settings): string[] {
+  const touched: string[] = []
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue
+    const file = path.join(dir, "settings.json")
+    const current: Settings = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {}
+    const next = edit(current)
+    if (JSON.stringify(next) === JSON.stringify(current)) continue
+    writeFileSync(file, JSON.stringify(next, null, 2) + "\n")
+    touched.push(file)
+  }
+  return touched
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,9 @@
+import type { Command } from "../types"
+import { install } from "./install"
+import { mode } from "./mode"
+import { serve } from "./serve"
+import { status } from "./status"
+import { stop } from "./stop"
+import { uninstall } from "./uninstall"
+
+export const commands: Record<string, Command> = { install, uninstall, stop, mode, status, serve }

package/src/cli/commands/install.ts

@@ -0,0 +1,44 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { claudeConfigDirs, loadConfig, saveConfig } from "../../config"
+import { paths } from "../../config/constants"
+import { flagValues } from "../args"
+import { editSettings, proxyUrl, withEunoe } from "../claude-settings"
+import { MODE_DESCRIPTIONS } from "../constants"
+import { routedDirs } from "../inspect"
+import * as launchd from "../launchd"
+import type { Command } from "../types"
+import { c, fail, line, listFiles, note, ok, rows, tilde, warn } from "../ui"
+
+export const install: Command = {
+  summary: "Route Claude Code through eunoe and keep it running",
+  usage: "eunoe install [--config-dir <dir>]",
+  details: [
+    "Starts the proxy in the background and points Claude Code at it by setting",
+    "ANTHROPIC_BASE_URL in settings.json. New sessions pick it up; restart running ones.",
+  ],
+  options: [["--config-dir <dir>", "Also manage this Claude config directory (repeatable, remembered)"]],
+  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])] })
+    const config = loadConfig()
+
+    line()
+    if (launchd.supported) {
+      launchd.installAgent([process.execPath, path.join(import.meta.dir, "..", "main.ts"), "serve"], paths.proxyLog)
+      ok(`Proxy running in the background on ${c.cyan(proxyUrl(config.port))}`)
+    } else {
+      warn("No launchd here, so keep the proxy running yourself:")
+      line(`    ${c.cyan("eunoe serve")}`)
+    }
+    const touched = editSettings(claudeConfigDirs(config), (settings) => withEunoe(settings, config.port, config.mode))
+    ok("Claude Code routed through eunoe")
+    listFiles(touched.length ? touched : routedDirs(config).map((dir) => path.join(dir, "settings.json")))
+    line()
+    rows([["Mode", `${c.bold(config.mode)}  ${c.dim(MODE_DESCRIPTIONS[config.mode])}`]])
+    line()
+    note(`New sessions go through eunoe. Restart any that are already running.`)
+    line()
+  },
+}

package/src/cli/commands/mode.ts

@@ -0,0 +1,30 @@
+import { claudeConfigDirs, loadConfig, saveConfig } from "../../config"
+import type { Mode } from "../../config/types"
+import { editSettings, withCompactionOwner } from "../claude-settings"
+import { MODE_DESCRIPTIONS } from "../constants"
+import * as launchd from "../launchd"
+import type { Command } from "../types"
+import { c, fail, line, ok } from "../ui"
+
+export const mode: Command = {
+  summary: "Show or switch how eunoe manages context",
+  usage: "eunoe mode [compact | trim | off]",
+  details: ["Takes effect on the next request; no restart needed."],
+  run(args) {
+    const config = loadConfig()
+    const next = args[0] as Mode | undefined
+    if (!next) {
+      line()
+      for (const [name, description] of Object.entries(MODE_DESCRIPTIONS) as Array<[Mode, string]>) {
+        const current = name === config.mode
+        line(`  ${current ? c.green("●") : c.dim("○")} ${current ? c.bold(name.padEnd(8)) : name.padEnd(8)}  ${c.dim(description)}`)
+      }
+      line()
+      return
+    }
+    if (!(next in MODE_DESCRIPTIONS)) fail(`Unknown mode: ${next}`, "Choose compact, trim or off.")
+    saveConfig({ mode: next })
+    if (launchd.isInstalled()) editSettings(claudeConfigDirs(loadConfig()), (settings) => withCompactionOwner(settings, next))
+    ok(`Mode ${c.bold(next)}  ${c.dim(MODE_DESCRIPTIONS[next])}`)
+  },
+}

package/src/cli/commands/serve.ts

@@ -0,0 +1,19 @@
+import { loadConfig } 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"
+
+export const serve: Command = {
+  summary: "Run the proxy in the foreground",
+  usage: "eunoe serve",
+  details: ["`eunoe install` runs this for you in the background."],
+  async run() {
+    const config = loadConfig()
+    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)
+    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/status.ts

@@ -0,0 +1,48 @@
+import path from "node:path"
+import { loadConfig } from "../../config"
+import { VERSION } from "../../version"
+import { proxyUrl } from "../claude-settings"
+import { MODE_DESCRIPTIONS } from "../constants"
+import { probe, recentRequests, routedDirs } from "../inspect"
+import * as launchd from "../launchd"
+import type { Command } from "../types"
+import { ago, c, line, rows, tilde, tokens, warn } from "../ui"
+
+export const status: Command = {
+  summary: "Show what eunoe is doing",
+  usage: "eunoe status",
+  async run() {
+    const config = loadConfig()
+    const health = await probe(config.port)
+    const routed = routedDirs(config)
+    const recent = recentRequests()
+
+    line()
+    line(`  ${c.bold("eunoe")} ${c.dim(VERSION)}`)
+    line()
+    rows([
+      ["Proxy", health ? `${c.green("●")} running on ${c.cyan(proxyUrl(config.port))}` : `${c.red("○")} not running`],
+      ["Claude Code", routed.length ? `${c.green("●")} routed through eunoe` : `${c.dim("○")} not routed ${c.dim("(eunoe install)")}`],
+      ["Mode", `${c.bold(config.mode)}  ${c.dim(MODE_DESCRIPTIONS[config.mode])}`],
+      ["Search", `${config.search} transcripts`],
+      ["Background", launchd.isInstalled() ? "launchd agent" : c.dim("none")],
+    ])
+    for (const dir of routed) line(`  ${" ".repeat(13)}${c.dim(tilde(path.join(dir, "settings.json")))}`)
+
+    if (recent.length) {
+      const sum = (key: string) => recent.reduce((total, entry) => total + (entry[key] ?? 0), 0)
+      const compactions = recent.filter((entry) => entry.compacted)
+      line()
+      line(`  ${c.dim(`Last ${recent.length} requests`)}`)
+      rows([
+        ["Cache", `${c.bold(tokens(sum("cacheRead")))} read  ·  ${tokens(sum("cacheWrite"))} written  ·  ${tokens(sum("uncached"))} uncached`],
+        ["Cuts", compactions.length ? `${compactions.length}, last ${ago(compactions.at(-1)!.ts)}` : c.dim("none yet")],
+      ])
+    }
+    if (health && health.mode !== config.mode) {
+      line()
+      warn(`The running proxy reports mode ${health.mode}; it switches on its next request.`)
+    }
+    line()
+  },
+}

package/src/cli/commands/stop.ts

@@ -0,0 +1,16 @@
+import { loadConfig } from "../../config"
+import { routedDirs } from "../inspect"
+import * as launchd from "../launchd"
+import type { Command } from "../types"
+import { fail, note, ok } from "../ui"
+
+export const stop: Command = {
+  summary: "Stop the background proxy",
+  usage: "eunoe stop",
+  details: ["Sessions still pointed at the proxy will fail until restarted, so run `eunoe uninstall` first."],
+  run() {
+    if (routedDirs(loadConfig()).length) fail("Claude Code is still routed through eunoe", "Run `eunoe uninstall` first, then restart your sessions.")
+    if (launchd.removeAgent()) ok("Background proxy stopped")
+    else note("The proxy isn't running as a background service.")
+  },
+}

package/src/cli/commands/uninstall.ts

@@ -0,0 +1,25 @@
+import { claudeConfigDirs, loadConfig, saveConfig } from "../../config"
+import { editSettings, withoutEunoe } from "../claude-settings"
+import type { Command } from "../types"
+import { c, line, listFiles, note, ok } from "../ui"
+
+export const uninstall: Command = {
+  summary: "Send new sessions straight to the API again",
+  usage: "eunoe uninstall",
+  details: [
+    "Removes eunoe from Claude Code's settings and hands compaction back to it.",
+    "The proxy keeps running as a passthrough, so sessions already pointed at it",
+    "keep working. Run `eunoe stop` once they have been restarted.",
+  ],
+  run() {
+    const config = loadConfig()
+    const touched = editSettings(claudeConfigDirs(config), (settings) => withoutEunoe(settings, config.port))
+    saveConfig({ mode: "off" })
+    line()
+    ok("Claude Code no longer routed through eunoe")
+    listFiles(touched)
+    note("The proxy stays up as a passthrough for sessions still using it.")
+    line(`  ${c.dim("Once they're restarted:")} ${c.cyan("eunoe stop")}`)
+    line()
+  },
+}