wechat-claude-sessions 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for your interest in wechat-claude!
+
+## Development setup
+
+```bash
+git clone https://github.com/Neil-UWA/wechat-claude.git
+cd wechat-claude
+npm install
+npm run build
+npm test
+```
+
+To run your checkout as the real thing (instead of the published package),
+link it and then set up as usual:
+
+```bash
+npm link                 # puts the `wechat-claude` bin on your PATH
+wechat-claude setup
+wechat-claude daemon install
+```
+
+- Source is TypeScript in `src/`, compiled to `dist/` (gitignored).
+- Files shipped to users live in `templates/` — the `/wechat` slash command
+  and the launchd plist template. `.claude/commands/wechat.md` is a symlink
+  to `templates/wechat.md`, so edit the template and both stay in sync.
+- The CLI (`src/cli.ts`) is the only entry point users have after a global
+  install; the `daemon:*` npm scripts just delegate to it. Add new operations
+  as CLI subcommands, not as npm scripts.
+- Tests use [vitest](https://vitest.dev): `npm test` (or `npm run test:watch`).
+- The daemon and MCP server share logic through small modules
+  (`src/sessions.ts`, `src/inbox.ts`, `src/tmux.ts`, etc.) — add behavior
+  there so both stay in sync, and cover it with a unit test.
+
+## Conventions
+
+- Strict TypeScript: no `any`, no non-null assertions, explicit return types
+  on exported functions.
+- User-facing WeChat strings live in `src/i18n.ts` with `zh` (default) and
+  `en` catalogs — add both when you add a message, and localize content
+  markers via `marker()` and relative times via `formatAgo(ms, lang)`.
+- Never build a shell command by string interpolation of user input. Use
+  `spawnSync` with an argv array (see `src/tmux.ts`).
+
+## Pull requests
+
+- Keep PRs focused; include tests for new behavior.
+- Run `npm run build && npm test` before pushing — CI runs the same.
+- Describe user-facing changes so `/help`, both READMEs (`README.md` is the
+  Chinese default, `README.en.md` the English version — keep them in sync), and MCP tool
+  descriptions can be kept in sync.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neil Lu
+
+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.en.md

@@ -0,0 +1,264 @@
+[中文](README.md) | English
+
+# wechat-claude
+
+Control Claude Code from your phone via WeChat. Message a task like
+`/run fix the login bug` and a Claude Code session runs it on your machine and
+sends the result back to your chat. Built on the ilink Bot API — no
+third-party dependencies beyond the MCP SDK.
+
+> ⚠️ **This runs code on your computer from chat messages.** Read
+> [SECURITY.md](SECURITY.md) before using it. Run it only on a machine you
+> control and an account only you can message.
+
+## Prerequisites
+
+- **Node.js 20+** and **[Claude Code](https://claude.com/claude-code)**.
+- **WeChat with ClawBot / ilink Bot access.** The bot is bound to *your* WeChat
+  account by scanning a QR code at login; it is not publicly discoverable and
+  strangers cannot message it. macOS is the first-class platform (launchd
+  autostart + native notifications); Linux/Windows run the daemon manually.
+
+## Architecture
+
+```
+WeChat User ←→ ilink Bot API ←→ Daemon (polling + routing) ←→ Inbox Files ←→ MCP Server (Claude Code)
+```
+
+- **Daemon**: Standalone Node.js process that polls WeChat for messages, handles routing commands, and writes messages to per-session inbox files. Runs independently of Claude Code.
+- **MCP Server**: Lightweight tool server registered with Claude Code. Reads from its session's inbox, sends replies via ilink API. No polling.
+
+## Setup
+
+```bash
+npm install -g wechat-claude-sessions
+wechat-claude setup
+```
+
+Install it **globally**, not with a bare `npx` — `setup` registers absolute
+paths (MCP server, launchd service) that must survive past the current shell,
+and npx's cache is not a stable location. Building from a git checkout works
+too: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+`setup` registers the MCP server, installs the `/wechat` slash command into
+`~/.claude/commands/`, and walks you through QR login (it opens the QR image in
+your browser — scan it with WeChat). The bot token is saved to
+`~/.claude/wechat/session.json` (mode 0600); you won't scan again unless it
+expires.
+
+Then start the daemon and enable monitoring:
+
+```bash
+wechat-claude daemon install   # macOS: install as a launchd service (auto-start + restart)
+# or, without autostart:
+wechat-claude daemon           # run it in the foreground / your own supervisor
+```
+
+Finally, type `/wechat` in any Claude Code session. That starts a persistent
+watcher (`dist/watch-inbox.js`) that reacts to messages instantly via
+`fs.watch` and marks the session `[monitoring]`. The daemon also auto-starts on
+`/wechat` and after a successful login if it isn't already running (it's a
+singleton, guarded by a pid file).
+
+`wechat-claude daemon install` generates the launchd plist for *your* paths
+from a packaged template and writes it to
+`~/Library/LaunchAgents/com.wechat-claude.daemon.plist` — no manual editing.
+Re-run it after a Node version switch or a global upgrade to refresh the paths.
+Other CLI commands: `wechat-claude login` (re-auth) and `wechat-claude status`.
+
+If the WeChat login expires, the daemon posts a macOS notification and sets a
+flag that `wechat_status` surfaces, so the next `/wechat` prompts a re-login —
+see [Troubleshooting](#troubleshooting) since you'll be away from the Mac.
+
+## WeChat Commands
+
+Send these from WeChat to control routing:
+
+| Command | Description |
+|---------|-------------|
+| `/sessions` or `/ls` | List active Claude Code sessions (`[监控中]` = actively monitoring) |
+| `/s <number> <message>` | Send message to session by its number. Numbers are stable for a session's lifetime — they never shift when other sessions open or close (retired numbers aren't reused; numbering resets once all sessions are gone) |
+| `/use <number\|name\|pid>` | Bind your chat to one session: every plain message goes straight to it (survives daemon restarts). `/use off` unbinds; `/use` shows the current binding. Closing the bound session clears the binding automatically |
+| `/s <name> <message>` | Send message to session by name (fuzzy match; if ambiguous, prefers the monitored / most recently active one) |
+| `/s <pid> <message>` | Send message to session by pid (duplicate names are listed as `name#pid`) |
+| `/run [--safe] [dir] <task>` | Start a new Claude session in tmux to run a task. The launched session is instructed to send its result back to WeChat. Runs unattended by default (`--dangerously-skip-permissions`); pass `--safe` for `--permission-mode acceptEdits`, where bash commands wait for confirmation at the computer. The first unattended run accepts skip-permissions mode in `~/.claude.json` on your behalf — a detached session cannot answer Claude Code's one-time dialog — and says so in its reply; see [SECURITY.md](SECURITY.md) |
+| `/runs` | List running `/run` task sessions |
+| `/stop <name>` | Kill a `/run` task session (names start with `wc-`) |
+| `/close <number\|name\|pid>` | Close a Claude session remotely — terminates its Claude process (and MCP server) and removes it from the list. Unsaved work in that session is lost. If a name matches several sessions it lists them instead of guessing; `/close <name> all` closes all matches, `/close idle` cleans up every unmonitored session idle for 2+ hours. Every close reply ends with a remaining-session summary |
+| `/help` | Show command help |
+| *(no prefix)* | Send to the most recently active **monitoring** session (falls back to most recently active overall) |
+
+Delivery feedback: if a message lands in a session that isn't monitoring its
+inbox, the daemon warns you immediately; if a delivered message is still
+unread after 2 minutes, it sends a reminder.
+
+Incoming images are downloaded and decrypted automatically to
+`~/.claude/wechat/media/` (cleaned up after 7 days); the routed message text
+contains the local path (`[图片: /path/to/file.png]`) so the receiving Claude
+session can open the file directly.
+
+### /run directory resolution
+
+`/run <name> <task>` resolves `<name>` in this order:
+
+1. An active session whose name (or directory basename) matches
+2. An absolute path
+3. `<dir>/<name>` for each search directory — the `repoDirs` entries in
+   `~/.claude/wechat/config.json` (optional, e.g. `{"repoDirs": ["~/code"]}`;
+   entries must be absolute or `~`-prefixed, invalid entries are reported)
+   plus the parent directory of every active session's cwd (the home
+   directory itself is never used as a search root)
+
+If the first word looks like a directory name but resolves nowhere, the run
+is cancelled with an explanation instead of silently executing in another
+directory. Use `/run . <task>` to force the default directory when the task
+text happens to start with a path-like word.
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `wechat_login` | Generate QR code for WeChat login |
+| `wechat_login_poll` | Poll QR code scan status |
+| `wechat_get_messages` | Read and clear incoming messages from inbox |
+| `wechat_send_text` | Send a text reply to a WeChat user |
+| `wechat_send_image` | Send an image file (with optional caption) to a WeChat user |
+| `wechat_set_session_name` | Set a custom name for routing |
+| `wechat_status` | Check connection, daemon, and session info |
+| `wechat_logout` | Disconnect and clear session |
+
+## Session Naming
+
+Sessions are automatically named based on the working directory:
+
+- Git repo: `reponame:branch` (e.g., `myapp:main`)
+- Worktree: `reponame/worktree-name` (e.g., `myapp/feature-x`)
+- Non-git: directory name
+
+Use `wechat_set_session_name` to set a custom name.
+
+## File Layout
+
+```
+~/.claude/wechat/
+├── session.json          # ilink bot token (persisted login)
+├── config.json           # optional settings (e.g. repoDirs for /run)
+├── bindings.json         # /use bindings (WeChat user -> session)
+├── session-numbers.json  # stable session number registry
+├── media/                # downloaded incoming images (7-day retention)
+├── context_tokens.json   # shared context tokens (daemon ↔ MCP server)
+├── daemon.pid            # daemon process ID
+├── daemon.log            # daemon output
+├── cursor.txt            # message polling cursor
+├── expired.flag          # present when the WeChat login has expired
+├── sessions/             # registered Claude Code sessions
+│   └── <pid>.json
+├── inbox/                # per-session message queues
+│   └── <pid>.json
+├── heartbeat/            # watcher heartbeats (session is [monitoring])
+│   └── <pid>
+└── typing/               # typing indicator state
+    └── <userId>
+```
+
+## CLI
+
+```bash
+wechat-claude setup              # Register MCP server + /wechat command, then log in
+wechat-claude login              # (Re)authenticate by scanning a QR code
+wechat-claude status             # Show login / daemon / service state
+wechat-claude daemon             # Run the daemon in the foreground
+wechat-claude daemon restart     # Restart it (use after upgrading)
+wechat-claude daemon install     # Install as a launchd service (macOS)
+wechat-claude daemon uninstall   # Remove the launchd service
+wechat-claude daemon status      # Check daemon / service state
+wechat-claude daemon log         # Tail the daemon log
+```
+
+In a git checkout the same commands are available as npm scripts
+(`npm run daemon:install`, …), which just delegate to the CLI.
+
+### Upgrading
+
+```bash
+npm install -g wechat-claude-sessions@latest
+wechat-claude daemon restart
+```
+
+Both long-lived processes keep the old code in memory until they are replaced.
+`daemon restart` handles the daemon (reloading the launchd job when one is
+installed, otherwise stopping and respawning it). The MCP server belongs to
+Claude Code, so reconnect it there — `/mcp` → `wechat` → Reconnect — and run
+`/wechat` again to re-attach the inbox watcher, which is bound to the old
+server's pid.
+
+## How It Works
+
+1. **Daemon** polls WeChat via the ilink Bot API (`getupdates` long-polling)
+2. Incoming messages are parsed and routed:
+   - Commands like `/sessions`, `/run`, `/close`, `/use` are handled by the daemon
+   - `/s <target> <msg>` routes to a specific session's inbox
+   - A plain message goes to your bound session (`/use`), else the most
+     recently active session that is `[monitoring]`
+3. When a message is routed, the daemon starts a "typing" indicator on WeChat
+4. **MCP Server** reads from its inbox when Claude calls `wechat_get_messages`
+5. Claude processes the message and replies via `wechat_send_text`
+6. The MCP server clears the typing indicator file; the daemon detects this and stops typing
+
+## Language
+
+Bot replies default to Chinese (the WeChat audience). To switch to English, set
+`lang` in `~/.claude/wechat/config.json`:
+
+```json
+{ "lang": "en" }
+```
+
+All user-facing strings live in `src/i18n.ts` (`zh` + `en`); the `WECHAT_LANG`
+environment variable overrides the config value.
+
+## Security
+
+wechat-claude executes code on your machine in response to chat messages. Read
+[SECURITY.md](SECURITY.md) for the full threat model. In short:
+
+- Only the account that scanned the login QR can message the bot; it is not
+  publicly discoverable and (currently) cannot be added to group chats.
+- `/run` runs unattended by default (`--dangerously-skip-permissions`); use
+  `/run --safe <task>` to require confirmation for bash commands.
+- The bot token lives in `~/.claude/wechat/session.json` (0600); the whole
+  data directory is 0700. Run only on a machine you control.
+
+## Troubleshooting
+
+- **The bot stopped replying.** The WeChat login likely expired — the daemon
+  exits on expiry and can no longer send messages. Back at the Mac, run
+  `wechat-claude status`; if logged out, `wechat-claude login` (or
+  `/wechat` in a session) to re-scan. Restart the daemon if needed.
+- **`/run` says "找不到目录".** The name didn't resolve to a project; add its
+  parent to `repoDirs` in `~/.claude/wechat/config.json`, pass an absolute
+  path, or use `/run . <task>` to run in the default directory.
+- **A message got no response.** Check `wechat-claude daemon status` and
+  `wechat-claude daemon log`. If the target session isn't `[monitoring]`, run
+  `/wechat` in it or bind with `/use <n>`.
+- **`daemon install` did nothing on Linux/Windows.** launchd is macOS-only;
+  run the daemon under your own supervisor (`wechat-claude daemon`, systemd,
+  pm2…).
+
+## Uninstall
+
+```bash
+wechat-claude daemon uninstall  # remove the launchd service (macOS)
+claude mcp remove wechat        # unregister the MCP server
+rm ~/.claude/commands/wechat.md # remove the slash command
+rm -rf ~/.claude/wechat         # remove tokens, inboxes, media, config
+npm uninstall -g wechat-claude-sessions
+```
+
+## Requirements
+
+- Node.js 20+
+- Claude Code
+- WeChat with ClawBot / ilink Bot access
+- macOS for launchd autostart and native notifications; Linux/Windows work
+  with a manually supervised daemon

package/README.md

@@ -0,0 +1,245 @@
+中文 | [English](README.en.md)
+
+# wechat-claude
+
+用微信从手机上操控 Claude Code。发一条 `/run 修复登录的 bug`，你电脑上就会跑起一个
+Claude Code session 去执行，结果再发回聊天窗口。基于 ilink Bot API 构建，除 MCP SDK
+外没有第三方依赖。
+
+> ⚠️ **它会根据聊天消息在你的电脑上执行代码。** 使用前请先读
+> [SECURITY.md](SECURITY.md)。只在你自己掌控的机器上运行，并且只绑定只有你能发消息的账号。
+
+## 前置条件
+
+- **Node.js 20+** 和 **[Claude Code](https://claude.com/claude-code)**。
+- **拥有 ClawBot / ilink Bot 权限的微信账号。** 机器人在登录时通过扫码绑定到*你自己的*
+  微信账号；它不会被公开检索到，陌生人也无法给它发消息。macOS 是一等公民（launchd
+  开机自启 + 原生通知）；Linux/Windows 需要自己托管 daemon。
+
+## 架构
+
+```
+微信用户 ←→ ilink Bot API ←→ Daemon（轮询 + 路由）←→ Inbox 文件 ←→ MCP Server（Claude Code）
+```
+
+- **Daemon**：独立的 Node.js 进程，轮询微信消息、处理路由命令、把消息写进各 session 的
+  inbox 文件。独立于 Claude Code 运行。
+- **MCP Server**：注册到 Claude Code 的轻量工具服务。只读自己 session 的 inbox，通过
+  ilink API 发回复。不做轮询。
+
+## 安装
+
+```bash
+npm install -g wechat-claude-sessions
+wechat-claude setup
+```
+
+必须**全局安装**，不要用裸 `npx` —— `setup` 会注册一批绝对路径（MCP server、launchd
+服务），这些路径得活得比当前 shell 更久，而 npx 的缓存目录并不稳定。从 git 检出构建也
+可以，见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+`setup` 会注册 MCP server、把 `/wechat` 斜杠命令装到 `~/.claude/commands/`，然后带你
+走完扫码登录（它会在浏览器里打开二维码图片，用微信扫）。机器人 token 保存在
+`~/.claude/wechat/session.json`（权限 0600）；除非过期，否则不用再扫。
+
+接着启动 daemon 并开启监控：
+
+```bash
+wechat-claude daemon install   # macOS：装成 launchd 服务（开机自启 + 崩溃重启）
+# 或者不要自启：
+wechat-claude daemon           # 前台运行 / 交给你自己的进程管理器
+```
+
+最后，在任意 Claude Code session 里输入 `/wechat`。这会启动一个常驻 watcher
+（`dist/watch-inbox.js`），它通过 `fs.watch` 即时响应消息，并把该 session 标记为
+`[监控中]`。daemon 在 `/wechat` 时和登录成功后也会自动拉起（它是单例，由 pid 文件守护）。
+
+`wechat-claude daemon install` 会用打包好的模板为*你这台机器*生成 launchd plist，写到
+`~/Library/LaunchAgents/com.wechat-claude.daemon.plist`，不需要手工编辑。切换 Node 版本
+或全局升级之后重跑一次即可刷新路径。其他 CLI 命令：`wechat-claude login`（重新认证）和
+`wechat-claude status`。
+
+如果微信登录过期，daemon 会发一条 macOS 通知并设置一个标志位，`wechat_status` 会把它暴露
+出来，于是下一次 `/wechat` 就会提示重新登录 —— 见[故障排查](#故障排查)，因为那时你多半
+不在电脑旁。
+
+## 微信命令
+
+在微信里发这些命令来控制路由：
+
+| 命令 | 说明 |
+|------|------|
+| `/sessions` 或 `/ls` | 列出活跃的 Claude Code session（`[监控中]` = 正在实时监控） |
+| `/s <编号> <消息>` | 按编号发消息给某个 session。编号在 session 生命周期内固定不变 —— 其他 session 开启或关闭都不会让它移位（退役的编号不会被复用；所有 session 都消失后编号重新计数） |
+| `/use <编号\|名字\|pid>` | 把你的聊天绑定到某个 session：之后每条不带前缀的消息都直接发给它（daemon 重启后依然有效）。`/use off` 解绑；`/use` 查看当前绑定。被绑定的 session 关闭时会自动解绑 |
+| `/s <名字> <消息>` | 按名字发消息（模糊匹配；有歧义时优先选正在监控的 / 最近活跃的） |
+| `/s <pid> <消息>` | 按 pid 发消息（同名的会以 `名字#pid` 形式列出） |
+| `/run [--safe] [目录] <任务>` | 在 tmux 里起一个新的 Claude session 执行任务。被启动的 session 会被要求把结果发回微信。默认无人值守运行（`--dangerously-skip-permissions`）；加 `--safe` 则用 `--permission-mode acceptEdits`，此时 bash 命令会在电脑端等待确认。第一次无人值守运行时，会替你在 `~/.claude.json` 里接受免确认模式 —— detached 的 session 无法回答 Claude Code 的一次性对话框 —— 并在回复里说明；详见 [SECURITY.md](SECURITY.md) |
+| `/runs` | 列出运行中的 `/run` 任务 session |
+| `/stop <名字>` | 终止一个 `/run` 任务 session（名字以 `wc-` 开头） |
+| `/close <编号\|名字\|pid>` | 远程关闭一个 Claude session —— 终结它的 Claude 进程（以及 MCP server）并从列表移除。该 session 里未保存的工作会丢失。如果一个名字匹配到多个，会列出来而不是瞎猜；`/close <名字> all` 关闭全部匹配项，`/close idle` 清理所有闲置 2 小时以上且未被监控的 session。每次关闭的回复末尾都会附上剩余 session 概览 |
+| `/help` | 显示命令帮助 |
+| *（无前缀）* | 发给最近活跃的**监控中** session（没有的话退回到最近活跃的那个） |
+
+**投递反馈**：如果消息落到了一个没在监控 inbox 的 session，daemon 会立刻警告你；如果一条
+已投递的消息 2 分钟后仍未被读取，它会再发一条提醒。
+
+**图片**会被自动下载解密到 `~/.claude/wechat/media/`（保留 7 天）；路由后的消息文本里带
+本地路径（`[图片: /path/to/file.png]`），接收方的 Claude session 可以直接打开该文件。
+
+### /run 的目录解析
+
+`/run <名字> <任务>` 按以下顺序解析 `<名字>`：
+
+1. 名字（或目录 basename）匹配的活跃 session
+2. 绝对路径
+3. 各搜索目录下的 `<目录>/<名字>` —— 搜索目录来自 `~/.claude/wechat/config.json` 里的
+   `repoDirs`（可选，例如 `{"repoDirs": ["~/code"]}`；条目必须是绝对路径或以 `~` 开头，
+   无效条目会被报出来），外加每个活跃 session 工作目录的父目录（home 目录本身永远不会
+   被当作搜索根）
+
+如果第一个词看起来像目录名但哪里都解析不到，这次运行会被取消并给出解释，而不是悄悄跑到
+别的目录里去。当任务文本恰好以一个像路径的词开头时，用 `/run . <任务>` 强制使用默认目录。
+
+## MCP 工具
+
+| 工具 | 说明 |
+|------|------|
+| `wechat_login` | 生成微信登录二维码 |
+| `wechat_login_poll` | 轮询扫码状态 |
+| `wechat_get_messages` | 读取并清空 inbox 里的新消息 |
+| `wechat_send_text` | 给微信用户发文本回复 |
+| `wechat_send_image` | 给微信用户发图片文件（可带说明文字） |
+| `wechat_set_session_name` | 为路由设置自定义 session 名 |
+| `wechat_status` | 查看连接、daemon 和 session 状态 |
+| `wechat_logout` | 断开连接并清除 session |
+
+## Session 命名
+
+Session 会根据工作目录自动命名：
+
+- Git 仓库：`仓库名:分支`（例如 `myapp:main`）
+- Worktree：`仓库名/worktree名`（例如 `myapp/feature-x`）
+- 非 Git 目录：目录名
+
+用 `wechat_set_session_name` 可以设置自定义名字。
+
+## 文件布局
+
+```
+~/.claude/wechat/
+├── session.json          # ilink 机器人 token（持久化登录）
+├── config.json           # 可选配置（例如 /run 用的 repoDirs）
+├── bindings.json         # /use 绑定关系（微信用户 -> session）
+├── session-numbers.json  # 稳定 session 编号注册表
+├── media/                # 下载的图片（保留 7 天）
+├── context_tokens.json   # 共享上下文 token（daemon ↔ MCP server）
+├── daemon.pid            # daemon 进程 ID
+├── daemon.log            # daemon 输出
+├── cursor.txt            # 消息轮询游标
+├── expired.flag          # 微信登录过期时存在
+├── sessions/             # 已注册的 Claude Code session
+│   └── <pid>.json
+├── inbox/                # 各 session 的消息队列
+│   └── <pid>.json
+├── heartbeat/            # watcher 心跳（session 处于 [监控中]）
+│   └── <pid>
+└── typing/               # 输入状态
+    └── <userId>
+```
+
+## CLI
+
+```bash
+wechat-claude setup              # 注册 MCP server + /wechat 命令，然后登录
+wechat-claude login              # （重新）扫码认证
+wechat-claude status             # 查看登录 / daemon / 服务状态
+wechat-claude daemon             # 前台运行 daemon
+wechat-claude daemon restart     # 重启 daemon（升级后用）
+wechat-claude daemon install     # 装成 launchd 服务（macOS）
+wechat-claude daemon uninstall   # 移除 launchd 服务
+wechat-claude daemon status      # 查看 daemon / 服务状态
+wechat-claude daemon log         # 跟踪 daemon 日志
+```
+
+在 git 检出里，同样的命令也有对应的 npm script（`npm run daemon:install` 等），它们只是
+转调 CLI。
+
+### 升级
+
+```bash
+npm install -g wechat-claude-sessions@latest
+wechat-claude daemon restart
+```
+
+两个长期存活的进程在被替换之前都还揣着旧代码。`daemon restart` 负责 daemon（装了 launchd
+就重载该 job，否则停掉再重新拉起）。MCP server 归 Claude Code 管，所以要在那边重连 ——
+`/mcp` → `wechat` → Reconnect —— 然后再跑一次 `/wechat` 重新挂上 inbox watcher，因为它绑
+的是旧 server 的 pid。
+
+## 工作原理
+
+1. **Daemon** 通过 ilink Bot API 轮询微信（`getupdates` 长轮询）
+2. 收到的消息被解析并路由：
+   - `/sessions`、`/run`、`/close`、`/use` 这类命令由 daemon 自己处理
+   - `/s <目标> <消息>` 路由到指定 session 的 inbox
+   - 不带前缀的消息发给你绑定的 session（`/use`），否则发给最近活跃且处于 `[监控中]`
+     的那个
+3. 消息被路由时，daemon 会在微信上打开"正在输入"指示
+4. **MCP Server** 在 Claude 调用 `wechat_get_messages` 时读取自己的 inbox
+5. Claude 处理消息并通过 `wechat_send_text` 回复
+6. MCP server 清除输入状态文件，daemon 检测到后停止"正在输入"
+
+## 语言
+
+机器人回复默认用中文（面向微信用户）。要切换成英文，在
+`~/.claude/wechat/config.json` 里设置 `lang`：
+
+```json
+{ "lang": "en" }
+```
+
+所有面向用户的字符串都在 `src/i18n.ts`（`zh` + `en`）；环境变量 `WECHAT_LANG` 会覆盖配置
+文件里的值。
+
+## 安全
+
+wechat-claude 会响应聊天消息、在你的机器上执行代码。完整威胁模型见
+[SECURITY.md](SECURITY.md)。简而言之：
+
+- 只有扫码登录的那个账号能给机器人发消息；它不会被公开检索到，（目前）也不能被拉进群聊。
+- `/run` 默认无人值守运行（`--dangerously-skip-permissions`）；用
+  `/run --safe <任务>` 可以让 bash 命令需要确认。
+- 机器人 token 存在 `~/.claude/wechat/session.json`（0600），整个数据目录是 0700。
+  只在你自己掌控的机器上运行。
+
+## 故障排查
+
+- **机器人不回消息了。** 多半是微信登录过期 —— daemon 在过期时会退出，也就再也发不出消息。
+  回到 Mac 上运行 `wechat-claude status`；如果显示未登录，用 `wechat-claude login`
+  （或在某个 session 里 `/wechat`）重新扫码。需要的话重启 daemon。
+- **`/run` 提示"找不到目录"。** 那个名字没解析到项目；把它的父目录加到
+  `~/.claude/wechat/config.json` 的 `repoDirs` 里，或者传绝对路径，或者用
+  `/run . <任务>` 在默认目录里跑。
+- **消息发出去没反应。** 检查 `wechat-claude daemon status` 和
+  `wechat-claude daemon log`。如果目标 session 不在 `[监控中]`，在它里面跑 `/wechat`，
+  或者用 `/use <编号>` 绑定。
+- **Linux/Windows 上 `daemon install` 什么都没做。** launchd 是 macOS 专有的；请用你自己
+  的进程管理器托管 daemon（`wechat-claude daemon`、systemd、pm2……）。
+
+## 卸载
+
+```bash
+wechat-claude daemon uninstall  # 移除 launchd 服务（macOS）
+claude mcp remove wechat        # 注销 MCP server
+rm ~/.claude/commands/wechat.md # 删除斜杠命令
+rm -rf ~/.claude/wechat         # 删除 token、inbox、图片、配置
+npm uninstall -g wechat-claude-sessions
+```
+
+## 环境要求
+
+- Node.js 20+
+- Claude Code
+- 拥有 ClawBot / ilink Bot 权限的微信账号
+- macOS 才有 launchd 自启和原生通知；Linux/Windows 需要自己托管 daemon

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+## Threat model — read this before running
+
+wechat-claude bridges a **chat channel** to **command execution on your
+computer**. A message like `/run <task>` starts a Claude Code session on your
+machine, and `/close` / `/stop` terminate processes. Treat the bot as a remote
+control for your laptop.
+
+Key facts to understand:
+
+- **Anyone who can message your bot can drive your machine.** There is
+  currently no per-sender authorization check — every incoming WeChat message
+  is acted on. Only enable the bot for an account that only you can message,
+  and never share or publicize the bot.
+- **`/run` defaults to `--dangerously-skip-permissions`.** Tasks run
+  unattended without per-action confirmation. Use `/run --safe <task>` for
+  `--permission-mode acceptEdits` (bash commands then wait for confirmation at
+  the computer).
+- **The first such `/run` accepts skip-permissions mode on your behalf.**
+  Claude Code gates that mode behind a one-time interactive dialog, which a
+  detached tmux session can never answer — the task would hang on the prompt
+  forever. So the daemon sets `bypassPermissionsModeAccepted` in
+  `~/.claude.json` before launching, and says so in its reply the one time it
+  does. If you would rather grant that yourself, accept the dialog once by
+  running `claude --dangerously-skip-permissions` at the computer, or stay on
+  `/run --safe`, which never touches the flag.
+- **The bot token is stored at `~/.claude/wechat/session.json`** (mode 0600).
+  The whole `~/.claude/wechat/` directory is created 0700. Anyone with read
+  access to your home directory can impersonate your bot.
+- **Run only on machines you control.** Do not run the daemon on shared or
+  multi-user hosts, and do not expose it to untrusted contacts.
+
+## Recommended hardening
+
+- Keep the bot conversation private (a single-user chat).
+- Prefer `/run --safe` unless you are actively watching the task.
+- Review `~/.claude/wechat/config.json` `repoDirs` — only list directories you
+  are comfortable running tasks in.
+
+## Reporting a vulnerability
+
+Please report security issues privately by opening a
+[GitHub security advisory](https://github.com/Neil-UWA/wechat-claude/security/advisories/new)
+rather than a public issue. We aim to respond within a week.

package/dist/bindings.d.ts

@@ -0,0 +1,4 @@
+export declare function getBinding(userId: string): string | undefined;
+export declare function setBinding(userId: string, sessionId: string): void;
+export declare function clearBinding(userId: string): void;
+export declare function clearBindingsToSession(sessionId: string): void;