miki-moni 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WarmBed / Miki-Moni contributors
+
+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,283 @@
+# Miki-Moni
+
+**[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md)**
+
+> 巫女 (Miki the Monitor) — watches your Claude Code sessions and pings you when one needs attention.
+
+Aggregate the state of every VSCode Claude Code panel into a single local dashboard. Connect to it from your phone or another laptop through an end-to-end encrypted relay.
+
+<p align="center">
+  <img src="docs/images/dashboard-desktop.png" width="800" alt="Desktop dashboard — session cards with live transcript">
+  <br />
+  <em>Desktop dashboard at <code>http://127.0.0.1:8765</code></em>
+</p>
+
+<table>
+<tr>
+<td align="center" width="33%">
+  <img src="docs/images/dashboard-phone.png" width="280" alt="Phone dashboard — same content, single-column mobile layout">
+  <br /><em>Phone dashboard (mobile viewport)</em>
+</td>
+<td align="center" width="33%">
+  <img src="docs/images/phone-pair-screen.png" width="280" alt="Phone pairing screen — QR scan + 16-char code">
+  <br /><em>Phone pairing screen — scan QR or type code</em>
+</td>
+<td align="center" width="33%">
+  <img src="docs/images/cli-banner.png" width="280" alt="CLI banner — miki start prints QR + URL + 16-char code on startup">
+  <br /><em><code>miki start</code> prints QR + URL + code on every startup</em>
+</td>
+</tr>
+</table>
+
+---
+
+## Why
+
+- Three Claude Code panels open across two VSCode windows. One finishes; you don't notice for 20 minutes.
+- You walk away from your desk; you want to peek at "did it finish yet?" from your phone without VPN-ing in.
+- A teammate's machine has the project loaded; you want a read-only view from yours.
+
+Miki-Moni gives you **one dashboard** that aggregates every Claude Code session (across windows, projects, machines) and lets you respond from anywhere.
+
+**Resume any session from any terminal.** Started a session in VSCode and your editor crashed? Closed the wrong window? Switched to a different terminal? Every session — VSCode-spawned or CLI-spawned — is resumable with its **full context** by running `miki claude -r <session-uuid>`. The dashboard exposes a one-click *Open CLI* button on each session card; from your phone, just keep prompting the same session through the relay. No more "I lost my Claude context" — the session UUID is the durable handle, not the window that started it.
+
+## Install
+
+```bash
+npm install -g miki-moni
+miki start
+```
+
+Or from source (for contributing / unreleased changes):
+
+```bash
+git clone https://github.com/WarmBed/Miki-Moni
+cd Miki-Moni
+pnpm install
+pnpm build:all
+pnpm link --global       # makes `miki` available on PATH
+miki start
+```
+
+On first run, a setup wizard asks:
+
+1. **Language** — English / 繁體中文 / 简体中文
+2. **Relay mode** — pick one:
+   - **Hosted** (default) — uses the author's free `relay.f1telemetrystationpro.org`. Zero setup.
+   - **Self-host** — auto-deploys a Cloudflare Worker + Pages site to *your* CF account (needs `wrangler`).
+   - **Local-only** — no phone access; dashboard at `127.0.0.1:8765` only.
+
+Then it prints a permanent pairing QR + 16-char code:
+
+```
+📱 Phone pairing — scan QR, open URL, or type the 16-char code:
+
+  [QR code]
+
+   URL:    https://miki-moni.pages.dev/#t=XXXX...&r=wss://...
+   Code:   XXXX-XXXX-XXXX-XXXX
+   Local:  http://127.0.0.1:8765
+   (QR / URL / Code are permanent — rotate with `miki pair --rotate`)
+```
+
+That QR works permanently — scan once on each device you want to pair. Rotate when leaked.
+
+## Three deployment modes
+
+|  | Hosted | Self-host | Local-only |
+|---|---|---|---|
+| **Setup** | 0 sec | ~5 min wizard | 0 sec |
+| **Needs CF account** | No | Yes | No |
+| **Phone access** | Yes | Yes | No |
+| **Trust author's infra** | Yes ([§ Security](#security)) | No | N/A |
+| **Bandwidth limits** | Author's CF free tier (100k req/day) | Your CF free tier | N/A |
+| **Rotate later** | `miki setup` | `miki setup` | `miki setup` |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                                                                          │
+│  ╭─ Your machine ────────────────────────────────────────────────────╮   │
+│  │                                                                   │   │
+│  │  miki-moni daemon (Node, 127.0.0.1:8765)                          │   │
+│  │    POST /event   GET /sessions   POST /focus /send  WS /ws        │   │
+│  │                                                                   │   │
+│  │     ▲                       ▲                            ▲       │   │
+│  │ PS hooks            web dashboard               RelayClient       │   │
+│  │ (~/.claude/         (browser at 127.0.0.1)                        │   │
+│  │  settings.json)                                                   │   │
+│  ╰────────────────────────────────────────────────────┬──────────────╯   │
+│                                                       │ E2E encrypted    │
+│                                                       │ envelope         │
+│                                          ╭────────────▼─────────────╮   │
+│                                          │ Cloudflare Worker relay  │   │
+│                                          │ (zero-knowledge: routes  │   │
+│                                          │  encrypted blobs only)   │   │
+│                                          ╰────────────┬─────────────╯   │
+│                                                       │ E2E encrypted    │
+│                                                       ▼                  │
+│                                          ╭──────────────────────────╮   │
+│                                          │ Phone / 2nd laptop /     │   │
+│                                          │ tablet (web PWA)         │   │
+│                                          │  · scans QR → auto-pair  │   │
+│                                          │  · sees same dashboard   │   │
+│                                          ╰──────────────────────────╯   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+**Encryption**: X25519 ECDH at pair time → per-peer shared secret → NaCl `secretbox` on every envelope. The relay never holds keys; only the daemon and the paired phone can read content.
+
+**Auth**: each phone holds an Ed25519 signing keypair (in IndexedDB). On reconnect, it signs `daemon_id || utc_minute` — relay verifies before routing. Revoke per-device with `miki pair --revoke <peer_id>`.
+
+## Dashboard features
+
+Top bar:
+
+| | What it does |
+|---|---|
+| **Counters** (`5 active · 0 idle · 56 total`) | Click to filter the grid to that status (click again to clear) |
+| **➕ New CLI** | Open a new wrapped Claude session in a fresh folder (`miki claude --fresh`) |
+| **⚙️ Settings** | Send key (Enter vs Ctrl/⌘+Enter), theme (light/dark), language (en / 繁中 / 简中) |
+| **WS status dot** | Green = receiving live updates · amber = reconnecting |
+
+Session cards:
+
+| Element | What it does |
+|---|---|
+| **Project name + cwd** | Header — click to expand the card / view full transcript |
+| **🖥️ VSCode / 📟 CLI badge** | Toggles how *send* / *focus* dispatches. **VSCode**: prompt fills the VSCode panel via `vscode://anthropic.claude-code/open?session=…`. **CLI**: prompt goes through the wrap CLI's WebSocket directly. |
+| **Permission badge** (`✏️ auto edit`, `🚀 bypass`) | Only on wrapped CLI sessions started with `--permission-mode acceptEdits` / `--bypass-permissions`. Locked for the session lifetime. |
+| **Transcript view** | Live-rendered Claude turns. Toggle tool calls. Limit slider (10 / 50 / 200 / all). |
+| **Send composer** | Multi-line prompt input. Enter or Ctrl/⌘+Enter to send (per your settings choice). Supports image attachment via paste/drop. |
+| **Open CLI button** ⭐ | **Take over the session from a CLI, with full context.** Spawns `wt.exe` (Windows Terminal) running `miki claude -r <session-uuid>` — Claude resumes from the exact turn the VSCode panel was on. Works regardless of where the session was originally started; the panel can be closed, crashed, or on a different window. Pair with the phone dashboard and you keep prompting the same session from anywhere. |
+| **Focus button** | `POST /focus` — raises the matching VSCode window (or new CLI tab) to foreground. |
+
+## CLI reference
+
+| Command | What it does |
+|---|---|
+| `miki start` | Run daemon + print pairing banner. First run launches the setup wizard. |
+| `miki setup` | Re-run the wizard (change language, switch relay mode, etc.) |
+| `miki pair` | Show the current permanent QR + paired-phones list. |
+| `miki pair --rotate` | Generate a new pair token (invalidates the old QR; paired phones keep working). |
+| `miki pair --list` | List paired phones with their IDs + paired timestamps. |
+| `miki pair --revoke <peer_id>` | Remove a phone from local config AND tell the relay to drop it. |
+| `miki pair --new` | One-shot ephemeral token (10 min TTL) — legacy / debugging. |
+| `miki claude [...args]` | Wrap a Claude Code session and auto-spawn the daemon if down. |
+| `miki install-hooks` | Merge Claude Code hooks into `~/.claude/settings.json` so non-wrapped panels show up too. |
+
+Verbose daemon logs: `MIKI_LOG_LEVEL=info miki start`. Full trace always in `~/.miki-moni/miki-moni.log`.
+
+## Security
+
+### What the phone can and can't do
+
+Designed conservatively to keep the threat model small:
+
+| The phone **can** | The phone **cannot** |
+|---|---|
+| See live session state + transcript | Run arbitrary shell commands on your machine |
+| Pre-fill a prompt into a VSCode panel (`/focus`) | Auto-submit a prompt without your VSCode keystroke (Anthropic's design) |
+| Push a prompt through the wrap CLI WebSocket for sessions started with `miki claude` | Spawn new processes or read files outside the session transcript |
+| Trigger a focus on an existing panel | Bypass Claude Code's tool-permission prompts (those still gate every tool call) |
+
+### Trust boundaries
+
+The daemon binds **`127.0.0.1` only** — nothing on the public network can reach it, ever. Remote access flows through the encrypted relay, not the local HTTP port.
+
+The daemon trusts any process running on the same machine to call `/event`, `/send`, `/focus`, and connect to `/ws_ext`. This is intentional (so Claude Code hooks and the VSCode helper extension don't need a token) but means: **anything that runs as your user can talk to the daemon**. See [`docs/security/hooks-trust-model.md`](docs/security/hooks-trust-model.md) and [`docs/security/extension-ws-trust-model.md`](docs/security/extension-ws-trust-model.md) for the full local-trust analysis and hardening options.
+
+### Risk table
+
+Ordered by realism:
+
+| Risk | Mitigation |
+|---|---|
+| 🔴 **Pairing QR leaks** (screenshot in chat, photo of screen, posted publicly) | Permanent QR means anyone with it can pair. Treat the QR like an SSH key. Rotate immediately if leaked: `miki pair --rotate`. |
+| 🟡 **Paired phone stolen** | Phone holds an Ed25519 signing key that grants relay access. Revoke from the daemon: `miki pair --revoke <peer_id>`. |
+| 🟡 **Local machine compromised** | The daemon trusts loopback. Any malicious process running as your user can read sessions and intercept prompts via `/ws_ext`. Treat `~/.miki-moni/` (private keys, paired-phone records) like `~/.ssh/`. |
+| 🟢 Brute-force pair token | 16 Crockford base32 chars ≈ 80 bits of entropy. Computationally infeasible. |
+| 🟢 Relay sees content | Zero-knowledge by design — relay only routes opaque ciphertext, never holds shared secrets. |
+| 🟡 You trust the hosted relay operator | Self-host avoids this entirely. The author can see metadata (peer IDs, timing, sizes) and theoretically swap the PWA bundle. Source is open; verify or self-host. |
+| 🟢 DDoS on hosted relay | Cloudflare rate-limit binding caps at 30 req/60s per IP. Worst case: your daily quota burns. |
+
+## Self-host (manual)
+
+The `miki setup` wizard automates this end-to-end, but if you prefer manual:
+
+```bash
+# In a cloned cc-hub source tree:
+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
+```
+
+Then edit `~/.miki-moni/config.json`:
+
+```json
+{
+  "remote": {
+    "worker_url": "wss://my-relay.<your-cf-username>.workers.dev",
+    "phone_pwa_url": "https://my-phone.pages.dev/"
+  }
+}
+```
+
+`miki start` will pick up the new endpoints on next run.
+
+## Development
+
+```bash
+git clone https://github.com/WarmBed/Miki-Moni
+cd Miki-Moni
+pnpm install
+pnpm typecheck
+pnpm test         # daemon + worker test suites
+pnpm dev          # tsx watch src/index.ts
+```
+
+Source tree:
+
+| Path | Purpose |
+|---|---|
+| `src/` | Node daemon (express + ws + better-sqlite3) — hooks, pairing, RelayClient |
+| `web/` | Desktop / phone full dashboard (Preact + Tailwind + Vite) |
+| `web-phone/` | Phone bootstrap shell (QR scanner + tunnel setup) — mounts web/ |
+| `worker/` | Cloudflare Worker relay (DaemonRelay + PairingCoordinator DOs) |
+| `extension/` | VSCode helper extension — handles `claude-vscode.send` |
+| `hooks/` | Claude Code hook scripts (PowerShell) — POST events to daemon |
+| `bin/miki.mjs` | npm-published CLI entry |
+
+## Branches
+
+- `main` — versioned releases (current: v0.0.0)
+- `dev` — active development; every change gets a `package.json` version bump
+
+## Related projects
+
+**[Happy](https://happy.engineering)** (`slopus/happy-cli`, MIT) solves an overlapping itch — controlling Claude Code from your phone — from a different angle. Both can coexist on the same machine.
+
+|  | Miki-Moni | Happy |
+|---|---|---|
+| Primary entry point | VSCode panel — hooks pull every panel into a dashboard | Terminal wrapper that replaces `claude` |
+| Relay | Cloudflare Worker; self-host in ~5 min on your own CF account | Author-hosted socket.io server (`api.cluster-fluster.com`) |
+| Phone client | Web PWA — scan QR, no app install | Native iOS / Android apps |
+| Supported agents | Claude Code | Claude Code, Codex, Gemini, generic ACP |
+| Voice input | — | Yes |
+| Multi-session visual dashboard | Yes — aggregates across windows | Sessions managed independently |
+| Replaces `claude`? | No — hooks in alongside | Yes — spawns `claude` itself |
+| Remote spawn (start a session away from your desk) | — | Yes (`happy daemon`) |
+| End-to-end encrypted relay | Yes (X25519 + NaCl secretbox) | Yes (X25519 + NaCl secretbox + AES-GCM) |
+
+Use Happy if you want a polished mobile-first experience across multiple AI agents and don't mind a SaaS relay. Use Miki-Moni if you live in VSCode, want a single dashboard for many parallel panels, or want to self-host the relay on your own CF account in minutes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Credits
+
+Built with [Anthropic Claude](https://claude.ai/code) via [Claude Code](https://github.com/anthropics/claude-code).

package/README.zh-CN.md

@@ -0,0 +1,275 @@
+# Miki-Moni
+
+**[English](README.md) · [繁體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md)**
+
+> 巫女 (Miki the Monitor) — 看着你所有 Claude Code session，要回应的时候叫你。
+
+把散落在各个 VSCode 窗口的 Claude Code panel 收进一张本机仪表板，手机或第二台笔电可以通过端对端加密 relay 连进来。
+
+<p align="center">
+  <img src="docs/images/dashboard-desktop.png" width="800" alt="桌面 dashboard — session 卡片含实时 transcript">
+  <br />
+  <em>本机 dashboard：<code>http://127.0.0.1:8765</code></em>
+</p>
+
+<table>
+<tr>
+<td align="center" width="33%">
+  <img src="docs/images/dashboard-phone.png" width="280" alt="手机 dashboard — 同样内容、单列移动版">
+  <br /><em>手机 dashboard（移动设备）</em>
+</td>
+<td align="center" width="33%">
+  <img src="docs/images/phone-pair-screen.png" width="280" alt="手机配对画面 — 扫 QR + 16 码输入">
+  <br /><em>手机配对画面 — 扫 QR 或输入 16 码</em>
+</td>
+<td align="center" width="33%">
+  <img src="docs/images/cli-banner.png" width="280" alt="CLI banner — miki start 启动时打印 QR + URL + 16 码">
+  <br /><em><code>miki start</code> 每次启动打印 QR + URL + 16 码</em>
+</td>
+</tr>
+</table>
+
+---
+
+## 为什么
+
+- 两个 VSCode 窗口开了三个 Claude Code panel，其中一个跑完了，你 20 分钟后才发现
+- 离开桌前想瞥一眼"跑完没？"但不想 VPN 进来
+- 同事机器有项目，你想只读看一眼
+
+Miki-Moni 给你**一张 dashboard** 收齐所有 Claude session（跨窗口、跨项目、跨机器），任何地方都能响应。
+
+**任何 session 都能从任何 terminal 接管继续做。** VSCode 起的、CLI 起的都一样，editor 崩了、窗口误关、想换个 terminal 继续做 — 一句 `miki claude -r <session-uuid>` 把**完整上下文**接回来。dashboard 每张 session 卡都有一键"Open CLI"按钮；手机端就直接通过 relay 对同一个 session 继续打字。再也不会"Claude 上下文掉了" — session UUID 是耐用的把手，不是起它的那个窗口。
+
+## 安装
+
+```bash
+npm install -g miki-moni
+miki start
+```
+
+或从 source 装（要贡献 / 用未 release 的改动）：
+
+```bash
+git clone https://github.com/WarmBed/Miki-Moni
+cd Miki-Moni
+pnpm install
+pnpm build:all
+pnpm link --global       # 把 `miki` 加到 PATH
+miki start
+```
+
+首次启动会跳设置 wizard：
+
+1. **语言** — English / 繁體中文 / 简体中文
+2. **Relay 模式** — 三选一：
+   - **Hosted**（默认）— 用作者免费 `relay.f1telemetrystationpro.org`，零设置
+   - **Self-host** — 自动部署 Cloudflare Worker + Pages 到你 CF 账号（需要 `wrangler`）
+   - **Local-only** — 不连手机，只用本机 `127.0.0.1:8765`
+
+然后打印永久配对 QR + 16 码：
+
+```
+📱 Phone pairing — scan QR, open URL, or type the 16-char code:
+
+  [QR]
+
+   URL:    https://miki-moni.pages.dev/#t=XXXX...&r=wss://...
+   Code:   XXXX-XXXX-XXXX-XXXX
+   Local:  http://127.0.0.1:8765
+   (QR / URL / Code 永久有效 — `miki pair --rotate` 可换)
+```
+
+那个 QR 永久有效，每台要配对的设备扫一次就好。泄漏时 rotate 即可。
+
+## 三种部署模式
+
+|  | Hosted | Self-host | Local-only |
+|---|---|---|---|
+| **设置时间** | 0 秒 | 约 5 分钟 wizard | 0 秒 |
+| **需要 CF 账号** | 否 | 是 | 否 |
+| **手机可用** | 是 | 是 | 否 |
+| **信任作者基础设施** | 是（[§ 安全](#安全)） | 否 | N/A |
+| **流量限制** | 作者 CF 免费层（10 万 req/天） | 你自己 CF 免费层 | N/A |
+| **随时切换** | `miki setup` | `miki setup` | `miki setup` |
+
+## 架构
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  你的电脑                                                                  │
+│  ╭─────────────────────────────────────────────────────────────╮        │
+│  │  miki-moni daemon (Node, 127.0.0.1:8765)                    │        │
+│  │    POST /event   GET /sessions   POST /focus /send  WS /ws  │        │
+│  │     ▲                       ▲                       ▲       │        │
+│  │ PS hooks            浏览器 dashboard       RelayClient       │        │
+│  ╰────────────────────────────────────────────┬────────────────╯        │
+│                                                │ E2E 加密 envelope        │
+│                                  ╭─────────────▼────────────╮            │
+│                                  │ Cloudflare Worker relay  │            │
+│                                  │ (零知识：只路由密文)       │             │
+│                                  ╰─────────────┬────────────╯            │
+│                                                ▼                         │
+│                                  ╭──────────────────────────╮            │
+│                                  │ 手机 / 第二台笔电 / 平板    │            │
+│                                  │  · 扫 QR → 自动配对        │            │
+│                                  │  · 看到一样的 dashboard    │            │
+│                                  ╰──────────────────────────╯            │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+**加密**：配对时 X25519 ECDH → per-peer shared secret → 每个 envelope 用 NaCl `secretbox`。Relay 没有 key；只有 daemon 跟配对好的手机能解内容。
+
+**认证**：每台手机握一对 Ed25519 签名 keypair（IndexedDB）。重连时签 `daemon_id || utc_minute`，relay 验签才放行。`miki pair --revoke <peer_id>` 删单个设备。
+
+## Dashboard 功能
+
+上方工具栏：
+
+| | 作用 |
+|---|---|
+| **计数器**（`5 进行中 · 0 闲置 · 56 总览`） | 点击筛选只看那个状态，再点取消 |
+| **➕ 新增 CLI** | 在指定文件夹开新 wrapped session（`miki claude --fresh`） |
+| **⚙️ 设置** | 发送键（Enter vs Ctrl/⌘+Enter）、主题（亮/暗）、语言 |
+| **WS 灯号** | 绿＝实时更新中 · 黄＝重连中 |
+
+Session 卡片：
+
+| 元素 | 作用 |
+|---|---|
+| **项目名 + cwd** | 卡片标题 — 点开查看完整 transcript |
+| **🖥️ VSCode / 📟 CLI 切换** | 决定 *发送 / focus* 走哪边。**VSCode**：用 `vscode://anthropic.claude-code/open?session=…` 把 prompt 预填 VSCode panel。**CLI**：直接打 wrap CLI 的 WebSocket。 |
+| **权限 badge**（`✏️ auto edit` / `🚀 bypass`） | 只有跑 `miki claude --permission-mode acceptEdits` / `--bypass-permissions` 的 wrap CLI session 才显示，整个 session lifetime 锁定不能改 |
+| **Transcript view** | 实时渲染 Claude 对话。可开关 tool call。滚动门槛 10 / 50 / 200 / 全部。 |
+| **发送输入框** | 多行 prompt。Enter 或 Ctrl/⌘+Enter 发送（按你的设置）。支持粘贴/拖图片。 |
+| **开 CLI 按钮** ⭐ | **从 CLI 接管这个 session，完整上下文都在。** 开 `wt.exe`（Windows Terminal）跑 `miki claude -r <session-uuid>` — Claude 从 VSCode panel 停的那回合接着做。原本从哪起的都不重要；panel 可以已关、已 crash、在另一个窗口。配上手机 dashboard，同一个 session 你在哪都能继续打 |
+| **Focus 按钮** | `POST /focus` — 把对应 VSCode 窗口（或 CLI tab）提到最前 |
+
+## CLI 命令
+
+| 命令 | 用途 |
+|---|---|
+| `miki start` | 跑 daemon + 打印配对 banner。第一次跑会跳 wizard |
+| `miki setup` | 重跑 wizard（换语言、切 relay 模式等） |
+| `miki pair` | 打印当前永久 QR + 已配对手机清单 |
+| `miki pair --rotate` | 换新 token（旧 QR 失效；已配对手机照常工作） |
+| `miki pair --list` | 列已配对手机 |
+| `miki pair --revoke <peer_id>` | 删除某台手机（本机 config + relay 都清） |
+| `miki pair --new` | 一次性 token（10 分钟 TTL）— 旧机制 / debug 用 |
+| `miki claude [...args]` | 包一个 Claude session，daemon 没跑会自动起 |
+| `miki install-hooks` | 把 Claude Code hooks 装进 `~/.claude/settings.json`，没 wrap 的 panel 也会出现在 dashboard |
+
+启动时看详细 log：`MIKI_LOG_LEVEL=info miki start`。完整 trace 永远在 `~/.miki-moni/miki-moni.log`。
+
+## 安全
+
+### 手机能做什么、不能做什么
+
+刻意把手机端能力压到最小，威胁模型才好顾：
+
+| 手机**可以** | 手机**不可以** |
+|---|---|
+| 看实时 session 状态 + transcript | 在你电脑上跑任意 shell 命令 |
+| Pre-fill prompt 进 VSCode panel（`/focus`） | 不经你 VSCode 按键自动送出 prompt（Anthropic 设计） |
+| 对 `miki claude` 起的 session 从 wrap CLI WebSocket 推 prompt | 开新 process 或读 session 外的文件 |
+| Focus 已存在的 panel | 绕过 Claude Code 工具权限提示（每个工具调用一样会问你） |
+
+### 信赖边界
+
+daemon **只绑 `127.0.0.1`** — 公网永远戳不到。远端走加密 relay，不走本机 HTTP port。
+
+daemon 信任**所有跟你同账号**的本机程序去打 `/event`、`/send`、`/focus`、`/ws_ext`。这是故意的（Claude Code hooks 跟 VSCode helper extension 才不用带 token），但代价是：**任何以你身份跑的程序都能跟 daemon 讲话**。完整本机信赖分析跟硬化选项见 [`docs/security/hooks-trust-model.md`](docs/security/hooks-trust-model.md) 跟 [`docs/security/extension-ws-trust-model.md`](docs/security/extension-ws-trust-model.md)。
+
+### 风险表
+
+按可能性排序：
+
+| 风险 | 缓解 |
+|---|---|
+| 🔴 **配对 QR 泄漏**（截图、贴到聊天室、被路人拍） | 永久 QR = 任何人扫到都能 pair。把 QR 当 SSH key 看待。泄漏立刻 rotate：`miki pair --rotate` |
+| 🟡 **配对手机被偷** | 手机握 Ed25519 签名 key 才能连 relay。从 daemon 删：`miki pair --revoke <peer_id>` |
+| 🟡 **本机被入侵** | daemon 信任 loopback。任何以你身份跑的恶意程序可读 session、可从 `/ws_ext` 拦 prompt。`~/.miki-moni/`（私钥、配对记录）请当 `~/.ssh/` 那样保护 |
+| 🟢 暴力猜 token | 16 字符 Crockford base32 ≈ 80 bits entropy，宇宙热寂前猜不到 |
+| 🟢 Relay 看到内容 | 零知识架构 — relay 只路由密文，不持有 shared secret |
+| 🟡 信任 hosted relay 维护者 | Self-host 完全摆脱这层信任。作者看得到 metadata（peer ID、时间、大小），理论上可改 PWA bundle。源码公开，可自行 audit 或 self-host。 |
+| 🟢 Hosted relay 被 DDoS | Cloudflare rate limit 限 30 req/60 秒/IP。最坏：你的当日配额烧光 |
+
+## Self-host（手动）
+
+`miki setup` wizard 自动做完，但要手动的话：
+
+```bash
+# 在 clone 好的 cc-hub source 树：
+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`：
+
+```json
+{
+  "remote": {
+    "worker_url": "wss://my-relay.<你 CF 账号>.workers.dev",
+    "phone_pwa_url": "https://my-phone.pages.dev/"
+  }
+}
+```
+
+下次 `miki start` 就会用新 endpoints。
+
+## 开发
+
+```bash
+git clone https://github.com/WarmBed/Miki-Moni
+cd Miki-Moni
+pnpm install
+pnpm typecheck
+pnpm test         # daemon + worker tests
+pnpm dev          # tsx watch src/index.ts
+```
+
+Source 结构：
+
+| 路径 | 用途 |
+|---|---|
+| `src/` | Node daemon（express + ws + better-sqlite3）— hooks、配对、RelayClient |
+| `web/` | 桌面 / 手机完整 dashboard（Preact + Tailwind + Vite） |
+| `web-phone/` | 手机 bootstrap（QR 扫描器 + tunnel 设置）— mount web/ |
+| `worker/` | Cloudflare Worker relay（DaemonRelay + PairingCoordinator DOs） |
+| `extension/` | VSCode helper extension — handle `claude-vscode.send` |
+| `hooks/` | Claude Code hook 脚本（PowerShell）— POST event 到 daemon |
+| `bin/miki.mjs` | npm 发布的 CLI 入口 |
+
+## 分支
+
+- `main` — 版本化 release（当前：v0.0.0）
+- `dev` — 开发中；每改动 bump `package.json` version
+
+## 相关项目
+
+**[Happy](https://happy.engineering)**（`slopus/happy-cli`, MIT）切的痛点有重叠 — 从手机操控 Claude Code — 但角度不同。两者可以同一台机器并存。
+
+|  | Miki-Moni | Happy |
+|---|---|---|
+| 主入口 | VSCode panel — hooks 把每个 panel 拉进 dashboard | 取代 `claude` 的 terminal wrapper |
+| Relay | Cloudflare Worker；可以 5 分钟 self-host 到自己 CF 账号 | 作者自架 socket.io server（`api.cluster-fluster.com`） |
+| 手机端 | Web PWA — 扫 QR 就能用，免装 app | 原生 iOS / Android app |
+| 支持 agent | Claude Code | Claude Code、Codex、Gemini、通用 ACP |
+| 语音输入 | — | 有 |
+| 多 session 可视化 dashboard | 有 — 跨窗口聚合 | 各 session 独立管 |
+| 取代 `claude` 吗 | 不取代 — hooks 并存 | 取代，自己 spawn `claude` |
+| 远端 spawn（人不在桌前也能起新 session） | — | 有（`happy daemon`） |
+| 加密 relay | 有（X25519 + NaCl secretbox） | 有（X25519 + NaCl secretbox + AES-GCM） |
+
+想要打磨好的手机原生体验、跨多个 AI agent、不介意 SaaS relay → 用 Happy。住在 VSCode 里、想要一张 dashboard 收齐多个并行 panel、想 self-host 到自己 CF → 用 Miki-Moni。
+
+## 许可证
+
+MIT — 见 [LICENSE](LICENSE)。
+
+## Credits
+
+用 [Anthropic Claude](https://claude.ai/code) 通过 [Claude Code](https://github.com/anthropics/claude-code) 写出来的。