@chroxify/eunoe 0.0.0-stage → 0.1.0

package/src/cli/constants.ts

@@ -0,0 +1,29 @@
+import { homedir } from "node:os"
+import path from "node:path"
+import type { Mode } from "../config/types"
+import type { OptionRow } from "./types"
+
+export const TAGLINE = "Context management for Claude Code that never forgets what matters."
+
+export const MODE_DESCRIPTIONS: Record<Mode, string> = {
+  compact: "Full context until the window is nearly full, then eunoe's cut",
+  trim: "Every finished turn kept as your message and the final reply",
+  off: "Passthrough. Claude Code compacts on its own",
+}
+
+export const GLOBAL_OPTIONS: OptionRow[] = [
+  ["-h, --help", "Show help for a command"],
+  ["-v, --version", "Show the version"],
+]
+
+export const LAUNCHD_LABEL = "com.chroxify.eunoe"
+export const LAUNCH_AGENT_PLIST = path.join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`)
+
+export const PROBE_TIMEOUT_MS = 800
+export const RECENT_REQUESTS = 200
+export const TYPO_DISTANCE = 2
+
+export const TRANSPARENT_PIXEL = "."
+export const HALF_BLOCKS = " ▀▄█"
+export const OCTANTS = [..." 𜺨𜺫🮂𜴀▘𜴁𜴂𜴃𜴄▝𜴅𜴆𜴇𜴈▀𜴉𜴊𜴋𜴌🯦𜴍𜴎𜴏𜴐𜴑𜴒𜴓𜴔𜴕𜴖𜴗𜴘𜴙𜴚𜴛𜴜𜴝𜴞𜴟🯧𜴠𜴡𜴢𜴣𜴤𜴥𜴦𜴧𜴨𜴩𜴪𜴫𜴬𜴭𜴮𜴯𜴰𜴱𜴲𜴳𜴴𜴵🮅𜺣𜴶𜴷𜴸𜴹𜴺𜴻𜴼𜴽𜴾𜴿𜵀𜵁𜵂𜵃𜵄▖𜵅𜵆𜵇𜵈▌𜵉𜵊𜵋𜵌▞𜵍𜵎𜵏𜵐▛𜵑𜵒𜵓𜵔𜵕𜵖𜵗𜵘𜵙𜵚𜵛𜵜𜵝𜵞𜵟𜵠𜵡𜵢𜵣𜵤𜵥𜵦𜵧𜵨𜵩𜵪𜵫𜵬𜵭𜵮𜵯𜵰𜺠𜵱𜵲𜵳𜵴𜵵𜵶𜵷𜵸𜵹𜵺𜵻𜵼𜵽𜵾𜵿𜶀𜶁𜶂𜶃𜶄𜶅𜶆𜶇𜶈𜶉𜶊𜶋𜶌𜶍𜶎𜶏▗𜶐𜶑𜶒𜶓▚𜶔𜶕𜶖𜶗▐𜶘𜶙𜶚𜶛▜𜶜𜶝𜶞𜶟𜶠𜶡𜶢𜶣𜶤𜶥𜶦𜶧𜶨𜶩𜶪𜶫▂𜶬𜶭𜶮𜶯𜶰𜶱𜶲𜶳𜶴𜶵𜶶𜶷𜶸𜶹𜶺𜶻𜶼𜶽𜶾𜶿𜷀𜷁𜷂𜷃𜷄𜷅𜷆𜷇𜷈𜷉𜷊𜷋𜷌𜷍𜷎𜷏𜷐𜷑𜷒𜷓𜷔𜷕𜷖𜷗𜷘𜷙𜷚▄𜷛𜷜𜷝𜷞▙𜷟𜷠𜷡𜷢▟𜷣▆𜷤𜷥█"]
+export const OCTANT_TERMINALS = ["ghostty"]

package/src/cli/help.ts

@@ -0,0 +1,42 @@
+import { VERSION } from "../version"
+import { GLOBAL_OPTIONS, TAGLINE } from "./constants"
+import { withLogo } from "./logo"
+import type { Command } from "./types"
+import { c, line } from "./ui"
+
+export function printHelp(commands: Record<string, Command>) {
+  const width = Math.max(...Object.keys(commands).map((name) => name.length), ...GLOBAL_OPTIONS.map(([flag]) => flag.length))
+  line()
+  for (const row of withLogo([`${c.bold("eunoe")} ${c.dim(VERSION)}`, c.italic(TAGLINE)])) line(row)
+  line()
+  line(`  ${c.dim("Usage")}`)
+  line(`    eunoe ${c.cyan("<command>")} ${c.dim("[options]")}`)
+  line()
+  line(`  ${c.dim("Commands")}`)
+  for (const [name, command] of Object.entries(commands)) line(`    ${c.cyan(name.padEnd(width))}   ${command.summary}`)
+  line()
+  line(`  ${c.dim("Options")}`)
+  for (const [flag, description] of GLOBAL_OPTIONS) line(`    ${flag.padEnd(width)}   ${description}`)
+  line()
+  line(`  ${c.dim("Run")} eunoe ${c.cyan("<command>")} --help ${c.dim("for details.")}`)
+  line()
+}
+
+export function printCommandHelp(name: string, command: Command) {
+  line()
+  line(`  ${c.bold(`eunoe ${name}`)}  ${c.dim(command.summary)}`)
+  line()
+  line(`  ${c.dim("Usage")}`)
+  line(`    ${command.usage}`)
+  if (command.details) {
+    line()
+    for (const detail of command.details) line(`  ${detail}`)
+  }
+  if (command.options) {
+    line()
+    line(`  ${c.dim("Options")}`)
+    const width = Math.max(...command.options.map(([flag]) => flag.length))
+    for (const [flag, description] of command.options) line(`    ${c.cyan(flag.padEnd(width))}   ${description}`)
+  }
+  line()
+}

package/src/cli/inspect.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+import { claudeConfigDirs } from "../config"
+import { paths } from "../config/constants"
+import type { Config } from "../config/types"
+import { HEALTH_PATH } from "../proxy/constants"
+import type { Health } from "../proxy/types"
+import { proxyUrl } from "./claude-settings"
+import { PROBE_TIMEOUT_MS, RECENT_REQUESTS } from "./constants"
+import type { RequestRecord } from "./types"
+
+export async function probe(port: number): Promise<Health | null> {
+  try {
+    const response = await fetch(`${proxyUrl(port)}${HEALTH_PATH}`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
+    return response.ok ? await response.json() as Health : null
+  } catch {
+    return null
+  }
+}
+
+export function routedDirs(config: Config) {
+  return claudeConfigDirs(config).filter((dir) => {
+    try {
+      const settings = JSON.parse(readFileSync(path.join(dir, "settings.json"), "utf8"))
+      return settings.env?.ANTHROPIC_BASE_URL === proxyUrl(config.port)
+    } catch {
+      return false
+    }
+  })
+}
+
+export function recentRequests(limit = RECENT_REQUESTS): RequestRecord[] {
+  if (!existsSync(paths.requests)) return []
+  return readFileSync(paths.requests, "utf8").trim().split("\n").slice(-limit).flatMap((entry) => {
+    try {
+      return [JSON.parse(entry)]
+    } catch {
+      return []
+    }
+  })
+}

package/src/cli/launchd.ts

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { LAUNCH_AGENT_PLIST as PLIST, LAUNCHD_LABEL } from "./constants"
+
+export const supported = process.platform === "darwin"
+
+export function isInstalled() {
+  return existsSync(PLIST)
+}
+
+export function installAgent(program: string[], logFile: string) {
+  mkdirSync(path.dirname(PLIST), { recursive: true })
+  const args = program.map((arg) => `<string>${arg}</string>`).join("")
+  writeFileSync(PLIST, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key><array>${args}</array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${logFile}</string>
+  <key>StandardErrorPath</key><string>${logFile}</string>
+</dict></plist>
+`)
+  Bun.spawnSync(["launchctl", "unload", PLIST])
+  Bun.spawnSync(["launchctl", "load", PLIST])
+}
+
+export function removeAgent() {
+  if (!existsSync(PLIST)) return false
+  Bun.spawnSync(["launchctl", "unload", PLIST])
+  unlinkSync(PLIST)
+  return true
+}

package/src/cli/logo/index.ts

@@ -0,0 +1,89 @@
+import { HALF_BLOCKS, OCTANT_TERMINALS, OCTANTS, TRANSPARENT_PIXEL } from "../constants"
+import { trueColor, useColor } from "../ui"
+import { LOGO_KEYS, LOGO_PALETTE, LOGO_PIXELS } from "./pixels"
+
+type Rgb = [number, number, number]
+type Pixel = Rgb | null
+
+const rgb = (hex: string): Rgb => [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16)) as Rgb
+
+const toCube = (value: number) => (value < 48 ? 0 : value < 115 ? 1 : Math.min(5, Math.round((value - 35) / 40)))
+
+const MISMATCH = 3 * 255 ** 2
+
+function sgr(color: Rgb, layer: "fg" | "bg") {
+  const base = layer === "fg" ? 38 : 48
+  if (trueColor) return `${base};2;${color.join(";")}`
+  const [r, g, b] = color.map(toCube)
+  return `${base};5;${16 + 36 * r + 6 * g + b}`
+}
+
+function pixel(key: string | undefined): Pixel {
+  if (!key || key === TRANSPARENT_PIXEL) return null
+  return rgb(LOGO_PALETTE[LOGO_KEYS.indexOf(key)])
+}
+
+function distance(a: Pixel, b: Pixel) {
+  if (!a || !b) return a === b ? 0 : MISMATCH
+  return (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2
+}
+
+function split(block: Pixel[]): [Pixel, Pixel] {
+  const colors = block.filter((color, i) => block.findIndex((other) => distance(other, color) === 0) === i)
+  if (colors.length <= 2) return [colors[0] ?? null, colors[1] ?? null]
+  let best: [Pixel, Pixel] = [colors[0], colors[1]]
+  let bestError = Number.POSITIVE_INFINITY
+  for (let i = 0; i < colors.length; i += 1) {
+    for (let j = i + 1; j < colors.length; j += 1) {
+      const error = block.reduce((total, color) => total + Math.min(distance(color, colors[i]), distance(color, colors[j])), 0)
+      if (error < bestError) [best, bestError] = [[colors[i], colors[j]], error]
+    }
+  }
+  return best
+}
+
+function dominant(block: Pixel[]): Pixel {
+  const counts = block.map((color) => block.filter((other) => distance(other, color) === 0).length)
+  return block[counts.indexOf(Math.max(...counts))]
+}
+
+function cell(block: Pixel[], glyphs: string[]) {
+  let [fg, bg] = split(block)
+  if (!fg) [fg, bg] = [bg, fg]
+  if (!fg) return " "
+  const mask = block.reduce((bits, color, i) => (distance(color, fg) <= distance(color, bg) ? bits | (1 << i) : bits), 0)
+  const codes = bg ? `${sgr(fg, "fg")};${sgr(bg, "bg")}` : sgr(fg, "fg")
+  return `\x1b[${codes}m${glyphs[mask]}\x1b[0m`
+}
+
+function supportsOctants() {
+  const terminal = `${process.env.TERM_PROGRAM ?? ""} ${process.env.TERM ?? ""}`.toLowerCase()
+  return OCTANT_TERMINALS.some((name) => terminal.includes(name))
+}
+
+function region(x: number, y: number, width: number, height: number): Pixel[] {
+  const block: Pixel[] = []
+  for (let dy = 0; dy < height; dy += 1) for (let dx = 0; dx < width; dx += 1) block.push(pixel(LOGO_PIXELS[y + dy]?.[x + dx]))
+  return block
+}
+
+export function logoLines(): string[] {
+  if (!useColor) return []
+  const octants = supportsOctants()
+  const lines: string[] = []
+  for (let y = 0; y < LOGO_PIXELS.length; y += 4) {
+    let row = ""
+    for (let x = 0; x < LOGO_PIXELS[0].length; x += 2) {
+      row += octants
+        ? cell(region(x, y, 2, 4), OCTANTS)
+        : cell([dominant(region(x, y, 2, 2)), dominant(region(x, y + 2, 2, 2))], [...HALF_BLOCKS])
+    }
+    lines.push(row)
+  }
+  return lines
+}
+
+export function withLogo(text: string[]): string[] {
+  const logo = logoLines()
+  return [...logo.map((row) => `  ${row}`), ...(logo.length ? [""] : []), ...text.map((entry) => `  ${entry}`)]
+}

package/src/cli/logo/pixels.ts

@@ -0,0 +1,34 @@
+export const LOGO_KEYS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456"
+
+export const LOGO_PALETTE = ["#fefefd", "#fdfcf1", "#fef7db", "#fef7da", "#fdf7dc", "#fef7d9", "#fdf6d9", "#fef6d6", "#fdf6d7", "#fdf4d5", "#fdf6cf", "#fef4ae", "#fde9a5", "#feec97", "#fde186", "#fddb6b", "#fdd763", "#fdd661", "#fdd55d", "#fcd259", "#fdcd49", "#fdc524", "#f6f5de", "#f5e6b1", "#d7ecc9", "#e2d596", "#e5b93b", "#7ce5d0", "#68dbd4", "#74cdd0", "#52d1cc", "#33c4c9", "#2bc0c7", "#2abcc5", "#29bbc4", "#27bcc5", "#20bccc", "#27bac3", "#24b7bc", "#12b3d0", "#0baccd", "#0fa7b4", "#7f7870", "#0678a5", "#038abb", "#04527e", "#018cd0", "#016b95", "#014b85", "#01417b", "#023d73", "#013a71", "#033b6a", "#023768", "#013367", "#092945", "#002d56", "#071a2c", "#041223"]
+
+export const LOGO_PIXELS = [
+  "..............W4...........a",
+  ".............Xutt..........U",
+  ".........tt...kuut.......uu.",
+  "........tkr...1Yxt4tT....u..",
+  "...XXW..soq...X2Xtst0.......",
+  "..TqssW.xr6...0CJRXs4.......",
+  "..oCCCsW.srrr012S4R1s.1.....",
+  "..kCCPrsV.ttslRSRJCFEB0m....",
+  "...pCPPrqW4W43nJJJJJHCG0....",
+  "...koCPR0sppHEtEILIHHHGhTrq.",
+  "....oCOSSZSFFEFFIIIHHHhhkEp.",
+  "XXX..nyEVPByEEEGGIIIHHLbwLo.",
+  "YrrYYY04WMGFEEggdhIIHHH63Vx.",
+  ".rqnnnxKKLwFifg66hhHHGJ6ujTe",
+  ".ZrpoCNSLKkGfh3355fffB4ejmj.",
+  "..1qpCY1PMLFfg3553hhhh.ihgRw",
+  ".....ZZ2POJGdd653AdcgQQhfe..",
+  ".....ZZPZPJdxjj6vcddcAAffT..",
+  ".CC.YpCE2VhGkjmmfdcddghdT..A",
+  "....Xpp1ZVRVxhhfgddfffTT..Ab",
+  ".....1Z2pC02VxxkxxgnmzA....6",
+  ".......qrp2ewVPMxxmmavvv6..A",
+  "..UU...YXY..PPFkEkkvvaaavA..",
+  ".UUCU......XXPMCkkvalanxavvN",
+  ".UCyUNN..1Yu4PMP055nlalxBavN",
+  "..UU.NN.1uD2PwJ0MP33nlmyBuav",
+  "QyDy3y..uo2RRwFPPPP6nnBBavaa",
+  "DQQQDyy.tB2RVPPPSR4poBBaaB6N",
+]

package/src/cli/main.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+import { VERSION } from "../version"
+import { wantsHelp } from "./args"
+import { commands } from "./commands"
+import { printCommandHelp, printHelp } from "./help"
+import { closest, fail, line } from "./ui"
+
+const [name, ...args] = process.argv.slice(2)
+
+if (!name || name === "help" || name === "-h" || name === "--help") {
+  const topic = name === "help" ? args[0] : undefined
+  if (topic && commands[topic]) printCommandHelp(topic, commands[topic])
+  else printHelp(commands)
+} else if (name === "-v" || name === "--version" || name === "version") {
+  line(VERSION)
+} else if (!commands[name]) {
+  const suggestion = closest(name, Object.keys(commands))
+  fail(`Unknown command: ${name}`, suggestion ? `Did you mean \`eunoe ${suggestion}\`?` : "Run `eunoe --help` to see the commands.")
+} else if (wantsHelp(args)) {
+  printCommandHelp(name, commands[name])
+} else {
+  await commands[name].run(args)
+}

package/src/cli/types.ts

@@ -0,0 +1,13 @@
+export type Settings = Record<string, any>
+
+export type OptionRow = [flag: string, description: string]
+
+export interface Command {
+  summary: string
+  usage: string
+  details?: string[]
+  options?: OptionRow[]
+  run: (args: string[]) => void | Promise<void>
+}
+
+export type RequestRecord = Record<string, any>

package/src/cli/ui.ts

@@ -0,0 +1,91 @@
+import { homedir } from "node:os"
+import { TYPO_DISTANCE } from "./constants"
+
+const colorFor = (stream: NodeJS.WriteStream) => Boolean(stream.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb"
+export const useColor = colorFor(process.stdout)
+export const trueColor = /^(truecolor|24bit)$/i.test(process.env.COLORTERM ?? "")
+const useColorErr = colorFor(process.stderr)
+
+const paint = (open: number, close: number, enabled = useColor) => (text: string) => (enabled ? `\x1b[${open}m${text}\x1b[${close}m` : text)
+
+export const c = {
+  bold: paint(1, 22),
+  dim: paint(2, 22),
+  italic: paint(3, 23),
+  cyan: paint(36, 39),
+  green: paint(32, 39),
+  yellow: paint(33, 39),
+  red: paint(31, 39),
+  magenta: paint(35, 39),
+}
+
+const errRed = paint(31, 39, useColorErr)
+const errDim = paint(2, 22, useColorErr)
+
+export function line(text = "") {
+  console.log(text)
+}
+
+export function ok(text: string) {
+  console.log(`${c.green("✓")} ${text}`)
+}
+
+export function note(text: string) {
+  console.log(`${c.dim("·")} ${text}`)
+}
+
+export function warn(text: string) {
+  console.log(`${c.yellow("!")} ${text}`)
+}
+
+export function fail(text: string, hint?: string): never {
+  console.error(`${errRed("✗")} ${text}`)
+  if (hint) console.error(`  ${errDim(hint)}`)
+  process.exit(1)
+}
+
+export function listFiles(files: string[]) {
+  for (const file of files) line(`    ${c.dim(tilde(file))}`)
+}
+
+export function rows(entries: Array<[string, string]>, indent = 2) {
+  const width = Math.max(...entries.map(([label]) => label.length))
+  for (const [label, value] of entries) console.log(`${" ".repeat(indent)}${c.dim(label.padEnd(width))}  ${value}`)
+}
+
+export function tilde(file: string) {
+  const home = homedir()
+  return file.startsWith(home) ? `~${file.slice(home.length)}` : file
+}
+
+export function tokens(count: number) {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(count >= 10_000_000 ? 0 : 1)}M`
+  if (count >= 1_000) return `${(count / 1_000).toFixed(count >= 10_000 ? 0 : 1)}k`
+  return String(count)
+}
+
+export function ago(iso: string) {
+  const seconds = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000))
+  if (seconds < 60) return "just now"
+  if (seconds < 3_600) return `${Math.round(seconds / 60)}m ago`
+  if (seconds < 86_400) return `${Math.round(seconds / 3_600)}h ago`
+  return `${Math.round(seconds / 86_400)}d ago`
+}
+
+export function closest(input: string, options: string[]) {
+  const distance = (a: string, b: string) => {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i += 1) {
+      let previous = row[0]
+      row[0] = i
+      for (let j = 1; j <= b.length; j += 1) {
+        const current = row[j]
+        row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1))
+        previous = current
+      }
+    }
+    return row[b.length]
+  }
+  const [best] = options.map((option) => [option, distance(input, option)] as const).sort((x, y) => x[1] - y[1])
+  return best && best[1] <= TYPO_DISTANCE ? best[0] : null
+}

package/src/config/constants.ts

@@ -0,0 +1,27 @@
+import { homedir } from "node:os"
+import path from "node:path"
+import type { Config, Mode, SearchMode } from "./types"
+
+export const EUNOE_DIR = process.env.EUNOE_DIR ?? path.join(homedir(), ".eunoe")
+
+export const paths = {
+  config: path.join(EUNOE_DIR, "config.json"),
+  requests: path.join(EUNOE_DIR, "requests.jsonl"),
+  threads: path.join(EUNOE_DIR, "threads"),
+  transcripts: path.join(EUNOE_DIR, "transcripts"),
+  models: path.join(EUNOE_DIR, "models.json"),
+  proxyLog: path.join(EUNOE_DIR, "proxy.log"),
+}
+
+export const DEFAULTS: Config = {
+  mode: "compact",
+  port: 8788,
+  compactAt: 0.9,
+  keepTurns: "all",
+  search: "markdown",
+  upstream: "https://api.anthropic.com",
+  claudeConfigDirs: [],
+}
+
+export const MODES: Mode[] = ["off", "trim", "compact"]
+export const SEARCH_MODES: SearchMode[] = ["jsonl", "markdown", "xml", "qmd"]

package/src/config/index.ts

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+import { DEFAULTS, EUNOE_DIR, MODES, paths, SEARCH_MODES } from "./constants"
+import type { Config } from "./types"
+
+export function normalizeConfig(raw: Record<string, any>): Config {
+  const config: Config = { ...DEFAULTS, ...raw }
+  if (!MODES.includes(config.mode)) config.mode = DEFAULTS.mode
+  if (!SEARCH_MODES.includes(config.search)) config.search = DEFAULTS.search
+  if (typeof config.compactAt !== "number" || config.compactAt <= 0 || config.compactAt > 1) config.compactAt = DEFAULTS.compactAt
+  if (config.keepTurns !== "all" && (typeof config.keepTurns !== "number" || config.keepTurns < 0)) config.keepTurns = DEFAULTS.keepTurns
+  if (!Number.isInteger(config.port)) config.port = DEFAULTS.port
+  if (!Array.isArray(config.claudeConfigDirs)) config.claudeConfigDirs = []
+  return config
+}
+
+let cached: { mtimeMs: number; config: Config } | null = null
+
+export function loadConfig(): Config {
+  let mtimeMs: number
+  try {
+    mtimeMs = statSync(paths.config).mtimeMs
+  } catch {
+    return DEFAULTS
+  }
+  if (cached?.mtimeMs === mtimeMs) return cached.config
+  let config = DEFAULTS
+  try {
+    config = normalizeConfig(JSON.parse(readFileSync(paths.config, "utf8")))
+  } catch (error) {
+    console.error(`[eunoe] ${paths.config} is not valid JSON; using defaults`, error)
+  }
+  cached = { mtimeMs, config }
+  return config
+}
+
+export function saveConfig(patch: Partial<Config>) {
+  mkdirSync(EUNOE_DIR, { recursive: true })
+  const current = existsSync(paths.config) ? JSON.parse(readFileSync(paths.config, "utf8")) : {}
+  writeFileSync(paths.config, JSON.stringify({ ...current, ...patch }, null, 2) + "\n")
+}
+
+export function claudeConfigDirs(config: Config): string[] {
+  const dirs = new Set([path.join(homedir(), ".claude")])
+  if (process.env.CLAUDE_CONFIG_DIR) dirs.add(process.env.CLAUDE_CONFIG_DIR)
+  for (const dir of config.claudeConfigDirs) dirs.add(dir.replace(/^~(?=$|\/)/, homedir()))
+  return [...dirs]
+}

package/src/config/types.ts

@@ -0,0 +1,21 @@
+export type Mode = "off" | "trim" | "compact"
+export type SearchMode = "jsonl" | "markdown" | "xml" | "qmd"
+
+export interface EvalConfig {
+  strategy?: "tail" | "guide"
+  tailTurns?: number
+  forceCut?: boolean
+  trustHeaders?: boolean
+}
+
+export interface Config {
+  mode: Mode
+  port: number
+  compactAt: number
+  keepTurns: number | "all"
+  search: SearchMode
+  upstream: string
+  claudeConfigDirs: string[]
+  window?: number
+  eval?: EvalConfig
+}

package/src/context/constants.ts

@@ -0,0 +1,7 @@
+export const SUMMARY_COMMAND_CHARS = 100
+export const SUMMARY_ARGUMENT_CHARS = 60
+export const SUMMARY_LAST_WORDS_CHARS = 600
+export const SUMMARY_CALLS_SHOWN = 20
+
+export const CLEARED_INPUT_THRESHOLD = 2_000
+export const CLEARED_INPUT_KEPT = 500

package/src/context/content.ts

@@ -0,0 +1,24 @@
+import type { Block, Message } from "./types"
+
+export function contentBlocks(content: unknown): Block[] {
+  return typeof content === "string" ? [{ type: "text", text: content }] : Array.isArray(content) ? content : []
+}
+
+export function blocks(message: Message): Block[] {
+  return contentBlocks(message.content)
+}
+
+export function withoutCacheControl(block: Block): Block {
+  if (!("cache_control" in block)) return block
+  const { cache_control: _, ...rest } = block
+  return rest
+}
+
+export function clean(message: Message): Message {
+  return { role: message.role, content: blocks(message).map(withoutCacheControl) }
+}
+
+export function clip(value: unknown, max: number): string {
+  const text = String(value).replace(/\s+/g, " ").trim()
+  return text.length > max ? `${text.slice(0, max)}…` : text
+}

package/src/context/prompts.ts

@@ -0,0 +1,66 @@
+import type { NoticeCounts } from "./types"
+
+export function compactionNotice(args: NoticeCounts) {
+  return [
+    "<context-compacted>",
+    "Your context was compacted here, so tool calls and their output from before this point were removed.",
+    args.omitted > 0
+      ? `${args.omitted} of the oldest turns didn't fit and were removed entirely. The ${args.kept} turn${args.kept === 1 ? "" : "s"} after them are shown as the user's message and your final reply.`
+      : args.kept > 0
+        ? "Every earlier turn is shown below as the user's message and your final reply."
+        : "",
+    "The turn that was in progress when the context filled up follows in full. Continue from it.",
+    "Instructions and preferences the user gave in earlier turns still apply: how they want things done, and what to do or not do on your own. Look back over their messages before you act.",
+    "For an exact detail from before this point (an ID, a path, a command, an error, a value, what a tool printed), look it up instead of going from memory. A lookup is cheap; a wrong detail is not. Never say you don't know about something earlier in this session without searching for it first, and if what you remember contradicts what the user says, search before telling them they are wrong.",
+    args.guide ?? "",
+    "</context-compacted>",
+  ].filter(Boolean).join("\n\n")
+}
+
+export function truncationNotice(args: NoticeCounts) {
+  return [
+    "<context-truncated>",
+    `${args.omitted} earlier turn${args.omitted === 1 ? " was" : "s were"} dropped to fit the context window. What follows is the most recent ${args.kept} turn${args.kept === 1 ? "" : "s"}, unchanged.`,
+    "Instructions and preferences the user gave in earlier turns still apply.",
+    args.guide ?? "",
+    "</context-truncated>",
+  ].filter(Boolean).join("\n\n")
+}
+
+export function trimInstructions(guide: string): string {
+  return [
+    "# Context between turns",
+    "",
+    "This session trims its context between turns: of every earlier turn you keep only the user's message (with anything that arrived with it) and your final message. Everything in between is gone when the next turn starts: tool calls and their results, files you read, command output, your thinking, and anything you wrote along the way. Within a turn, nothing is trimmed.",
+    "",
+    "So your final message is the only memory you carry forward. End each turn with a final message that lets you pick the work back up cold:",
+    "- What changed: files with their paths, branches, commits, PRs, anything created, moved or deleted.",
+    "- What you found: facts you would otherwise have to dig up again. Where code lives, how something works, the cause of a bug, exact error text, IDs, URLs, the numbers that matter.",
+    "- Decisions and their reasons, including approaches you tried and ruled out.",
+    "- Where things stand: what is done, what is not, what you verified and how, and what is waiting on the user.",
+    "",
+    "It is still your reply to the user, so write it for them, but leave out nothing you will need. State things outright instead of pointing back at tool output: \"as shown above\" means nothing next turn. One exact line (a path, a command, a value) beats a paragraph describing it. A turn that ends on a question still needs the state written down. A trivial turn (a quick answer, small talk) needs no state.",
+    "",
+    "Instructions and preferences the user gave in earlier turns still apply: how they want things done, and what to do or not do on your own.",
+    "",
+    "Nothing is lost. What you see of earlier turns is only their outcome. For an exact detail from an earlier turn (an ID, a path, a command you ran, what it printed, a file's earlier content, an error), look it up in the full transcript instead of going from memory or redoing the work. A lookup is cheap; a wrong detail is not.",
+    "",
+    guide,
+    "",
+    "What you read from it stays in context for this turn only. If you will need it again later, put it in your final message.",
+  ].join("\n")
+}
+
+export function searchOnlyInstructions(guide: string): string {
+  return [
+    "# The full transcript",
+    "",
+    "Earlier parts of this session may be summarised or missing from your context. The complete record is on disk, and for any exact detail from earlier (an ID, a path, a command you ran, what it printed, an error, a value) you should look it up there rather than answer from memory. A lookup is cheap; a wrong detail is not. Never say you don't know about something earlier in this session without searching for it first.",
+    "",
+    guide,
+  ].join("\n")
+}
+
+export const CLEARED_OUTPUT = "[Output cleared to keep the context within its limit. It is in the full transcript: search there for this call.]"
+
+export const TRANSCRIPT_FALLBACK = "The full transcript is your Claude Code session file under ~/.claude/projects."