claude-discover 1.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Georgi Dichev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+> Session browser + Token costs + API traffic
+# <img src="src/renderer/assets/claude-icon.svg" width="20"> Claude Discover
+
+Ever wondered what Claude Code is **actually** doing all day?
+
+<img width="1660" height="1256" alt="claude-discover-dimmed-screenshot" src="https://github.com/user-attachments/assets/708d05c7-8769-47d8-b5bd-14337d1d6037" />
+<br><br>
+
+**Claude Discover** is a desktop tool that shows you what **Claude Code** is actually doing. It collects all your sessions (from the CLI, Desktop, or SDK) and puts them on one timeline, where you can read every conversation, peek at the system prompts, memories, and tools, inspect the raw API traffic behind it all, and see exactly where your tokens - and your money - went. (Spoiler: mostly on re-sending tool definitions.)
+
+No configuration, no API keys, and **everything stays on your machine**.
+
+## Getting started
+
+The tool works on Windows, macOS, and Linux. If you have Node.js 22+, just try it:
+```
+npx claude-discover@latest
+```
+
+Like it and want to keep it around? Install it:
+```
+npm install -g claude-discover
+claude-discover
+```
+
+## Features
+
+- **Timeline**\
+  Your Claude sessions laid out on a daily, weekly, or monthly timeline. One glance tells you where your tokens went; the second finds the session that quietly spawned 100+ agents.
+
+- **Sessions list**\
+  Filter and sort every session in the selected period. Warning badges flag the expensive habits: oversized context, extended 1h cache, fast mode, marathon sessions - and more to come.
+
+- **Session preview**
+  - **Conversation view**\
+    The full transcript rendered like a chat: your prompts, Claude's replies, and every tool call expanded. Everything the terminal scrolled past, now readable at human pace.
+
+  - **Raw logs**\
+    The same session exactly as Claude Code stores it on disk, one JSON line at a time. For when you don't want the story, you want the evidence.
+
+  - **API request inspector**\
+    A Postman-like view of every API request and response, captured by an optional local proxy (one click on, one click off). This is where the secrets live: the system prompt, your CLAUDE.md and memory files, tool definitions, injected reminders - all the stuff session logs politely never record.
+
+- **Session summary**\
+  Token usage and cost for every session, and totals for the whole period. Computed from your local transcripts with current model rates - accurate to the cent.
+
+- **AI session analysis**\
+  Ask Claude to review a session and tell you where the tokens leaked - with concrete hints on how to spend fewer next time. Yes, that's Claude critiquing Claude's own spending habits, and yes it runs on your own subscription and local credentials.
+
+
+## Bonus - a status line
+Install the bundled Claude Code status line to see context usage, token counts, and rate limits right in your terminal - so the surprise comes *before* the limit, not after:
+```text
+[Opus 4.8] Context: ▓▓▓░░░░░░░ 32% used (45.2k, 87% cached)  |  Tokens: 1.2M total (+45.2k, 3 turns) ...
+```
+
+## Contributing
+
+PRs and feature requests are welcome.
+```
+git clone https://github.com/dichev/claude-discover.git && cd claude-discover
+npm install
+npm run dev   # start the tool with vite's hot reload
+npm test      # run the test suite
+```
+
+**Verifying token/cost calculations** - trust, but verify. You can print the tool's per-period token usage and cost as a terminal table, and then compare it against **ccusage** - the numbers should match to the cent:
+
+```
+node test/scripts/usage.mjs monthly --timezone UTC
+npx ccusage claude monthly -z UTC
+```
+---
+**[MIT license](LICENSE)** - Not affiliated with Anthropic.

package/bin/claude/hooks.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/*
+Single entry point for every Claude Code hook this app installs — reads the hook event JSON from stdin
+and dispatches on hook_event_name; add new hooks as new branches in main(). Standalone (no imports from
+src/), wired into <CLAUDE_DIR>/settings.json by the app's ProxySwitch (StatusBar Activate/Deactivate button).
+
+Currently handled:
+- SessionStart → ensureProxy(): revive the request-capture proxy (bin/proxy.mjs) if it's
+  down. settings.json's env.ANTHROPIC_BASE_URL survives a PC restart or proxy crash, and without this every
+  Claude Code request would hit a dead port. A SessionStart hook's stdout is injected into the session
+  context, so only stderr may speak — exit 1 shows the warning without blocking the session.
+
+Copy-paste into <CLAUDE_DIR>/settings.json (replace the path):
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "node /ABSOLUTE/PATH/TO/claude-discover/bin/claude/hooks.mjs" }] }
+    ]
+  }
+}
+*/
+
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { text } from 'node:stream/consumers'
+import { PROXY_URL, PING_ROUTE, PING_RESPONSE, DATA_DIR, ERROR_LOG_PATH } from '../proxy.config.js'
+
+
+const DEBUG_LOG = false // Log every incoming hook event to DEBUG_LOG_FILE
+const DEBUG_LOG_FILE = path.join(DATA_DIR, 'hooks.debug.log')
+const ERROR_LOG = true // Log hook errors to ERROR_LOG_FILE
+const ERROR_LOG_FILE = path.join(DATA_DIR, 'hooks.error.log')
+
+const CLAUDE_HOOKS = {
+  SESSION_START: 'SessionStart',
+}
+
+const PROXY_PATH = path.join(import.meta.dirname, '..', 'proxy.mjs')
+
+
+function log(file, data) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.appendFileSync(file, `${new Date().toISOString()} ${data}\n`)
+  } catch {}
+}
+
+
+async function ping() {
+  try {
+    const res = await fetch(`${PROXY_URL}${PING_ROUTE}`, { signal: AbortSignal.timeout(1000) })
+    return res.ok && (await res.text()) === PING_RESPONSE
+  } catch { return false }
+}
+
+
+async function ensureProxy() {
+  if (await ping()) return // the common case — one loopback round-trip per session start
+
+  const child = spawn(process.execPath, [PROXY_PATH], { detached: true, stdio: 'ignore', windowsHide: true })
+  const exited = new Promise(resolve => child.once('exit', resolve)) // idempotent: exits 0 when one is already listening
+  child.unref()
+
+  // Poll until it answers (startup includes a ≤5s upstream check), racing the child's exit.
+  const settle = (async () => {
+    for (let i = 0; i < 40; i++) {
+      if (await ping()) return 'up'
+      await new Promise(r => setTimeout(r, 200))
+    }
+    return 'unresponsive'
+  })()
+
+  const outcome = await Promise.race([exited, settle])
+  if (outcome === 'up' || await ping()) return // up, or a proxy of ours won the race and is now answering
+
+  // Exit 0 ("already running") + failed ping = a foreign process holds the port Claude Code sends API traffic to
+  let msg = `capture proxy failed to start (see ${ERROR_LOG_PATH}) — Claude Code cannot reach the API until it runs; disable capture via the app's Stop button to unblock`
+  if (outcome === 0) msg = `${PROXY_URL} is held by another process that is not the capture proxy — Claude Code is configured to send API traffic there`
+  if (outcome === 2) msg = 'cannot reach api.anthropic.com — capture proxy not started'
+  console.error('claude-discover: ' + msg)
+  process.exitCode = 1
+}
+
+
+async function main() {
+  const raw = await text(process.stdin)
+  if (DEBUG_LOG) log(DEBUG_LOG_FILE, raw.trim())
+
+  try {
+    const event = JSON.parse(raw || '{}') // inside the try so a malformed payload is logged, not silently swallowed
+    if (event.hook_event_name === CLAUDE_HOOKS.SESSION_START) {
+      await ensureProxy()
+    }
+  }
+  catch (err) {
+    if (ERROR_LOG) log(ERROR_LOG_FILE, err?.stack || err)
+  }
+}
+
+main().catch(() => {}).finally(() => process.exit(process.exitCode ?? 0))

package/bin/claude/statusline.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+//
+// Claude Code status line. Reads the hook JSON from stdin and prints one colored line
+// summarizing the model, context-window usage, token totals, and rate-limit windows.
+// Installed as the `statusLine` command from the app: StatusBar → Status line → Activate
+// (see src/main/services/switchers/StatuslineSwitch.js).
+//
+// Example output:
+//   [Opus 4.8] Context: ▓▓▓░░░░░░░ 32% used (45.2k, 87% cached)  |  Tokens: 1.2M total (+45.2k, 3 turns)  |  Usage limit: 42% used (resets in 2h 30m)  |  Weekly limit: 18% used (resets in 3d 4h)
+//
+
+import { readFileSync } from 'node:fs'
+import { styleText } from 'node:util'
+
+
+// Formatting
+const THRESHOLDS = { // (white, yellow, red)
+  context: [0, 100_000, 160_000],
+  limit:   [0, 60, 90],
+  cache:   [90, 60, 0],
+  tokens:  [0, 250_000, 1_000_000],
+  session: [0, 5_000_000, 20_000_000],
+  turns:   [0, 10, 25],
+}
+
+const NO_COLOR = process.env.NO_COLOR !== undefined // standard opt-out; styleText can't honor it for piped output, so gate here
+
+function colorize(kind, text, value = 0) {
+  const bounds = THRESHOLDS[kind]
+  const n = bounds.filter(b => value >= b).length
+  const TIERS  = [null, 'yellow', 'red'] // indexed by severity tier
+  const idx = bounds[0] < bounds.at(-1) ? n - 1 : bounds.length - n
+  const color = TIERS[idx]
+  // validateStream:false forces codes through the pipe (statusline output isn't a TTY)
+  return color && !NO_COLOR ? styleText(color, text, { validateStream: false }) : text
+}
+
+
+// Collect stdin data
+const data = JSON.parse(readFileSync(0, 'utf-8')) // fd 0 = stdin
+const modelName = data.model?.display_name?.replace('Claude ', '') || '?'
+const parts = []
+
+
+
+// Context window
+const ctx = data.context_window || {}
+const total = ctx.context_window_size || 0
+if (total) {
+  const usage = ctx.current_usage || {}
+  const hit  = usage.cache_read_input_tokens || 0
+  const used = hit + (usage.cache_creation_input_tokens || 0) + (usage.input_tokens || 0)
+  const pct  = Math.round((used / total) * 100)
+  const cpct = used ? Math.floor((hit * 100) / used) : 0
+  const filled = Math.floor(pct / 10)
+  const bar    = '▓'.repeat(filled) + '░'.repeat(10 - filled)
+  const head   = colorize('context', `${bar} ${pct}% used`, used)
+  const tokens = colorize('context', `${(used / 1000).toFixed(1)}k`, used)
+  const cached = used ? colorize('cache', `${cpct}% cached`, cpct) : `${cpct}% cached`
+  parts.push(`Context: ${head} (${tokens}, ${cached})`)
+}
+
+
+
+// Total tokens (per session and per reply loop)
+function agentLoopUsage(transcriptPath) { // Read the transcript JSONL and sum API usage for the current agent loop and the whole session.
+  const lines   = readFileSync(transcriptPath, 'utf-8').split(/\r?\n/).filter(Boolean)
+  let loop      = { total: 0, turns: 0 } // last prompt-reply breakdown
+  const session = { total: 0, turns: 0 } // whole-session breakdown
+  let seen = new Set() // One API response spans multiple lines (one per content block), each repeating the usage block, so dedupe by message.id.
+
+  for (const line of lines) {
+    let e
+    try { e = JSON.parse(line) } catch { continue } // the transcript may be mid-append — skip a half-written line
+    const msg = e.message || {}
+
+    if (e.type === 'user' && !e.isMeta) {
+      const isToolReply = Array.isArray(msg.content) && msg.content.some(b => b.type === 'tool_result')
+      if (!isToolReply) { // real user prompt = new loop
+        loop = { total: 0, turns: 0 }
+        seen = new Set()
+      }
+    } else if (e.type === 'assistant' && !seen.has(msg.id)) {
+      seen.add(msg.id)
+      const u = msg.usage || {}
+      const tokens = (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0)
+      for (const d of [loop, session]) {
+        d.total += tokens
+        d.turns += 1
+      }
+    }
+  }
+  return [loop, session]
+}
+
+if (data.transcript_path) {
+  const [loop, session] = agentLoopUsage(data.transcript_path)
+  const fmt = n => n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : `${(n / 1000).toFixed(1)}k`
+  const tokensS = colorize('tokens',  fmt(loop.total),    loop.total)
+  const sessS   = colorize('session', fmt(session.total), session.total)
+  const turnsS  = colorize('turns', `${loop.turns} turn${loop.turns !== 1 ? 's' : ''}`, loop.turns)
+  parts.push(`Tokens: ${sessS} total (+${tokensS}, ${turnsS})`)
+}
+
+
+
+// Rate limits (5-hour and weekly windows)
+function fmtReset(resetsAt) { // Format remaining time until a unix-epoch reset, e.g. "2h 30m" (null if no timestamp).
+  if (!resetsAt) return null
+  const secs = Math.max(0, Math.floor(Number(resetsAt)) - Math.floor(Date.now() / 1000))
+  const min  = Math.floor(secs / 60) % 60
+  const hrs  = Math.floor(secs / 3600) % 24
+  const days = Math.floor(secs / 86400)
+  if (days) return `${days}d ${hrs}h`
+  if (hrs)  return `${hrs}h ${min}m`
+  return `${min}m`
+}
+
+const rl = data.rate_limits || {}
+for (const [label, window] of [['Usage limit', rl.five_hour], ['Weekly limit', rl.seven_day]]) {
+  if (!window) continue
+  const pct      = Math.floor(window.used_percentage || 0)
+  const reset    = fmtReset(window.resets_at)
+  const resetStr = reset ? ` (resets in ${reset})` : ''
+  parts.push(`${label}: ${colorize('limit', `${pct}% used${resetStr}`, pct)}`)
+}
+
+
+// Status line
+process.stdout.write(`[${modelName}] ` + parts.join('  |  ') + '\n')

package/bin/claude-discover.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Launches the app from an npm install (`npx claude-discover`): points the local
+// Electron binary at the package root, whose package.json main is out/main/main.js.
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import electron from 'electron' // under plain node the electron package exports its binary path
+
+const appDir = fileURLToPath(new URL('..', import.meta.url))
+if (!existsSync(new URL('../out/main/main.js', import.meta.url))) {
+  console.error('claude-discover: missing build output — run `npm run build` first')
+  process.exit(1)
+}
+
+spawn(electron, [appDir, ...process.argv.slice(2)], { stdio: 'inherit' })
+  .on('close', code => process.exit(code ?? 0))

package/bin/proxy.config.js

@@ -0,0 +1,19 @@
+// Shared config for the request-capture proxy (bin/proxy.mjs) — the single place its port,
+// routes, ping body and paths are defined, imported by bin/ and src/main/. Sole exception:
+// the renderer doesn't import from bin/, so StatusBar's tooltip hardcodes PROXY_URL.
+
+import os from 'node:os'
+import path from 'node:path'
+
+export const HOST      = '127.0.0.1' // loopback only, on purpose — the proxy sees auth headers and must never listen on external interfaces
+export const PORT      = process.env.CLAUDE_DISCOVER_PORT || 41414 // arbitrary uncommon port (unregistered, unlikely to collide); env override used only by tests
+export const PROXY_URL = `http://${HOST}:${PORT}`
+export const UPSTREAM  = process.env.CLAUDE_DISCOVER_UPSTREAM || 'https://api.anthropic.com' // env override used only by tests
+
+export const EXIT_ROUTE    = '/claude-discover/exit' // POST here makes the proxy exit — how --restart replaces a running instance (the port is loopback-only and assumed ours)
+export const PING_ROUTE    = '/claude-discover/ping' // answered directly (never forwarded) — polled by the app's ProxySwitch to show/settle the running state
+export const PING_RESPONSE = 'claude-discover-proxy' // the ping body — proves it's this proxy on the port, not some other process
+
+export const DATA_DIR       = process.env.CLAUDE_DISCOVER_DIR || path.join(os.homedir(), '.claude-discover') // global on purpose — session ids are unique, so one flat dir serves every Claude dir (env override used only by tests)
+export const REQUESTS_DIR   = path.join(DATA_DIR, 'requests') // logs are kept forever — nothing deletes them
+export const ERROR_LOG_PATH = path.join(DATA_DIR, 'proxy.error.log') // capture errors — capture must never fail a request

package/bin/proxy.mjs

@@ -0,0 +1,268 @@
+// Local logging proxy for Claude Code's API traffic — captures what transcripts never record
+// (system prompt, tool definitions, injected reminders, request params) plus the raw responses.
+// Claude Code is pointed at it via env.ANTHROPIC_BASE_URL (installed by the app's StatusBar
+// Activate button); started manually with `npm run proxy`. Capture must never fail or delay a request — errors go
+// to ~/.claude-discover/proxy.error.log instead of the client.
+//
+// Usage: node bin/proxy.mjs [--restart] — port/upstream/dir come from proxy.config.js ($CLAUDE_DISCOVER_* env overrides used only by tests)
+
+import fs from 'node:fs'
+import path from 'node:path'
+import http from 'node:http'
+import https from 'node:https'
+import zlib from 'node:zlib'
+import crypto from 'node:crypto'
+import { pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
+
+import { HOST, PORT, PROXY_URL, UPSTREAM, EXIT_ROUTE, PING_ROUTE, PING_RESPONSE, REQUESTS_DIR, ERROR_LOG_PATH } from './proxy.config.js'
+
+
+// ── 1. Generic tee proxy — knows nothing about Claude ────────────────────────
+// Forwards verbatim to `upstream` and pipes the response back while buffering both bodies.
+// `onExchange(exchange)` fires exactly once per request, after piping (its response fields are
+// undefined when upstream never responded); `errorBody(err)` shapes the 502 when it's unreachable.
+
+function createProxy({ upstream, onExchange, onError, errorBody }) {
+  const mod = upstream.protocol === 'http:' ? http : https
+
+  return http.createServer(async (req, res) => {
+    if (req.method === 'POST' && req.url === EXIT_ROUTE) {
+      // Loopback-only control route. The restart client is a bare Node request; reject anything carrying browser fetch metadata so a web page can't CSRF the proxy into exiting.
+      if (req.headers.origin || req.headers.referer || req.headers['sec-fetch-site']) return res.writeHead(403).end('forbidden')
+      return res.end('bye', () => process.exit(0))
+    }
+    if (req.url === PING_ROUTE) return res.end(PING_RESPONSE)
+    const started = Date.now()
+    let requestBody
+    try { requestBody = Buffer.concat(await req.toArray()) } catch { return res.destroy() }
+
+    let done = false // response 'close' and upstream 'error' can race — fire onExchange exactly once
+    const finish = (status, responseHeaders, responseBody) => {
+      if (done) return
+      done = true
+      const exchange = { req, requestBody, status, responseHeaders, responseBody, timestamp: new Date(started).toISOString(), durationMs: Date.now() - started }
+      try { onExchange(exchange) } catch (err) { onError(err, `logging ${req.method} ${req.url}`) }
+    }
+
+    const headers = { ...req.headers, host: upstream.host }
+    delete headers.connection
+
+    // Claude code offers "gzip, deflate, br, zstd", but we accept gzip only to keep it simple
+    if (/\bgzip\b/.test(headers['accept-encoding'] ?? '')) {
+      headers['accept-encoding'] = 'gzip'
+    } else {
+      delete headers['accept-encoding']
+    }
+
+    const up = mod.request(new URL(req.url, upstream), { method: req.method, headers }, upRes => {
+      const resHeaders = { ...upRes.headers }
+      delete resHeaders['transfer-encoding'] // node re-frames the piped body itself
+      delete resHeaders.connection
+      res.writeHead(upRes.statusCode, resHeaders)
+      const chunks = []
+      upRes.on('data', c => chunks.push(c))
+      upRes.pipe(res)
+      // 'close' fires after 'end' and also on an aborted stream — a truncated body is still captured
+      upRes.on('close', () => {
+        finish(upRes.statusCode, upRes.headers, decode(upRes.headers['content-encoding'], Buffer.concat(chunks)))
+        if (!upRes.complete) res.destroy() // upstream died mid-body — surface the reset so the client can retry
+      })
+    })
+    // Client gone mid-exchange — tear down upstream too; headersSent means upstream responded and its 'close' captures the partial body, otherwise log the attempt here (up.destroy() emits no 'error')
+    res.on('close', () => {
+      if (done) return
+      up.destroy()
+      if (!res.headersSent) finish()
+    })
+    up.on('error', err => {
+      onError(err, `${req.method} ${req.url} → ${upstream.host}`)
+      finish()
+      if (res.headersSent) return res.destroy() // mid-stream failure — never append an error body to a partially-piped response
+      res.writeHead(502, { 'content-type': 'application/json' })
+      res.end(errorBody(err))
+    })
+    up.end(requestBody)
+  })
+}
+
+// gzip is the only encoding ever advertised upstream, so it's the only decoder needed.
+// Z_SYNC_FLUSH tolerates a truncated stream (aborted response) and yields what did decompress.
+function decode(encoding, buf) {
+  if (encoding !== 'gzip') return buf.toString('utf8')
+  try { return zlib.gunzipSync(buf, { finishFlush: zlib.constants.Z_SYNC_FLUSH }).toString('utf8') } catch { return buf.toString('utf8') }
+}
+
+// ── 2. Claude Code capture ───────────────────────────────────────────────────
+// One JSON record per exchange in ~/.claude-discover/requests/<sessionId>.requests.jsonl
+// (session id from the X-Claude-Code-Session-Id header).
+
+// Keep the header name (useful signal) but never the credential.
+function redactHeaders(headers, keys) {
+  for (const k of keys) if (headers?.[k]) headers[k] = '<redacted>'
+  return headers
+}
+
+function logRequest({ req, requestBody, status, responseHeaders, responseBody, timestamp, durationMs }) {
+  const sessionId = req.headers['x-claude-code-session-id']
+  if (!sessionId || !/^[\w-]+$/.test(sessionId)) return // header value becomes a filename — accept only safe ids
+  const logPath = path.join(REQUESTS_DIR, `${sessionId}.requests.jsonl`)
+  const record = { type: 'api-request', timestamp, url: `${req.method} ${req.url}`, status, durationMs }
+  record.requestHeaders = redactHeaders(req.headers, ['authorization', 'x-api-key', 'proxy-authorization', 'cookie'])
+  record.responseHeaders = redactHeaders(responseHeaders, ['set-cookie']) // upstream sits behind Cloudflare
+  let body
+  try { body = JSON.parse(requestBody.toString('utf8')) } catch {}
+  // Every endpoint is captured in full — count_tokens probes re-send the conversation, so the
+  // shared per-session seen-set collapses their payloads to $refs. An unparsable body: size only.
+  if (body) record.request = dedupeRequest(body, seenFor(sessionId, logPath))
+  else if (requestBody.length) record.size = requestBody.length
+  record.response = parseResponse(responseHeaders?.['content-type'], responseBody)
+  fs.mkdirSync(REQUESTS_DIR, { recursive: true })
+  fs.appendFileSync(logPath, JSON.stringify(record) + '\n')
+}
+
+function parseResponse(contentType, text) {
+  if (text == null) return undefined // upstream never responded — the attempt is logged without a response
+  if (contentType?.includes('text/event-stream')) return assembleSSE(text)
+  try { return JSON.parse(text) } catch { return text.slice(0, 20_000) }
+}
+
+// Folds a raw SSE stream back into the final API message — what a non-streaming request would have
+// returned. Malformed/truncated streams degrade to { $sseParseError, raw } instead of throwing.
+export function assembleSSE(text) {
+  try {
+    let message
+    const partialJson = {} // content index → accumulated input_json_delta string
+    for (const chunk of text.split(/\r?\n\r?\n/)) {
+      const data = chunk.split(/\r?\n/).find(l => l.startsWith('data:'))
+      if (!data) continue
+      const ev = JSON.parse(data.slice(5))
+      const block = message?.content[ev.index]
+      switch (ev.type) {
+        case 'message_start': message = ev.message; break
+        case 'content_block_start': message.content[ev.index] = ev.content_block; break
+        case 'content_block_delta': {
+          const d = ev.delta
+          if (d.type === 'text_delta') block.text += d.text
+          else if (d.type === 'thinking_delta') block.thinking += d.thinking
+          else if (d.type === 'signature_delta') block.signature = (block.signature ?? '') + d.signature
+          else if (d.type === 'input_json_delta') partialJson[ev.index] = (partialJson[ev.index] ?? '') + d.partial_json
+          break
+        }
+        case 'content_block_stop': if (ev.index in partialJson) block.input = JSON.parse(partialJson[ev.index] || '{}'); break
+        case 'message_delta': Object.assign(message, ev.delta); Object.assign(message.usage ??= {}, ev.usage); break
+        case 'error': return ev
+      }
+    }
+    if (!message) throw new Error('no message_start event')
+    return message
+  } catch (err) {
+    return { $sseParseError: String(err?.message || err), raw: text.slice(0, 20_000) }
+  }
+}
+
+// ── 3. Dedup hashing ─────────────────────────────────────────────────────────
+// The API re-sends the whole conversation each turn, so each bulk value is logged in full
+// ({ $hash, value }) only the first time, then as { $ref }; readers rebuild the map top-down.
+
+// The logged request body: params verbatim, bulk fields (system, tools, each message) deduped.
+export function dedupeRequest(body, seen = new Set()) {
+  const dedupe = value => {
+    // hash with cache_control stripped — breakpoints move between requests, unchanged content must still match
+    const json = JSON.stringify(value, (k, v) => k === 'cache_control' ? undefined : v)
+    // 16 base64url chars = 96 bits — a collision (silent: a new value logged as someone else's $ref) is negligible
+    const hash = crypto.createHash('sha256').update(json).digest('base64url').slice(0, 16)
+    if (seen.has(hash)) return { $ref: hash }
+    seen.add(hash)
+    return { $hash: hash, value: deep(value) }
+  }
+  // Inside a newly-seen value, array elements (content blocks, tool schemas, …) are deduped
+  // individually too, at any depth — one injected/updated element (e.g. a system-reminder)
+  // must not re-log its siblings. Primitive elements stay inline: a $ref would outweigh them.
+  const deep = v =>
+    Array.isArray(v) ? v.map(el => el && typeof el === 'object' ? dedupe(el) : el)
+    : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, deep(x)]))
+    : v
+  const out = { ...body }
+  if (out.system != null) out.system = dedupe(out.system)
+  if (out.tools != null) out.tools = dedupe(out.tools)
+  if (out.messages) out.messages = out.messages.map(dedupe)
+  return out
+}
+
+// Warm the seen-set from the request log on first touch, so a proxy restart doesn't re-log full values.
+const seenHashes = new Map() // sessionId → Set of hashes already logged in full
+function seenFor(sessionId, logPath) {
+  let seen = seenHashes.get(sessionId)
+  if (!seen) seenHashes.set(sessionId, seen = warmFromLog(logPath))
+  return seen
+}
+
+function warmFromLog(logPath) {
+  const seen = new Set()
+  const walk = v => { // collect every $hash at any depth
+    if (!v || typeof v !== 'object') return
+    if (v.$hash) seen.add(v.$hash)
+    for (const x of Object.values(v)) walk(x)
+  }
+  let lines = []
+  try { lines = fs.readFileSync(logPath, 'utf8').split('\n') } catch {}
+  for (const line of lines) {
+    try { walk(JSON.parse(line).request) } catch {}
+  }
+  return seen
+}
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+
+// Capture/upstream errors land here instead of ever reaching the client.
+function logError(err, context) {
+  try { // AggregateError (e.g. all of a host's addresses failed to connect) hides the detail in err.errors
+    const causes = (err?.errors ?? []).map(e => `\n  cause: ${e?.message || e}`).join('')
+    const message = `${new Date().toISOString()} ${context ? `[${context}] ` : ''}${err?.stack || err}${causes}\n`
+    fs.mkdirSync(path.dirname(ERROR_LOG_PATH), { recursive: true }) // the error may fire before any request write creates the dir
+    fs.appendFileSync(ERROR_LOG_PATH, message)
+  } catch {}
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+if (isMain) {
+  const args = parseArgs({
+    options: {
+      restart: { type: 'boolean' }, // replace an already-running instance instead of exiting
+    }
+  })
+  const upstream = new URL(UPSTREAM)
+  // Fail fast when the upstream is unreachable — a clear exit beats a proxy that 502s every request.
+  // Runs before --restart so a working instance is never replaced by a broken one. Exit code 2 is
+  // recognized by the app's ProxySwitch ("cannot reach upstream").
+  try {
+    await fetch(new URL('/v1/models', upstream), { signal: AbortSignal.timeout(5000) })
+  } catch (err) {
+    console.error(`Cannot reach ${upstream.origin} (${err?.cause?.code || err?.cause?.message || err?.name || err})`)
+    logError(err, `startup check → ${upstream.origin}`)
+    process.exit(2)
+  }
+  const server = createProxy({
+    upstream: upstream,
+    onExchange: logRequest,
+    onError: logError,
+    errorBody: err => JSON.stringify({ type: 'error', error: { type: 'api_error', message: `claude-discover proxy: upstream unreachable (${err.code || err.message})` } }),
+  })
+  if (args.values.restart) {
+    // Ask a previous instance (the port is loopback-only and assumed ours) to exit before listening.
+    const replaced = await new Promise(resolve => http.request(`${PROXY_URL}${EXIT_ROUTE}`, { method: 'POST' }, () => resolve(true)).on('error', () => resolve(false)).end())
+    if (replaced) {
+      console.log(`Replacing running proxy on ${PROXY_URL}...`)
+      await new Promise(resolve => setTimeout(resolve, 500)) // give it a moment to release the port
+    }
+  }
+  server.on('error', err => {
+    if (err.code === 'EADDRINUSE' && args.values.restart) { console.error(`Failed to restart: ${HOST}:${PORT} is still busy`); process.exit(1) }
+    if (err.code === 'EADDRINUSE') { console.log(`Capture proxy already running on ${HOST}:${PORT}`); process.exit(0) }
+    logError(err)
+    process.exit(1)
+  })
+  server.listen(PORT, HOST, () => console.log(`Capture proxy listening on ${PROXY_URL} → ${upstream.origin}\nLogging requests to ${REQUESTS_DIR}`))
+}