miki-moni

v0.3.22

Published

6 days ago

Miki-Moni / 巫女 — weave multiple VSCode Claude Code panel sessions into one local dashboard, with optional encrypted relay to a phone client. See docs/naming.md.

Downloads

3,656

0High
0Medium
0Low

warmbed

Miki-Moni

English · 繁體中文 · 简体中文

巫女 (Miki the Monitor) — 一張 dashboard 收齊你所有 Claude Code session，可端對端加密從手機遙控。

這是什麼

你同時開了好幾個 Claude Code panel。其中一個跑完了，你 20 分鐘後才發現。你離開桌前想瞄一眼「跑完沒？」，但不想 VPN 進來。同事機器上有 context，你想唯讀看一下。

Miki-Moni 用 hooks 串接每一個 Claude Code panel，把它們聚合到本機 http://127.0.0.1:8765 一張 dashboard 上。要的話，加密 relay 讓手機或第二台電腦看到同一個畫面，並能推 prompt 回來。

聚合，不是取代。 Hooks 跟 claude 並存 — 你照原本方式起 session
同一個對話，跨任何裝置。 在電腦 A 起的話，搭車路上用手機繼續打，回家再用電腦 B 接著做 — 同一個 session UUID、同一份 transcript、同一份 context。不用把進度貼到新 prompt 裡
Session 撐得比視窗久。 任何 session 都能用 UUID 從任何 terminal 接回完整 context：miki claude -r <uuid>，原本的 panel 已關 / crash 都不影響
預設純本機，自己選才走遠端。 Daemon 只綁 127.0.0.1。手機端走端對端加密 envelope，relay 不持有任何 key

快速開始

npm install -g miki-moni
miki start

首次啟動跑 wizard：選語言、選 relay 模式（hosted / self-host / local-only）、印永久配對 QR：

每支要配對的裝置掃一次 QR 就好。Token 永久有效，除非你 miki pair --rotate。Dashboard 在 http://127.0.0.1:8765。

架構

┌─ 你的電腦 ─────────────────────────────────────────────────────────────┐
│                                                                        │
│  Claude Code（任何 panel）                                             │
│   │                                                                    │
│   │ PS hooks（SessionStart / Stop / UserPromptSubmit / PreToolUse /    │
│   │            PostToolUse）                                           │
│   │  ── POST /event ──▶                                                │
│   │                                                                    │
│   │   ┌──────────────────────────────────────────────────────────┐    │
│   │   │  miki-moni daemon（Node, 127.0.0.1:8765）                │    │
│   │   │  ─ session 儲存（better-sqlite3）                         │    │
│   │   │  ─ HTTP：/event /sessions /focus /send /wrap/*           │    │
│   │   │  ─ WS：  /ws（dashboard） /wrap（CLI） /ws_ext（ext）    │    │
│   │   │  ─ RelayClient（X25519 + NaCl secretbox）                │    │
│   │   └─────┬──────────────┬────────────────┬───────────┬───────┘    │
│   │         │ WS /ws       │ WS /ws_ext     │ WS /wrap  │ relay      │
│   ▼         ▼              ▼                ▼           │ envelope   │
│  hooks    瀏覽器 dashboard  VSCode helper   miki claude │            │
│           （Preact SPA）   extension       （wrap CLI）  │            │
│                                                          │            │
└──────────────────────────────────────────────────────────┼────────────┘
                                                           │
                                       ╭───────────────────▼──────────╮
                                       │ Cloudflare Worker relay      │
                                       │ （零知識：只路由不透明 blob，│
                                       │   不持有任何 key）            │
                                       ╰───────────────────┬──────────╯
                                                           │ E2E 加密
                                                           ▼
                                       ╭──────────────────────────────╮
                                       │ 手機 PWA / 第二台電腦         │
                                       │ Ed25519 keypair 存 IndexedDB │
                                       ╰──────────────────────────────╯

| 元件 | 角色 | |---|---| | PS hooks | Claude Code 在 session / tool 邊界 POST 到 /event，沒 wrap 的 panel 也會被 dashboard 看到 | | daemon | Node + express + ws + better-sqlite3。持有 session 狀態，路由四個 WS 平面 | | 瀏覽器 dashboard | Preact + Tailwind SPA 掛在 /。讀 /ws，POST /send 跟 /focus | | wrap CLI（miki claude） | 包一個 Claude Code session，讓 daemon 能推 prompt（/send）、切模型（/wrap/model）、用 UUID resume | | VSCode helper extension | 連 /ws_ext；接收 claude-vscode.focus 把 prompt 預填進當前 panel | | RelayClient | E2E 加密 envelope（每個 peer 一把 X25519 ECDH → NaCl secretbox），打到 Worker | | Cloudflare Worker | Stateless relay。在 daemon 跟配對 peer 之間路由密文。驗 daemon_id ‖ utc_minute 的 Ed25519 簽章 | | 手機 PWA | Web client 從 Pages 出。掃 QR，IndexedDB 存 Ed25519 簽章 key，跟 relay 溝通 |

完整協定見 docs/protocols/relay-protocol.md。

功能

Dashboard

多 session 網格 — 本機上每一個 Claude Code panel，不管哪個 VSCode 視窗或 terminal 起的都收進來
狀態計數器可篩選 — 點 5 進行中 把網格收斂到那個狀態，再點取消
New CLI popover — 在任意資料夾起一個全新的 miki claude --fresh；最近用過的 cwd 用原生下拉選單記著，跳新專案一鍵搞定
即時 transcript 用聊天泡泡版面（user 右、assistant/system/tool 左）。可切 tool call 顯示，捲動門檻 10 / 50 / 200 / 全部
WS 燈號 — 綠 = 即時接收中，黃 = 重連中

Session 控制

Model chip — 點開即時切模型：default / Sonnet / Opus / Haiku / 自訂 id。透過 POST /wrap/model 廣播到每張 dashboard
Mode chip 帶顏色 — acceptEdits 藍、bypass 紅、ask 灰。整個 session lifetime 鎖定
Open CLI — 開 wt.exe 跑 miki claude -r <session-uuid>，從 terminal 接管 session 帶完整 context。原本的 panel 已關或 crash 都不影響
送出輸入框 — 多行輸入自動長高。Enter 或 Ctrl/⌘+Enter 送出（依你的設定）。支援貼上、拖曳、按鈕選圖片附件

效能監控

TTFT 折線圖 — 每個 miki claude wrap session 的 Time-to-First-Token（ms），追蹤 Claude 開始回覆的速度
TPS 折線圖 — streaming 期間每秒字元數，一眼看出模型或網路劣化
Fleet 平均線 — 虛線顯示 48 小時滾動平均，讓單次數據有參照基準
時間窗選擇 — 1h / 6h / 24h / 48h 滾動視窗，無需重新載入即可切換
手機同等 — 手機端點擊 ⚡ Monit 按鈕，透過加密 relay proxy 查看同樣的圖表

注意： TTFT / TPS 資料只在 miki claude（wrap 模式）起的 session 中收集。純 hook 模式的 session 會出現在 dashboard 上，但不產生效能指標。

手機

手機 dashboard — 一樣的網格，單欄、行動裝置友善的點擊區
聊天泡泡 transcript 跟桌面同步，適配手機 viewport
右滑關閉 session modal — document 層級手勢 + translateX 預覽
Composer 帶圖片上傳鈕（手機 file picker）、textarea 自動長高、修好 iOS focus-zoom 跟鍵盤縮放
Transcript 控制可折疊（show-tool / limit / load-all / reload）藏在一個 sliders popover 裡

部署模式

| | Hosted | Self-host | Local-only | |---|---|---|---| | 設定時間 | 0 秒 | 約 5 分鐘 wizard | 0 秒 | | 需要 CF 帳號 | 否 | 是 | 否 | | 手機可連 | 是 | 是 | 否 | | 信任作者基礎設施 | 是 | 否 | N/A | | 流量上限 | 作者 CF 免費層（約 10 萬 req/天） | 你自己 CF 免費層 | N/A | | 之後可切換 | miki setup | miki setup | miki setup |

預設是 Hosted，指向 relay.f1telemetrystationpro.org。選 Self-host 時 wizard 會把 Worker + Pages 部署到你的 CF 帳號。

資安

Daemon 只綁 127.0.0.1 — 公網永遠戳不到。手機端走端對端加密：配對時 X25519 ECDH，每個 envelope NaCl secretbox。加密用的私鑰永遠不離開 daemon 跟配對好的手機。

Daemon 信任所有以你身分跑的程序去呼叫 /event、/send、/focus、/ws_ext。這讓 hooks 跟 helper extension 不用帶 token，但代價是：任何以你身分跑的程序都能跟 daemon 講話。~/.miki-moni/ 請當 ~/.ssh/ 那樣保護。

手機能 / 不能做什麼

| 手機可以 | 手機不可以 | |---|---| | 看即時 session 狀態 + transcript | 在你電腦上跑任意 shell 指令 | | 推 prompt（pre-fill 進 VSCode、直送 wrap CLI） | 不經你 VSCode 按鍵就自動送出 prompt | | Focus 已存在的 panel | 繞過 Claude Code 每個工具的權限提示 |

Relay 看得到 / 看不到什麼

daemon 跟手機之間全程走 WSS（到 CF edge 為止都是 TLS）。Worker 在 edge 解 TLS 之後看到的：

| Relay (Worker) 看得到 | Relay 看不到 | |---|---| | Daemon 的公鑰（Ed25519 + X25519） | 訊息內容（每個 envelope 都是 NaCl secretbox 在兩端加密） | | Pairing token（配對那一刻，用完即丟） | 私鑰（X25519 / Ed25519 留在 daemon 跟手機 — 手機側存在 IndexedDB） | | 手機公鑰 + reconnect 簽章 | 你打了什麼、Claude 回了什麼、transcript、tool I/O | | Metadata：誰跟誰配對、連線時間、envelope 大小、peer ID | |

Hosted relay 模式下這些 metadata 維運者（作者 + Cloudflare）看得到。Self-host 就避開這層 — 維運者變你自己。

Relay 唯一現實的攻擊路徑：PWA bundle swap

手機端是從 Cloudflare Pages 出的 PWA。被攻陷的 relay 維運者可以推一份惡意 bundle，在首次載入時把手機 IndexedDB 裡的 X25519 私鑰偷走。端對端加密的安全性最後還是取決於兩端跑的程式碼。緩解：

Self-host — Worker 跟 Pages bundle 都你掌控
Pin bundle — 在已知乾淨的日子配對，然後關掉 PWA 自動更新（看 browser）
看 source — Pages bundle 可以從這個 repo 對應 daemon 版本的 tag 重現

風險表、硬化選項、完整 hooks / extension 信賴分析見 docs/security/。

CLI 指令

| 指令 | 用途 | |---|---| | miki start | 跑 daemon；首次啟動會跳 wizard | | miki setup | 重跑 wizard（換語言、切 relay 模式） | | miki pair | 印永久 QR + 已配對手機清單 | | miki pair --rotate | 換新 token（舊 QR 失效；已配對手機照常工作） | | miki claude [...args] | 包一個 Claude Code session，daemon 沒跑會自動起 | | miki install-hooks | 把 Claude Code hooks merge 進 ~/.claude/settings.json |

完整清單見 miki --help。詳細 log：MIKI_LOG_LEVEL=info miki start，完整 trace 永遠在 ~/.miki-moni/miki-moni.log。

Self-host

Wizard 會做完全程；要手動部署：

cd worker
wrangler login
wrangler deploy --config wrangler-selfhost.toml --name my-relay
wrangler pages project create my-phone --production-branch=main
wrangler pages deploy ../dist/web-phone --project-name my-phone --branch=main

然後把 ~/.miki-moni/config.json 指到你的 endpoint：

{
  "remote": {
    "worker_url": "wss://my-relay.<你的 cf 帳號>.workers.dev",
    "phone_pwa_url": "https://my-phone.pages.dev/"
  }
}

開發

git clone https://github.com/WarmBed/Miki-Moni
cd Miki-Moni
pnpm install
pnpm dev          # tsx watch src/index.ts
pnpm test         # daemon + worker tests
pnpm typecheck

Source tree：src/ daemon · web/ dashboard SPA · web-phone/ 手機 bootstrap · worker/ Cloudflare Worker · extension/ VSCode helper · hooks/ PS hook scripts · bin/miki.js CLI 入口。

Branch：main 出 release（目前 v0.3.18），dev 跑開發、每個改動 bump package.json。

License

MIT — 見 LICENSE。

Credits

用 Anthropic Claude 透過 Claude Code 寫出來的。