Peanut

在手机上远程控制 Claude Code 的 CLI 工具。

功能

• 在终端启动 Claude Code 并生成配对二维码
• 通过 iOS App 扫码连接，实现远程控制
• 实时同步 Claude Code 的输出到手机
• 支持在手机上发送指令、处理权限请求

安装

npm install -g peanut-cc@latest

注意：使用 @latest 确保安装最新版本，避免 npm 缓存问题。

快速开始

1. 安装 Hooks（首次安装必须）

peanut install-hooks

重要：Hooks 配置让 Claude Code 能够将状态同步到手机。首次安装后只需执行一次。

2. 启动会话

# 启动会话（显示配对二维码）
peanut start

# 自定义会话名称
peanut start -n "我的项目"

# 使用自定义中继服务器（推荐敏感项目使用）
peanut start -s "wss://your-relay-server.com"

3. 用 App 扫码连接

打开 Peanut App，扫描终端中的二维码即可配对。

其他命令

# 检查 Hooks 配置状态
peanut check-hooks

# 查看 Hooks 配置内容（不安装）
peanut install-hooks --show

配套 App

扫描二维码需要配套的 iOS App：Peanut

App 功能：

• 扫码快速配对
• 实时查看 Claude Code 输出
• 远程发送指令
• 一键处理权限请求

工作原理

┌─────────────┐                      ┌─────────────┐
│   iOS App   │  ◄───── 同步 ──────► │ peanut start│
│             │      WebSocket       │             │
└─────────────┘                      └──────┬──────┘
       │                                    │ PTY
       │                             ┌──────▼──────┐
       ▼                             │ Claude Code │
┌─────────────┐                      └─────────────┘
│ 云端中继服务 │
└─────────────┘

1. peanut start 启动 Claude Code，包装在 PTY 中
2. 解析输出为结构化消息，通过 WebSocket 发送
3. 云端中继服务转发消息到 iOS App
4. App 可发送指令回传到 CLI

安全说明

数据传输机制

默认情况下，CLI 使用作者提供的公共中继服务器。这意味着：

| 数据类型 | 是否经过中继 | 是否存储 | |----------|--------------|----------| | Claude Code 输出 | ✅ 是 | ❌ 否（仅转发） | | 用户输入指令 | ✅ 是 | ❌ 否（仅转发） | | 会话密钥 | ✅ 是 | ✅ 是（用于配对验证） | | 代码/文件内容 | ✅ 是 | ❌ 否（仅转发） |

重要提示：

• 消息内容不会被持久化存储，仅实时转发
• 但消息以明文形式经过中继服务器
• 中继服务运营者理论上可以查看传输内容
• 目前没有端到端加密

何时应该自建中继服务？

建议在以下场景自建中继服务：

• 🔐 处理包含敏感信息的项目（API 密钥、密码、私有代码）
• 🏢 企业/商业项目
• 📋 有合规要求的场景（GDPR、数据本地化）
• 🔒 对隐私有较高要求

公共中继服务适合：

• 🧪 个人学习、测试用途
• 📖 开源项目开发
• 🎯 快速体验产品功能

自建中继服务

如果你需要完全控制数据传输，可以部署自己的中继服务。

前置要求

• Cloudflare 账号（免费）
• Node.js >= 18
• Wrangler CLI

部署步骤

1. 克隆仓库

git clone https://github.com/alchaincyf/cc-connect.git
cd cc-connect/relay-server

2. 安装依赖

npm install

3. 登录 Cloudflare

npx wrangler login

4. 修改配置

编辑 wrangler.toml，修改 name 为你自己的服务名：

name = "my-peanut-relay"  # 改成你的名字

5. 部署

npm run deploy

部署成功后会显示你的服务地址，类似：

https://my-peanut-relay.你的用户名.workers.dev

6. 使用自建服务

peanut start -s "wss://my-peanut-relay.你的用户名.workers.dev"

Cloudflare 免费额度

| 资源 | 免费额度 | 说明 | |------|----------|------| | Workers 请求 | 10 万次/天 | 足够个人使用 | | Durable Objects | 100 万次读写/月 | 用于会话管理 | | 存储 | 1 GB | 仅存储会话密钥 |

对于个人使用，免费额度完全足够。

免责声明

公共中继服务

本项目提供的公共中继服务（wss://cc-connect.alchaincyf.workers.dev）：

1. 按原样提供，不保证可用性、稳定性或安全性
2. 不承诺数据的保密性，尽管我们不会主动记录或查看
3. 不适用于生产环境或敏感数据传输
4. 可能随时停止服务或更改条款
5. 不承担因使用本服务造成的任何损失

用户责任

使用本工具即表示你理解并同意：

• 你对传输的内容负全部责任
• 不得传输违法、侵权或有害内容
• 敏感项目应自建中继服务
• 遵守当地法律法规

建议

• 🔐 敏感项目请务必自建中继服务
• 🔑 不要在不信任的网络环境使用
• 📝 定期检查和轮换可能暴露的密钥

系统要求

• Node.js 18.x 或 20.x (LTS)
  • 推荐使用 LTS 版本，非 LTS 版本（如 v21、v23）可能遇到原生模块编译问题
  • 如遇 posix_spawnp failed 错误，请切换到 Node LTS 版本
• 已安装 Claude Code (npm install -g @anthropic/claude-code)
• macOS/Linux（Windows 暂不支持）

常见问题

Q: 安装后运行报错 posix_spawnp failed

A: 这是因为 node-pty 原生模块与当前 Node 版本不兼容。解决方案：

# 方案 1: 切换到 Node LTS 版本（推荐）
nvm install 20
nvm use 20
npm install -g peanut-cc

# 方案 2: 手动重新编译（需要 Xcode 命令行工具）
cd $(npm root -g)/peanut-cc
npm rebuild node-pty

开源协议

MIT

作者

花叔 (@alchaincyf)

问题反馈

• GitHub Issues: https://github.com/alchaincyf/cc-connect/issues