@caoruhua/open-claude-remote 0.1.7 → 0.2.4

package/README.md

@@ -2,6 +2,15 @@
 
 **Control Claude Code from your mobile browser over LAN.**
 
+[English](#english) | [中文](#中文)
+
+---
+
+<a name="english"></a>
+## English
+
+**Control Claude Code from your mobile browser over LAN.**
+
 View terminal output, send commands, and approve tool calls from your phone — keep working even when you step away from your desktop.
 
 ---
@@ -54,12 +63,14 @@ Scan the QR code shown in your terminal with your phone. The auth token is auto-
 - Auto-skips on subsequent visits
 
 ### Multi-Instance
-- Run multiple `claude-remote` instances simultaneously
+- Run multiple `claude-remote` instances simultaneously in a single daemon process
+- Fixed port 8866 — all instances share same origin, no cross-port auth needed
 - Browser tab bar for switching — no re-authentication needed
 - Auto-switch when an instance goes offline
 - Spawn new instances from the web UI ("+" button)
 - Copy instance via long-press/right-click tab — pre-fills working directory, settings, and arguments
-- `claude-remote attach <port|name>` to take over a web-spawned instance
+- `claude-remote attach <name|id>` to take over a web-spawned instance
+- `claude-remote stop` to stop the daemon and all instances
 
 ### Window Resize Priority
 
@@ -125,7 +136,7 @@ Get notified when Claude is waiting for input. All notifications include the ins
 ## Usage
 
 ```bash
-# Start Claude Code
+# Start Claude Code (starts daemon + first instance)
 claude-remote
 
 # Pass arguments to Claude
@@ -133,13 +144,21 @@ claude-remote chat
 claude-remote -- --dangerously-skip-permissions
 
 # Custom options
-claude-remote --port 8080
 claude-remote --name my-project
 claude-remote --token my-secret-token
 
-# Attach to a web-spawned instance
-claude-remote attach 3001        # by port
+# Attach to an existing instance
 claude-remote attach my-project  # by name
+claude-remote attach 550e8400     # by instance ID prefix
+
+# List all running instances
+claude-remote list
+
+# Show daemon status (PID, port, uptime, instance count, three-version info)
+claude-remote status
+
+# Stop the daemon and all instances
+claude-remote stop
 
 # Headless mode (no local terminal, web UI only)
 claude-remote --no-terminal
@@ -151,6 +170,18 @@ claude-remote --version
 claude-remote update
 ```
 
+### Version Checks
+
+`claude-remote status` displays three versions with actionable advice:
+
+- **Installed** — CLI version on disk
+- **Daemon** — version cached by the running daemon (✓ or "outdated")
+- **Latest** — newest version on npm (✓ or "new")
+
+On startup, a background npm check runs without blocking. If a newer version exists, a one-line hint is printed to stderr.
+
+After `claude-remote update`, the daemon is automatically restarted if no instances are running. If instances exist, you'll see a reminder to restart manually.
+
 ### Stopping
 
 - **Single Ctrl+C** — sent to Claude Code (cancels current task)
@@ -160,11 +191,10 @@ claude-remote update
 
 ## Configuration
 
-Config file: `~/.claude-remote/config.json`
+Config file: `~/.claude-remote/settings.json` (legacy `config.json` is auto-migrated)
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `port` | number | 3000 | Server port (auto-increments if busy) |
 | `host` | string | "0.0.0.0" | Bind address |
 | `token` | string \| null | null | Auth token; `null` = auto-generated shared token |
 | `claudeCommand` | string | "claude" | Claude CLI path |
@@ -180,6 +210,8 @@ Config file: `~/.claude-remote/config.json`
 | `settingsDirs` | string[] | ["~/.claude/", "~/.claude-remote/settings/"] | Directories to scan for settings files |
 | `notifications` | object | — | Notification channels config (see below) |
 
+> **Note**: Port is fixed at 8866. All instances run in a single daemon process.
+
 **Notification channel config:**
 
 | Field | Type | Default | Description |
@@ -248,6 +280,14 @@ Custom command buttons in the shortcut bar.
 | /stats | Statistics |
 | /exit | Exit |
 
+**Skills as Commands:**
+
+Skills defined in `~/.claude/skills/*/SKILL.md` or `<project>/.claude/skills/*/SKILL.md` are automatically converted to slash commands. For example, a skill named `finish-task` becomes `/finish-task` in the command bar.
+
+- Skills are scanned on each `/api/config` request
+- Project-level skills override global skills with the same name
+- User modifications (enabled, autoSend) are preserved across scans
+
 **Custom example:**
 
 ```json
@@ -320,13 +360,12 @@ When creating instances from the web UI, you can select a custom settings file t
 }
 ```
 
-> **Note**: Files like `3000.json` (port configs) are automatically excluded from the settings file list.
+> **Note**: Port-numbered JSON files are automatically excluded from the settings file list.
 
 ### Complete Example
 
 ```json
 {
-  "port": 3000,
   "host": "0.0.0.0",
   "token": null,
 
@@ -396,7 +435,7 @@ Install build tools:
 
 ### Phone can't connect?
 
-1. Check your PC firewall allows the port (default: 3000)
+1. Check your PC firewall allows port 8866
 2. Verify the URL shows the correct LAN IP
 3. If using a VPN, try setting the `host` option explicitly
 
@@ -447,3 +486,487 @@ pnpm stop
 ## License
 
 MIT
+
+---
+---
+
+<a name="中文"></a>
+## 中文
+
+**通过局域网在手机浏览器中控制 Claude Code。**
+
+在手机上查看终端输出、发送命令、审批工具调用 — 即使离开桌面也能继续工作。
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+# npm
+npm install -g @caoruhua/open-claude-remote
+
+# pnpm（推荐）
+pnpm add -g @caoruhua/open-claude-remote
+```
+
+> **pnpm 用户注意**：pnpm v10 可能显示 "Ignored build scripts: node-pty" 警告。这是正常的，**不影响功能** — 包含预编译的二进制文件，开箱即用。要消除警告，运行 `pnpm approve-builds -g`（可选）。
+
+### 2. 运行
+
+```bash
+claude-remote
+```
+
+### 3. 连接
+
+用手机扫描终端显示的二维码。认证令牌自动填充 — 就可以开始使用了。
+
+> 首次运行时，`claude-remote` 会自动检查并安装缺失的依赖（pnpm、Claude CLI）。Hook 也会自动配置 — 无需手动设置。
+
+---
+
+## 功能特性
+
+### 终端同步
+- 实时终端输出推送到手机
+- 通过 xterm.js 完整渲染 ANSI 颜色
+- 1万行滚动缓冲区，重连时自动恢复
+- 局域网 IP 变更通知，附带新连接地址
+- 智能自动滚动，配有"滚动到底部"悬浮按钮
+
+### 快捷操作
+- 一键发送：Esc、Enter、Tab、方向键、Shift+Tab
+- 自定义快捷键（设置中配置）
+- 预设命令（/clear、/compact、/resume 等）
+
+### 新手引导
+- 首次访问时显示交互式高亮引导
+- 聚焦关键 UI 元素并显示提示标记
+- 后续访问自动跳过
+
+### 多实例支持
+- 在单个守护进程中同时运行多个 `claude-remote` 实例
+- 固定端口 8866 — 所有实例共享同源，无需跨端口认证
+- 浏览器标签栏切换 — 无需重新认证
+- 实例离线时自动切换
+- 从 Web UI 生成新实例（"+" 按钮）
+- 长按/右键标签复制实例 — 预填充工作目录、设置和参数
+- `claude-remote attach <名称|ID>` 接管 Web 生成的实例
+- `claude-remote stop` 停止守护进程和所有实例
+
+### 窗口大小优先级
+
+当多个客户端连接时，窗口大小由以下优先级控制：
+**WebApp（手机）> Attach（PC）> PC 终端**
+
+| 场景 | 控制方 | 行为 |
+|------|--------|------|
+| 无客户端连接 | PC 终端 | 正常本地使用 |
+| 仅 WebApp | WebApp | 手机控制窗口大小 |
+| 仅 Attach | Attach | PC attach 控制大小 |
+| WebApp + Attach | WebApp | 手机优先，PC 跟随 |
+
+- WebApp 在线时，Attach 的调整大小请求被忽略
+- Attach 连接时自动同步 WebApp 的窗口大小
+
+### 通知
+
+当 Claude 等待输入时收到通知。所有通知都包含实例 URL，即使 IP 变更也能快速重连。
+
+**Web 推送** — 即使浏览器在后台或屏幕锁定也能工作。只需在提示时允许通知即可。
+
+**渠道开关** — 每个通知渠道在设置中都有开关。切换即可启用/禁用，无需删除配置。更改立即生效于所有运行中的实例。
+
+**钉钉** — 配置钉钉机器人 webhook，在团队群中接收通知：
+
+```json
+{
+  "notifications": {
+    "dingtalk": {
+      "webhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=your-token"
+    }
+  }
+}
+```
+
+> **注意**：旧版配置文件中的根级 `dingtalk` 字段会在首次加载时自动迁移到 `notifications.dingtalk`。
+
+**设置步骤：**
+1. 打开钉钉群 → 群设置 → 智能群助手 → 添加机器人 → 自定义
+2. 安全设置选择"自定义关键词"，添加 `Claude`（消息标题包含此关键词）
+3. 将 Webhook URL 复制到配置文件或粘贴到 Web UI 设置中
+
+**微信（Server酱³）** — 配置 Server酱³ 在微信中接收通知：
+
+```json
+{
+  "notifications": {
+    "wechat_work": {
+      "sendKey": "SCTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+    }
+  }
+}
+```
+
+**设置步骤：**
+1. 访问 [Server酱 Sendkey](https://sct.ftqq.com/sendkey) 并用微信登录
+2. 复制你的 SendKey（以 `SCT` 开头）
+3. 粘贴到配置文件或 Web UI 设置中
+
+---
+
+## 使用方法
+
+```bash
+# 启动 Claude Code（启动守护进程 + 第一个实例）
+claude-remote
+
+# 向 Claude 传递参数
+claude-remote chat
+claude-remote -- --dangerously-skip-permissions
+
+# 自定义选项
+claude-remote --name my-project
+claude-remote --token my-secret-token
+
+# 附加到现有实例
+claude-remote attach my-project  # 按名称
+claude-remote attach 550e8400     # 按实例 ID 前缀
+
+# 列出所有运行中的实例
+claude-remote list
+
+# 显示守护进程状态（PID、端口、运行时间、实例数、三版本信息）
+claude-remote status
+
+# 停止守护进程和所有实例
+claude-remote stop
+
+# 无头模式（无本地终端，仅 Web UI）
+claude-remote --no-terminal
+
+# 查看版本
+claude-remote --version
+
+# 更新到最新版本
+claude-remote update
+```
+
+### 版本检查
+
+`claude-remote status` 显示三个版本及操作建议：
+
+- **Installed** — 磁盘上的 CLI 版本
+- **Daemon** — 运行中 daemon 缓存的版本（✓ 或 "outdated"）
+- **Latest** — npm 上的最新版本（✓ 或 "new"）
+
+启动时会后台检查 npm 新版本（不阻塞），如有更新会在 stderr 输出一行提示。
+
+执行 `claude-remote update` 后，如果没有运行中的实例，守护进程会自动重启。如有实例运行，会提示手动重启。
+
+### 停止运行
+
+- **单次 Ctrl+C** — 发送给 Claude Code（取消当前任务）
+- **双次 Ctrl+C**（500毫秒内）— 停止代理服务器
+
+---
+
+## 配置
+
+配置文件：`~/.claude-remote/settings.json`（旧版 `config.json` 会自动迁移）
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `host` | string | "0.0.0.0" | 绑定地址 |
+| `token` | string \| null | null | 认证令牌；`null` = 自动生成的共享令牌 |
+| `claudeCommand` | string | "claude" | Claude CLI 路径 |
+| `claudeArgs` | string[] | [] | 额外的 Claude CLI 参数（与 CLI 参数合并，去重） |
+| `claudeCwd` | string \| null | null | Claude 工作目录；`null` = 当前目录 |
+| `sessionTtlMs` | number | 86400000 | 会话 TTL（毫秒，默认 24 小时） |
+| `authRateLimit` | number | 20 | 认证速率限制（每分钟每 IP） |
+| `maxBufferLines` | number | 10000 | 输出缓冲区最大行数 |
+| `instanceName` | string \| null | null | 实例名称；`null` = 工作目录名 |
+| `shortcuts` | array | 见下文 | 快捷输入按钮 |
+| `commands` | array | 见下文 | 自定义命令按钮 |
+| `workspaces` | string[] | [] | Web 生成实例允许的工作目录 |
+| `settingsDirs` | string[] | ["~/.claude/", "~/.claude-remote/settings/"] | 设置文件扫描目录 |
+| `notifications` | object | — | 通知渠道配置（见下文） |
+
+> **注意**：端口固定为 8866。所有实例运行在单个守护进程中。
+
+**通知渠道配置：**
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `webhookUrl` | string | — | 钉钉 webhook URL |
+| `sendKey` | string | — | Server酱³ SendKey（微信） |
+| `enabled` | boolean | true | 渠道是否启用 |
+
+**优先级**：CLI 参数 > 配置文件 > 默认值（`claudeArgs` 除外，它是合并的）
+
+### 快捷键
+
+终端下方显示的快捷输入按钮。
+
+**默认快捷键：**
+
+| 按键 | 数据 | 说明 |
+|------|------|------|
+| Esc | `\u001b` | ESC 键 |
+| Enter | `\r` | 回车键 |
+| Tab | `\t` | Tab 键 |
+| ↑ | `\u001b[A` | 上箭头 |
+| ↓ | `\u001b[B` | 下箭头 |
+| ← | `\u001b[D` | 左箭头 |
+| → | `\u001b[C` | 右箭头 |
+| S-Tab | `\u001b[Z` | Shift+Tab |
+| Ctrl+O | `\u000f` | Ctrl+O |
+| Ctrl+E | `\u0005` | Ctrl+E |
+
+**自定义示例：**
+
+```json
+{
+  "shortcuts": [
+    { "label": "Yes", "data": "y", "enabled": true, "desc": "确认" },
+    { "label": "Esc", "data": "\u001b", "enabled": true, "desc": "取消 (ESC)" },
+    { "label": "Ctrl+C", "data": "\u0003", "enabled": true, "desc": "中断" }
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `label` | string | 按钮显示文本 |
+| `data` | string | 发送的数据（支持转义序列，如 `\u001b` 表示 ESC） |
+| `enabled` | boolean | 按钮是否启用 |
+| `desc` | string | 描述（可选） |
+
+**常用转义值：**
+- `\u001b` - ESC
+- `\r` - 回车
+- `\u0003` - Ctrl+C
+- `\u0004` - Ctrl+D
+
+### 命令
+
+快捷栏中的自定义命令按钮。
+
+**默认命令：**
+
+| 命令 | 说明 |
+|------|------|
+| /clear | 清屏 |
+| /compact | 压缩对话 |
+| /resume | 恢复会话 |
+| /stats | 统计信息 |
+| /exit | 退出 |
+
+**Skill 自动转换为命令：**
+
+定义在 `~/.claude/skills/*/SKILL.md` 或 `<项目>/.claude/skills/*/SKILL.md` 中的 Skill 会自动转换为斜杠命令。例如，名为 `finish-task` 的 Skill 会变成命令栏中的 `/finish-task`。
+
+- 每次请求 `/api/config` 时扫描 Skill
+- 项目级 Skill 覆盖同名的全局 Skill
+- 用户的修改（enabled、autoSend）在扫描时保留
+
+**自定义示例：**
+
+```json
+{
+  "commands": [
+    { "label": "/help", "command": "/help", "enabled": true },
+    { "label": "Git 状态", "command": "git status", "enabled": true, "autoSend": false }
+  ]
+}
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `label` | string | — | 按钮显示文本 |
+| `command` | string | — | 要执行的命令 |
+| `enabled` | boolean | — | 按钮是否启用 |
+| `autoSend` | boolean | `true` | `true` = 立即发送，`false` = 填入输入框 |
+
+> 以 `/` 开头的命令是 Claude Code 斜杠命令。其他命令在终端中执行。
+
+### 工作空间
+
+限制 Web 生成的实例可以使用哪些目录：
+
+```json
+{
+  "workspaces": [
+    "/home/user/projects/api",
+    "/home/user/projects/web"
+  ]
+}
+```
+
+如未配置，Web 生成的实例只能从已存在的 claude 实例中选择项目
+
+### 设置文件
+
+从 Web UI 创建实例时，可以选择自定义设置文件通过 `--settings` 传递。设置文件必须：
+
+1. 以 `settings` 为前缀命名（如 `settings-project-a.json`、`settings.idea.json`）
+2. 是有效的 `.json` 结尾的 JSON 文件
+3. 位于配置的扫描目录中
+
+**默认扫描目录：**
+- `~/.claude/` — Claude Code 配置目录
+- `~/.claude-remote/settings/` — Claude Remote 自定义设置
+
+**自定义目录：**
+
+```json
+{
+  "settingsDirs": [
+    "~/.claude/",
+    "~/.claude-remote/settings/",
+    "~/my-custom-settings/"
+  ]
+}
+```
+
+**设置文件示例**（`~/.claude/settings-project-a.json`）：
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
+  },
+  "permissions": {
+    "allow": ["Bash(git:*)", "Bash(npm:*)"]
+  }
+}
+```
+
+> **注意**：带端口号的 JSON 文件会自动从设置文件列表中排除。
+
+### 完整示例
+
+```json
+{
+  "host": "0.0.0.0",
+  "token": null,
+
+  "claudeCommand": "claude",
+  "claudeArgs": ["--no-telemetry"],
+  "claudeCwd": null,
+
+  "sessionTtlMs": 86400000,
+  "authRateLimit": 20,
+  "maxBufferLines": 10000,
+  "instanceName": null,
+
+  "shortcuts": [
+    { "label": "Yes", "data": "y", "enabled": true },
+    { "label": "Esc", "data": "\u001b", "enabled": true },
+    { "label": "Enter", "data": "\r", "enabled": true },
+    { "label": "Ctrl+C", "data": "\u0003", "enabled": true }
+  ],
+
+  "commands": [
+    { "label": "Git 状态", "command": "git status", "enabled": true },
+    { "label": "Git 日志", "command": "git log --oneline -10", "enabled": true }
+  ],
+
+  "workspaces": [
+    "/home/user/projects/api",
+    "/home/user/projects/web"
+  ],
+
+  "notifications": {
+    "dingtalk": {
+      "webhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=your-token"
+    }
+  }
+}
+```
+
+---
+
+## 安全性
+
+- **令牌认证** — 32 字节随机令牌，首次运行生成
+- **会话 Cookie** — HttpOnly + SameSite=Lax，24 小时 TTL
+- **网络隔离** — 仅绑定局域网 IP，无公网暴露
+- **速率限制** — 每个 IP 每分钟 20 次认证尝试
+- **Hook 安全** — 仅接受 localhost 请求
+
+---
+
+## 故障排除
+
+### `node-pty` 编译失败
+
+安装编译工具：
+
+| 操作系统 | 命令 |
+|---------|------|
+| macOS | `xcode-select --install` |
+| Ubuntu/Debian | `sudo apt-get install build-essential python3` |
+| Fedora/RHEL | `sudo dnf groupinstall 'Development Tools'` |
+| Arch Linux | `sudo pacman -S base-devel python` |
+
+### 二维码扫不了？
+
+1. 确保手机和 PC 在同一网络
+2. 手动打开终端显示的 URL 并输入令牌
+
+### 手机连不上？
+
+1. 检查 PC 防火墙允许端口 8866
+2. 验证 URL 显示正确的局域网 IP
+3. 如使用 VPN，尝试显式设置 `host` 选项
+
+---
+
+## 前置要求
+
+- **Node.js** >= 20
+- **Claude Code CLI** — [安装指南](https://docs.anthropic.com/en/docs/claude-code)
+
+> `pnpm` 和 Claude CLI 会在首次运行时自动安装（如缺失）。
+
+---
+
+## 开发
+
+**源码开发：**
+
+```bash
+# 克隆并安装
+git clone https://github.com/StephenTowne/open-claude-remote.git
+cd open-claude-remote
+pnpm install
+
+# 开发模式（热重载）
+pnpm dev:cli
+
+# 生产模式
+pnpm build && pnpm link -g && claude-remote
+```
+
+**项目结构：**
+
+- 后端：`backend/src/`（Express + node-pty + WebSocket）
+- 前端：`frontend/src/`（React + xterm.js）
+- 共享类型：`shared/`（通过 `#shared` 别名导入）
+- 测试：`pnpm test`（Vitest）
+- 构建：`pnpm build`（TypeScript + Vite）
+
+### 停止所有实例
+
+```bash
+pnpm stop
+```
+
+---
+
+## 许可证
+
+MIT

package/dist/backend/src/api/config-routes.d.ts

@@ -2,6 +2,6 @@ import { Router } from 'express';
 import { AuthModule } from '../auth/auth-middleware.js';
 import type { NotificationManager } from '../notification/notification-manager.js';
 import type { NotificationServiceFactory } from '../notification/notification-service-factory.js';
-import type { WsServer } from '../ws/ws-server.js';
-export declare function createConfigRoutes(authModule: AuthModule, notificationManager?: NotificationManager, notificationServiceFactory?: NotificationServiceFactory, wsServer?: WsServer): Router;
+import type { InstanceManager } from '../instance/instance-manager.js';
+export declare function createConfigRoutes(authModule: AuthModule, notificationManager?: NotificationManager, notificationServiceFactory?: NotificationServiceFactory, instanceManager?: InstanceManager): Router;
 //# sourceMappingURL=config-routes.d.ts.map

package/dist/backend/src/api/config-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-routes.d.ts","sourceRoot":"","sources":["../../../../backend/src/api/config-routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAKjC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAexD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AACnF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAC;AAClG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA+GnD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,mBAAmB,CAAC,EAAE,mBAAmB,EACzC,0BAA0B,CAAC,EAAE,0BAA0B,EACvD,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CA4LR"}
+{"version":3,"file":"config-routes.d.ts","sourceRoot":"","sources":["../../../../backend/src/api/config-routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAKjC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAoBxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AACnF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAC;AAClG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AA+GvE,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,mBAAmB,CAAC,EAAE,mBAAmB,EACzC,0BAA0B,CAAC,EAAE,0BAA0B,EACvD,eAAe,CAAC,EAAE,eAAe,GAChC,MAAM,CA+MR"}