@kylindc/ccxray 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [Unreleased]
+
+### Fixed
+
+- **Orphan hub detection**: When `hub.json` lockfile is missing but a hub is still running, clients now probe the default port and reconnect automatically instead of failing with EADDRINUSE
+- **Browser auto-open**: First client connecting to a hub now opens the dashboard, regardless of whether the client forked the hub or discovered an existing one
+- **ECONNRESET handling**: Upstream socket destruction mid-response no longer leaves the client hanging; added `proxyRes` error handler for both SSE and non-SSE paths
+- **OOM on long-running hub**: In-memory entries capped at 5000 (configurable via `CCXRAY_MAX_ENTRIES`), oldest evicted first; disk logs unaffected
+
+### Added
+
+- `CCXRAY_MAX_ENTRIES` environment variable to configure in-memory entry limit (default: 5000)
+- Hub status endpoint includes `app: 'ccxray'` marker for identity verification
+- 57 new tests (98 → 155) covering proxy E2E, SSE streaming, intercept lifecycle, error paths, concurrency, and hub crash recovery
+
+## 1.1.0
+
+### Added
+
+- **Multi-project hub**: Multiple `ccxray claude` instances automatically share a single proxy server and dashboard. No configuration needed — the first instance starts a hub, subsequent ones connect to it.
+- **`ccxray status`**: New subcommand showing hub info and connected clients.
+- **Hub crash auto-recovery**: If the hub process dies, connected clients detect and restart it within ~5 seconds.
+- **Version compatibility check**: Clients with different major versions are rejected with a clear error message.
+
+### Changed
+
+- **Logs location**: Moved from `./logs/` (package-relative) to `~/.ccxray/logs/` (user home). Existing logs are automatically migrated on first run.
+- **`--port` behavior**: Explicitly specifying `--port` now opts out of hub mode, running an independent server instead.
+
+### Migration from 1.0.0
+
+- Logs are automatically migrated from the old `logs/` directory to `~/.ccxray/logs/` on first startup. No manual action needed.
+- If you use `AUTH_TOKEN`, hub discovery endpoints (`/_api/health`, `/_api/hub/*`) bypass authentication since they are local IPC.
+
+## 1.0.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Lee
+
+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.ja.md

@@ -0,0 +1,144 @@
+# ccxray
+
+[English](README.md) | [正體中文](README.zh-TW.md) | **日本語**
+
+AIエージェントセッションのX線ビュー。ゼロ設定のHTTPプロキシで、Claude CodeとAnthropic API間のすべてのAPI呼び出しを記録し、エージェント内部で実際に何が起きているかを確認できるリアルタイムダッシュボードを提供します。
+
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+![ccxrayダッシュボード](https://raw.githubusercontent.com/lis186/ccxray/main/docs/dashboard.png)
+
+## なぜ必要か
+
+Claude Codeはブラックボックスです。以下が見えません：
+- どんなシステムプロンプトを送信しているか（バージョン間の変更も含む）
+- 各ツール呼び出しのコスト
+- なぜ30秒も思考しているのか
+- 200Kトークンのコンテキストウィンドウを何が消費しているのか
+
+ccxrayはそれをガラス箱に変えます。
+
+## クイックスタート
+
+```bash
+npx @kylindc/ccxray claude
+```
+
+これだけです。プロキシが起動し、Claude Codeがプロキシ経由で接続し、ダッシュボードが自動的にブラウザで開きます。複数のターミナルで実行すると、自動的に一つのダッシュボードを共有します。
+
+### その他の実行方法
+
+```bash
+ccxray                           # プロキシ + ダッシュボードのみ
+ccxray claude --continue         # すべてのclaude引数がそのまま渡される
+ccxray --port 8080 claude        # カスタムポート（独立モード、hub共有なし）
+ccxray claude --no-browser       # ブラウザの自動オープンをスキップ
+ccxray status                    # hubの情報と接続中のクライアントを表示
+ANTHROPIC_BASE_URL=http://localhost:5577 claude   # 手動設定（既存セッション）
+```
+
+### マルチプロジェクト
+
+複数のターミナルで `ccxray claude` を実行すると、自動的に単一のプロキシとダッシュボードを共有します。設定は不要です。
+
+```bash
+# Terminal 1
+cd ~/project-a && ccxray claude     # hubを起動 + claude
+
+# Terminal 2
+cd ~/project-b && ccxray claude     # 既存のhubに接続
+
+# 両プロジェクトが http://localhost:5577 のダッシュボードに表示
+```
+
+Hubプロセスがクラッシュした場合、接続中のクライアントは数秒以内に自動的に復旧します。
+
+```bash
+$ ccxray status
+Hub: http://localhost:5577 (pid 12345, uptime 3600s, v1.1.0)
+Connected clients (2):
+  [1] pid 23456 — ~/dev/project-a
+  [2] pid 34567 — ~/dev/project-b
+```
+
+`--port` を使用すると独立モードで実行できます。
+
+## 機能
+
+### タイムライン
+
+エージェントの思考をリアルタイムで観察。各ターンを思考ブロック（所要時間付き）、ツール呼び出しのインラインプレビュー、アシスタント応答に分解します。
+
+![タイムラインビュー](https://raw.githubusercontent.com/lis186/ccxray/main/docs/timeline.png)
+
+### 使用量とコスト
+
+実際の支出を把握。セッションヒートマップ、消費レート、ROI計算 — トークンの行き先を正確に把握できます。
+
+![使用量分析](https://raw.githubusercontent.com/lis186/ccxray/main/docs/usage.png)
+
+### システムプロンプト追跡
+
+バージョンの自動検出とdiffビューア。Claude Codeのアップデートで何が変わったかを正確に把握 — プロンプトの変更を見逃しません。
+
+![システムプロンプト追跡](https://raw.githubusercontent.com/lis186/ccxray/main/docs/system-prompt.png)
+
+### その他
+
+- **セッション検出** — Claude Codeセッションごとに自動グループ化。プロジェクト/作業ディレクトリの抽出付き
+- **トークン会計** — ターンごとの内訳：input/output/cache-read/cache-createトークン、USD単位のコスト、コンテキストウィンドウ使用率バー
+
+## 仕組み
+
+```
+Claude Code  ──►  ccxray (:5577)  ──►  api.anthropic.com
+                      │
+                      ▼
+          ~/.ccxray/logs/ (JSON)
+                      │
+                      ▼
+                  ダッシュボード（同じポート）
+```
+
+ccxrayは透過型HTTPプロキシです。リクエストをそのままAnthropicに転送し、リクエストとレスポンスの両方をJSONファイルとして記録し、同じポートでWebダッシュボードを提供します。APIキーは不要です — Claude Codeが送信する内容をそのまま通過させます。
+
+## 設定
+
+### CLIフラグ
+
+| フラグ | 説明 |
+|---|---|
+| `--port <number>` | プロキシ + ダッシュボードのポート（デフォルト: 5577）。hub共有を無効化 |
+| `--no-browser` | ダッシュボードをブラウザで自動オープンしない |
+
+### 環境変数
+
+| 変数 | デフォルト | 説明 |
+|---|---|---|
+| `PROXY_PORT` | `5577` | プロキシ + ダッシュボードのポート（`--port`で上書き） |
+| `BROWSER` | — | `none`に設定すると自動オープンを無効化 |
+| `AUTH_TOKEN` | _（なし）_ | アクセス制御用APIキー（未設定時は無効） |
+| `CCXRAY_HOME` | `~/.ccxray` | hubロックファイル、ログ、hub.logの基本ディレクトリ |
+
+ログは`~/.ccxray/logs/`に`{timestamp}_req.json`と`{timestamp}_res.json`として保存されます。v1.0からアップグレードする場合、`./logs/`のログは初回起動時に自動的に移行されます。
+
+## Docker
+
+```bash
+docker build -t ccxray .
+docker run -p 5577:5577 ccxray
+```
+
+## 要件
+
+- Node.js 18+
+
+## 作者の他のプロジェクト
+
+- [SourceAtlas](https://sourceatlas.io/) — あらゆるコードベースへのマップ
+- [AskRoundtable](https://github.com/AskRoundtable/expert-skills) — AIをMunger、Feynman、Paul Grahamのように思考させる
+- Xで [@lis186](https://x.com/lis186) をフォローして最新情報をチェック
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,145 @@
+# ccxray
+
+**English** | [正體中文](README.zh-TW.md) | [日本語](README.ja.md)
+
+X-ray vision for AI agent sessions. A zero-config HTTP proxy that records every API call between Claude Code and Anthropic, with a real-time dashboard to inspect what's actually happening inside your agent.
+
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+![ccxray dashboard](https://raw.githubusercontent.com/lis186/ccxray/main/docs/dashboard.png)
+
+## Why
+
+Claude Code is a black box. You can't see:
+- What system prompts it sends (and how they change between versions)
+- How much each tool call costs
+- Why it's thinking for 30 seconds
+- What context is eating your 200K token window
+
+ccxray makes it a glass box.
+
+## Quick Start
+
+```bash
+npx @kylindc/ccxray claude
+```
+
+That's it. Proxy starts, Claude Code launches through it, and the dashboard opens automatically in your browser. Run it in multiple terminals — they automatically share one dashboard.
+
+### Other ways to run
+
+```bash
+ccxray                           # Proxy + dashboard only
+ccxray claude --continue         # All claude args pass through
+ccxray --port 8080 claude        # Custom port (independent, no hub sharing)
+ccxray claude --no-browser       # Skip auto-open browser
+ccxray status                    # Show hub info and connected clients
+ANTHROPIC_BASE_URL=http://localhost:5577 claude   # Manual setup (existing sessions)
+```
+
+### Multi-project
+
+Running `ccxray claude` in multiple terminals automatically shares a single proxy and dashboard — no configuration needed.
+
+```bash
+# Terminal 1
+cd ~/project-a && ccxray claude     # Starts hub + claude
+
+# Terminal 2
+cd ~/project-b && ccxray claude     # Connects to existing hub
+
+# Both projects visible in one dashboard at http://localhost:5577
+```
+
+If the hub process crashes, connected clients automatically recover within seconds.
+
+```bash
+$ ccxray status
+Hub: http://localhost:5577 (pid 12345, uptime 3600s, v1.1.0)
+Connected clients (2):
+  [1] pid 23456 — ~/dev/project-a
+  [2] pid 34567 — ~/dev/project-b
+```
+
+Use `--port` to opt out and run an independent server instead.
+
+## Features
+
+### Timeline
+
+Watch your agent think in real-time. Every turn broken down into thinking blocks (with duration), tool calls with inline previews, and assistant responses.
+
+![Timeline view](https://raw.githubusercontent.com/lis186/ccxray/main/docs/timeline.png)
+
+### Usage & Cost
+
+Track your real spending. Session heatmap, burn rate, ROI calculator — know exactly where your tokens go.
+
+![Usage analytics](https://raw.githubusercontent.com/lis186/ccxray/main/docs/usage.png)
+
+### System Prompt Tracking
+
+Automatic version detection with diff viewer. See exactly what changed between Claude Code updates — never miss a prompt change again.
+
+![System prompt tracking](https://raw.githubusercontent.com/lis186/ccxray/main/docs/system-prompt.png)
+
+### More
+
+- **Session Detection** — Automatically groups turns by Claude Code session, with project/cwd extraction
+- **Token Accounting** — Per-turn breakdown: input/output/cache-read/cache-create tokens, cost in USD, context window usage bar
+
+## How It Works
+
+```
+Claude Code  ──►  ccxray (:5577)  ──►  api.anthropic.com
+                      │
+                      ▼
+              ~/.ccxray/logs/ (JSON)
+                      │
+                      ▼
+                  Dashboard (same port)
+```
+
+ccxray is a transparent HTTP proxy. It forwards requests to Anthropic unchanged, records both request and response as JSON files, and serves a web dashboard on the same port. No API key needed — it passes through whatever Claude Code sends.
+
+## Configuration
+
+### CLI flags
+
+| Flag | Description |
+|---|---|
+| `--port <number>` | Port for proxy + dashboard (default: 5577). Opts out of hub sharing. |
+| `--no-browser` | Don't auto-open the dashboard in your browser |
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PROXY_PORT` | `5577` | Port for proxy + dashboard (overridden by `--port`) |
+| `BROWSER` | — | Set to `none` to disable auto-open |
+| `AUTH_TOKEN` | _(none)_ | API key for access control (disabled when unset) |
+| `CCXRAY_HOME` | `~/.ccxray` | Base directory for hub lockfile, logs, and hub.log |
+| `CCXRAY_MAX_ENTRIES` | `5000` | Max in-memory entries (oldest evicted; disk logs unaffected) |
+
+Logs are stored in `~/.ccxray/logs/` as `{timestamp}_req.json` and `{timestamp}_res.json`. Upgrading from v1.0? Logs previously in `./logs/` are automatically migrated on first run.
+
+## Docker
+
+```bash
+docker build -t ccxray .
+docker run -p 5577:5577 ccxray
+```
+
+## Requirements
+
+- Node.js 18+
+
+## Also by the author
+
+- [SourceAtlas](https://sourceatlas.io/) — Your map to any codebase
+- [AskRoundtable](https://github.com/AskRoundtable/expert-skills) — Make your AI think like Munger, Feynman, or Paul Graham
+- Follow [@lis186](https://x.com/lis186) on X for updates
+
+## License
+
+MIT

package/README.zh-TW.md

@@ -0,0 +1,144 @@
+# ccxray
+
+[English](README.md) | **正體中文** | [日本語](README.ja.md)
+
+AI 代理工作階段的透視鏡。零設定的 HTTP 代理，記錄 Claude Code 與 Anthropic API 之間的每一次呼叫，搭配即時儀表板，讓你看清代理內部到底在做什麼。
+
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+![ccxray 儀表板](https://raw.githubusercontent.com/lis186/ccxray/main/docs/dashboard.png)
+
+## 為什麼需要
+
+Claude Code 是個黑盒子。你看不到：
+- 它送出了什麼 system prompt（以及版本間的變化）
+- 每次 tool call 花了多少錢
+- 為什麼它思考了 30 秒
+- 什麼東西吃掉了你的 200K token 上下文窗口
+
+ccxray 讓它變成透明的。
+
+## 快速開始
+
+```bash
+npx @kylindc/ccxray claude
+```
+
+就這樣。代理啟動、Claude Code 透過代理連線、儀表板自動在瀏覽器中開啟。在多個終端機執行時會自動共用同一個 dashboard。
+
+### 其他執行方式
+
+```bash
+ccxray                           # 只啟動代理 + 儀表板
+ccxray claude --continue         # 所有 claude 參數直接穿透
+ccxray --port 8080 claude        # 自訂 port（獨立模式，不共用 hub）
+ccxray claude --no-browser       # 不自動開啟瀏覽器
+ccxray status                    # 顯示 hub 資訊及已連線的 client
+ANTHROPIC_BASE_URL=http://localhost:5577 claude   # 手動設定（現有工作階段）
+```
+
+### 多專案
+
+在多個終端機執行 `ccxray claude` 會自動共用同一個 proxy 和 dashboard — 無需任何設定。
+
+```bash
+# Terminal 1
+cd ~/project-a && ccxray claude     # 啟動 hub + claude
+
+# Terminal 2
+cd ~/project-b && ccxray claude     # 連線至現有 hub
+
+# 兩個專案都顯示在 http://localhost:5577 的 dashboard
+```
+
+如果 hub 意外終止，已連線的 client 會在數秒內自動恢復。
+
+```bash
+$ ccxray status
+Hub: http://localhost:5577 (pid 12345, uptime 3600s, v1.1.0)
+Connected clients (2):
+  [1] pid 23456 — ~/dev/project-a
+  [2] pid 34567 — ~/dev/project-b
+```
+
+使用 `--port` 可改為獨立模式。
+
+## 功能
+
+### 時間軸
+
+即時觀看代理的思考過程。每個回合拆解為思考區塊（含時長）、tool call 內聯預覽、助手回應。
+
+![時間軸檢視](https://raw.githubusercontent.com/lis186/ccxray/main/docs/timeline.png)
+
+### 用量與成本
+
+追蹤你的實際花費。工作階段熱力圖、消耗速率、ROI 計算 — 精確掌握 token 流向。
+
+![用量分析](https://raw.githubusercontent.com/lis186/ccxray/main/docs/usage.png)
+
+### System Prompt 追蹤
+
+自動偵測版本變更，內建 diff 檢視器。精確掌握 Claude Code 更新時改了什麼 — 不再遺漏任何 prompt 變動。
+
+![System Prompt 追蹤](https://raw.githubusercontent.com/lis186/ccxray/main/docs/system-prompt.png)
+
+### 其他功能
+
+- **工作階段偵測** — 自動依 Claude Code session 分組，含專案/工作目錄擷取
+- **Token 記帳** — 每回合明細：input/output/cache-read/cache-create tokens、美元成本、上下文窗口使用率
+
+## 運作原理
+
+```
+Claude Code  ──►  ccxray (:5577)  ──►  api.anthropic.com
+                      │
+                      ▼
+                  ~/.ccxray/logs/ (JSON)
+                      │
+                      ▼
+                  儀表板（同一連接埠）
+```
+
+ccxray 是透明的 HTTP 代理。它將請求原封不動地轉發到 Anthropic，將請求與回應記錄為 JSON 檔案，並在同一連接埠提供網頁儀表板。不需要 API 金鑰 — 它直接傳遞 Claude Code 送出的內容。
+
+## 設定
+
+### CLI 參數
+
+| 參數 | 說明 |
+|---|---|
+| `--port <number>` | 代理 + 儀表板的連接埠（預設：5577）。使用後不共用 hub。 |
+| `--no-browser` | 不自動在瀏覽器中開啟儀表板 |
+
+### 環境變數
+
+| 變數 | 預設值 | 說明 |
+|---|---|---|
+| `PROXY_PORT` | `5577` | 代理 + 儀表板的連接埠（`--port` 會覆蓋此值） |
+| `BROWSER` | — | 設為 `none` 可停用自動開啟 |
+| `AUTH_TOKEN` | _（無）_ | 存取控制用 API 金鑰（未設定時停用） |
+| `CCXRAY_HOME` | `~/.ccxray` | 基底目錄，存放 hub lockfile、logs、hub.log |
+
+日誌儲存在 `~/.ccxray/logs/`，格式為 `{timestamp}_req.json` 和 `{timestamp}_res.json`。從 v1.0 升級？`./logs/` 中的日誌會在首次啟動時自動遷移。
+
+## Docker
+
+```bash
+docker build -t ccxray .
+docker run -p 5577:5577 ccxray
+```
+
+## 系統需求
+
+- Node.js 18+
+
+## 作者的其他作品
+
+- [SourceAtlas](https://sourceatlas.io/) — 任何 codebase 的導航地圖
+- [AskRoundtable](https://github.com/AskRoundtable/expert-skills) — 讓你的 AI 像 Munger、Feynman、Paul Graham 一樣思考
+- 在 X 上追蹤 [@lis186](https://x.com/lis186) 獲取最新動態
+
+## 授權
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kylindc/ccxray",
+  "version": "1.2.0",
+  "description": "X-ray vision for AI agent sessions — a transparent HTTP proxy and dashboard for Claude Code",
+  "main": "server/index.js",
+  "bin": {
+    "ccxray": "server/index.js"
+  },
+  "scripts": {
+    "start": "node server/index.js",
+    "dev": "node --watch-path=server --watch-path=public server/index.js",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "proxy",
+    "dashboard",
+    "anthropic",
+    "ai-agent",
+    "debugging",
+    "observability"
+  ],
+  "author": "KylinDC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KylinDC/ccxray.git"
+  },
+  "homepage": "https://github.com/KylinDC/ccxray",
+  "bugs": {
+    "url": "https://github.com/KylinDC/ccxray/issues"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@anthropic-ai/tokenizer": "^0.0.4",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@fission-ai/openspec": "^1.2.0",
+    "puppeteer": "^24.39.1"
+  }
+}

package/public/app.js

@@ -0,0 +1,99 @@
+// ── Global Config ────────────────────────────────────────────────────
+const DEFAULT_MAX_CTX = window.__PROXY_CONFIG__?.DEFAULT_CONTEXT || 200000;
+
+// ── Active Tab State ─────────────────────────────────────────────────
+let activeTab = 'dashboard';
+
+function switchTab(tab, forceDiff) {
+  if (activeTab === tab) return;
+  activeTab = tab;
+
+  // Update tab buttons
+  document.querySelectorAll('.topbar-tab').forEach(btn => {
+    btn.classList.toggle('active', btn.dataset.tab === tab);
+  });
+
+  // Show/hide content areas
+  document.getElementById('columns').style.display = tab === 'dashboard' ? '' : 'none';
+  const costPage = document.getElementById('cost-page');
+  const diffOverlay = document.getElementById('diff-overlay');
+  if (tab === 'usage') {
+    costPage.classList.add('open');
+    diffOverlay.classList.remove('open');
+    loadCostPage();
+  } else {
+    costPage.classList.remove('open');
+  }
+  if (tab === 'sysprompt') {
+    diffOverlay.classList.add('open');
+    costPage.classList.remove('open');
+    openSystemPromptPanel(forceDiff);
+  } else if (tab !== 'sysprompt') {
+    diffOverlay.classList.remove('open');
+  }
+
+  // Update Row 2 contextual content
+  document.getElementById('row2-dashboard').style.display = tab === 'dashboard' ? '' : 'none';
+  document.getElementById('row2-usage').style.display = tab === 'usage' ? '' : 'none';
+  document.getElementById('row2-sysprompt').style.display = tab === 'sysprompt' ? '' : 'none';
+
+  // Sync URL
+  syncViewParam();
+}
+
+function syncViewParam() {
+  // Use syncUrlFromState if available (miller-columns.js loaded), otherwise fallback
+  if (typeof syncUrlFromState === 'function') {
+    syncUrlFromState();
+  } else {
+    const params = new URLSearchParams(window.location.search);
+    if (activeTab === 'dashboard') params.delete('view');
+    else params.set('view', activeTab);
+    const qs = params.toString();
+    history.replaceState(null, '', window.location.pathname + (qs ? '?' + qs : ''));
+  }
+}
+
+// Capture view param early before deep-link resolution rewrites URL
+const _savedViewParam = new URLSearchParams(window.location.search).get('view');
+
+function restoreTabFromUrl() {
+  const view = _savedViewParam;
+  if (view === 'usage' || view === 'sysprompt') {
+    switchTab(view);
+  }
+}
+
+// ── Theme Toggle ─────────────────────────────────────────────────────
+function toggleTheme() {
+  const isLight = document.documentElement.getAttribute('data-theme') === 'light';
+  const next = isLight ? 'dark' : 'light';
+  document.documentElement.setAttribute('data-theme', next);
+  localStorage.setItem('theme', next);
+  updateThemeIcon();
+}
+function updateThemeIcon() {
+  const btn = document.getElementById('theme-toggle');
+  if (!btn) return;
+  btn.textContent = document.documentElement.getAttribute('data-theme') === 'light' ? '🌙' : '☀️';
+}
+updateThemeIcon();
+
+// ── Unified Escape + tab switching handler ──────────────────────────
+document.addEventListener('keydown', (e) => {
+  if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA' || e.target.isContentEditable) return;
+  // Don't intercept when miller-columns focused mode is active
+  if (typeof isFocusedMode !== 'undefined' && isFocusedMode) return;
+
+  // Escape → switch to dashboard
+  if (e.key === 'Escape' && activeTab !== 'dashboard') {
+    switchTab('dashboard');
+    e.preventDefault();
+    return;
+  }
+
+  // Tab switching: 1/2/3
+  if (e.key === '1') { switchTab('dashboard'); e.preventDefault(); return; }
+  if (e.key === '2') { switchTab('usage'); e.preventDefault(); return; }
+  if (e.key === '3') { switchTab('sysprompt'); e.preventDefault(); return; }
+});