claude-remote
v0.6.0
Published
Remote control bridge for Claude Code REPL - drive from phone/WebUI
Readme
Claude Remote
在手机上远程操控 Claude Code —— 随时随地写代码、审批权限、切换模型。
这是什么？
一个轻量级的远程控制桥接器，让你可以通过 Android App 连接到电脑上运行的 Claude Code，实现：
- 💬 远程对话 —— 发消息、看回复、完整的 Markdown 渲染
- 🔧 工具调用可视化 —— 实时查看 Claude 正在读哪个文件、执行什么命令
- 🔐 权限审批 —— 手机上一键 Allow / Deny
- 🔄 模式切换 —— Default / Plan / Accept Edits / Bypass
- 📱 斜杠命令 —— /model /compact /clear /cost /help
快速开始
1. 安装
npm install -g claude-remote2. 启动
在任意项目目录下运行：
claude-remote会在当前目录启动 Claude Code 并开启远程控制服务（默认端口 3100）。
参数透传
claude-remote 支持将参数直接传递给 Claude Code CLI：
# 恢复指定会话
claude-remote --resume <session-id>
# 继续最近的对话
claude-remote -c
# 指定模型
claude-remote --model opus
# 组合使用
claude-remote --model sonnet -c
# 指定工作目录 + 恢复会话
claude-remote /path/to/project --resume abc123不兼容参数（
--output-format、--version等非交互模式参数）会被自动过滤并在启动 banner 中提示。
指定端口：
PORT=8080 claude-remote3. 安全认证
claude-remote 内置 Token 鉴权机制，防止未授权的客户端控制你的 Claude Code。
工作原理
- 首次启动时自动生成 Token —— 桥接器启动后会自动生成一个随机 Token，持久化到
~/.claude-remote-token文件，并在启动 banner 中显示 - 客户端必须提供 Token —— App 在添加/编辑服务器时填入 Token，连接时通过
hello握手消息发送给服务器 - 服务器验证 Token —— 使用
crypto.timingSafeEqual安全比对，防止时序攻击。验证通过后才发送会话数据 - 认证超时 —— 连接后 5 秒内未完成认证将被自动断开（close code 4002）
- 认证失败 —— Token 不匹配时连接立即关闭（close code 4001），App 会弹出编辑对话框提示修正
Token 来源优先级
| 优先级 | 来源 | 说明 |
|--------|------|------|
| 1 | --token <value> | CLI 参数，最高优先级 |
| 2 | CLAUDE_REMOTE_TOKEN 环境变量 | 适合 CI/脚本场景 |
| 3 | ~/.claude-remote-token 文件 | 自动生成并持久化，首次启动时创建 |
# 使用自定义 Token
claude-remote --token my-secret-token
# 通过环境变量
CLAUDE_REMOTE_TOKEN=my-secret-token claude-remote
# 默认行为：自动生成并保存到 ~/.claude-remote-token
claude-remote禁用认证
⚠️ 仅在安全网络环境下使用，如本地开发或 VPN 内网。
# CLI 参数
claude-remote --no-auth
# 环境变量
NO_AUTH=1 claude-remoteApp 端配置
在连接中心添加或编辑服务器时，填入 Token 字段即可。Token 输入框支持密码显示/隐藏切换。认证失败时 App 会自动弹出编辑对话框，方便修正 Token。
4. App 连接
安装 Android App 后，在连接中心添加服务器地址连接。根据你的网络环境，有以下三种方式：
方式一：局域网直连
手机和电脑在同一 Wi-Fi 下，直接输入电脑内网 IP：
ws://<电脑IP>:3100适合在家或办公室使用，最简单、延迟最低。
方式二：Tailscale 组网
通过 Tailscale 虚拟局域网，手机和电脑不在同一网络也能连接。
- 电脑和手机都安装 Tailscale 并登录同一账号
- 在 Tailscale 管理面板查看电脑的 Tailscale IP（通常是
100.x.x.x） - App 中输入：
ws://<Tailscale IP>:3100适合跨网络使用，无需公网暴露，安全可靠。
方式三：Cloudflare Tunnel 公网访问
通过 Cloudflare Tunnel 将本地服务暴露到公网。
- 安装
cloudflared并登录 - 启动隧道：
cloudflared tunnel --url http://localhost:3100- 获得一个
https://xxx.trycloudflare.com的地址 - App 中输入（注意用
wss://）：
wss://xxx.trycloudflare.com适合在外网或移动网络下远程控制，支持 HTTPS/WSS 加密。
5. 编译 Android App
cd app
npm install
npx tauri android init
npx tauri android dev架构
┌─────────────┐ WebSocket ┌──────────────┐ PTY ┌────────────┐
│ Android App│ ◄──────────────► │ server.js │ ◄──────────► │ Claude Code│
│ │ ws://ip:3100 │ (Bridge) │ node-pty │ (CLI) │
└─────────────┘ └──────────────┘ └────────────┘
│
│ 读取 JSONL transcript
▼
~/.claude/projects/server.js 是核心桥接层：
- 通过
node-pty启动并管理 Claude Code CLI 进程 - 监听
~/.claude/projects/下的 JSONL transcript 文件，实时解析事件 - 通过 WebSocket 将事件广播给所有连接的客户端
- 转发客户端输入到 Claude PTY
功能特性
| 功能 | 说明 |
|------|------|
| 实时对话 | 完整 Markdown + 代码高亮渲染 |
| 工具调用追踪 | 折叠式 step group，shimmer 加载动效 |
| 权限队列 | 批量审批，计数器显示剩余数量 |
| 模式切换 | 四种模式一键切换，彩色状态标识 |
| Token 鉴权 | 自动生成 Token，timingSafeEqual 安全比对，防止未授权访问 |
| 对话压缩 | /compact 带 spinner 遮罩，压缩完自动恢复 |
| 斜杠命令菜单 | 输入 / 弹出命令面板 |
| 模型切换 | 底部面板选择，toast 即时反馈 |
| 断线重连 | 自动重连 + 事件回放，不丢消息 |
| 图片上传 | 手机拍照/选图发送到 Claude Code |
| 代码 Diff | GitHub 风格行内高亮 |
| 安卓适配 | 安全区、虚拟键盘、大触摸目标 |
依赖
- Node.js >= 18
- node-pty —— PTY 终端模拟
- ws —— WebSocket 服务
- Tauri 2.0 —— Android App（需要 Rust 工具链）
TODO
本项目看到 Claude Code 官方远程控制，可惜不支持 API 调用的模式，于是空闲时间摸鱼用 vibing code 写的小东西，目前处于快速迭代阶段。
- [x] 提问与计划远程弹窗（AskUserQuestion / ExitPlanMode 远程交互）
- [x] 自动审批命令模式
- [x] Claude Code ToDo App 渲染
- [x] 美化部分样式
- [x] 代码 diff 查看
- [x] 缓存机制 —— 避免每次 App 重连全量回放
- [x] App 支持图片上传
- [x] /命令指令及样式美化
- [x] npm 包化 ——
npm install -g claude-remote全局安装，claude-remote一键启动 - [x] AI 截图显示 —— 工具返回的图片（如 Playwright 截图）全宽渲染，点击全屏查看
- [x] CLI 参数透传 ——
claude-remote --resume xxx等参数直接传给 Claude Code，自动过滤不兼容参数 - [x] 多客户端同步 —— 多台设备同时连接，Working 状态和消息实时同步
- [x] 会话生命周期管理 —— 通过 SessionStart Hook 自动绑定会话 ID，支持 /clear 切换检测
- [ ] Tool Use 状态渲染（进行中 / 成功 / 失败）