Kanna 是一個為「Claude Code」與「Codex」CLI 提供優雅網頁介面的開源專案。作者將其比喻為這兩個工具「結婚生的寶寶，但 UI/UX 設計更好」，強調自身的介面品質優勢。

核心功能

Kanna 提供多個關鍵特性以改善開發體驗：

• 一鍵在 Claude 與 Codex（OpenAI）之間切換，支援各提供者的模型選擇、推理努力控制和 Codex 快速模式
• 專案優先的側邊欄設計，將聊天記錄按專案分組，並以即時狀態指示器（閒置、執行中、等待、失敗）標示進度
• 拖曳排序專案群組的功能，順序會被永久保存
• 自動探索 Claude 與 Codex 的本地歷史記錄以發現專案
• 豐富的對話文本渲染，包括已初始化的工具呼叫、可摺疊的工具群組、計畫模式對話框和互動式提示
• 透過 Claude Haiku 進行輕量結構化查詢（如標題生成），搭配自動 Codex 降級方案
• 計畫模式讓使用者在執行前檢視並批准 Agent 的計畫
• 刷新時不遺失的本地歷史記錄，由 JSONL 事件日誌和壓縮快照支援
• 背景自動產生聊天標題
• 完整上下文保留的 Agent 工作階段恢復功能
• WebSocket 驅動的即時訂閱模型與反應式狀態廣播

技術架構

系統採用分層設計：前端為 React + Zustand 狀態管理，透過 WebSocket 與 Bun 伺服器通訊；後端包含 WSRouter（訊息路由與訂閱）、AgentCoordinator（多提供者回合管理）、ProviderCatalog（提供者/模型/努力度標準化）、QuickResponseAdapter（結構化查詢含降級）、EventStore（JSONL 持久化與快照壓縮）和 ReadModels（衍生檢視）；最終與本地 Claude Agent SDK 或 Codex 應用伺服器通訊。

核心設計模式採用事件溯源管理所有狀態變化，CQRS 分離讀寫路徑（事件日誌對應快照），反應式廣播讓訂閱者在每次狀態改變時收到新快照，支援多提供者 Agent 協調與工具門控以實現使用者批准流程，並提供提供者無關的對話文本初始化以統一渲染。

安裝與使用

Kanna 透過 Bun 套件管理器安裝：bun install -g kanna-code（Bun 1.3.5 以上）。執行 kanna 命令後即在瀏覽器開啟 localhost:3210。支援 --port 自訂連接埠和 --no-open 跳過自動開啟瀏覽器。開發時可分別執行 bun run dev:client（Vite 開發伺服器，連接埠 5174）和 bun run dev:server（Bun 後端，連接埠 3211）。

本地資料存儲

所有狀態儲存於 ~/.kanna/data/，包含 projects.jsonl（專案事件）、chats.jsonl（聊天建立/重新命名/刪除事件）、messages.jsonl（對話訊息）、turns.jsonl（Agent 回合事件）和 snapshot.json（壓縮快照供快速啟動）。事件日誌採用追加式 JSONL 格式，啟動時 Kanna 會重放最後快照後的日誌尾部，當日誌超過 2 MB 時進行壓縮。

環境要求

需要 Bun v1.3.5 以上、運作中的 Claude Code 環境，以及可選的 Codex CLI。內嵌終端支援使用 Bun 原生 PTY API，目前僅支援 macOS/Linux。