# remote-claude-agent

**Repository Path**: nathanjoy/remote-claude-agent

## Basic Information

- **Project Name**: remote-claude-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Remote Claude Agent

> Hermes Agent 作为 orchestrator,通过 SSH + JSON-lines 协议,在远端服务器上 spawn
> 真实的 Claude Code CLI 流式执行编码任务。Hermes 自己调度、检查、续接、总结,
> 最后通过飞书 (Lark) interactive card 把结果发回给你。

把"远端 Claude 当 worker,hermes 当 orchestrator"这件事做成可复制、可二次开发的项目。

---

## 这是什么

你(用飞书)发:`[远端] 在 ~/chip_vi/.../xspi 加 OPI Read 8D-133M 模式`

Hermes 自动:
1. 解析任务,探测工作目录
2. 写入 memory 记录任务
3. SSH 到远端服务器 → spawn 真实 `claude` CLI(流式输出)
4. 实时收集 claude 的工具调用、文本、思考过程
5. claude 跑完后,hermes 拉 git diff / 跑测试,自动检查
6. 如果失败,hermes 用同一个 `session_id` 续接 claude,让 claude 自己修
7. 最多迭代 3 次,最后生成飞书 interactive card 发回给你

整个过程你不需要敲任何终端命令,也不需要自己 ssh 到服务器。

## 它不是什么

- **不是** 浏览器 UI 渲染工具 — 你不会看到 claude 的终端画面(没必要,只需要总结)
- **不是** Claude Code 替代品 — 它就是把 Claude Code 当一个真实 worker 调度
- **不是** 多 worker 并行框架 — 当前 1 个 hermes orchestrator + 1 个 claude worker(hive 那种多 agent 模式留作未来扩展)
- **不是** 模型网关 — Claude Code 自己的会话、OAuth、模型选择全部自己管

## 跟 hive 的关系

受 [tt-a1i/hive](https://github.com/tt-a1i/hive) 项目启发,但简化 90%:

| 维度 | hive | 本项目 |
|---|---|---|
| 浏览器 PWA UI | ✓ | ✗ |
| PTY 双向 WebSocket | ✓ | ✗(用 stream-json 替代) |
| 多 worker 并行 | ✓ | ✗(单 worker) |
| xterm.js 终端渲染 | ✓ | ✗ |
| 飞书集成 | ✗ | ✓ |
| Hermes Agent 集成 | ✗ | ✓ |
| **部署复杂度** | 139 个 TS 文件 / npm 全家桶 | **7 个 Python 文件,纯 stdlib** |

Hive 是大而全的多 CLI agent 协作平台,本项目是"用 hermes 当 orchestrator 调一个远端 claude worker"的最小可用实现。

完整对比见 [docs/hive-comparison.md](docs/hive-comparison.md)。

## 架构

```
┌────────────────────────────────────────────────┐
│   飞书 (Nathan)  ← 你发 [远端] <任务>           │
└──────────────┬─────────────────────────────────┘
               │ 飞书事件
               ▼
┌────────────────────────────────────────────────┐
│  Hermes Agent (WSL 本机)                         │
│  ┌────────┐  ┌─────────┐  ┌──────────────┐    │
│  │ memory │  │  OpenViking │ │ 飞书发送器  │    │
│  └────────┘  └─────────────┘  └──────────────┘    │
│  ┌──────────────────────────────────────────┐  │
│  │ RemoteClaude SDK (Python)                │  │
│  │   - 解析任务 → 自动探测 cwd              │  │
│  │   - SSH spawn 远端 bridge                │  │
│  │   - 收集 stream-json 事件                │  │
│  │   - 检查 → 续接 → 总结                   │  │
│  └──────────────────────────────────────────┘  │
└──────────────┬─────────────────────────────────┘
               │ SSH (stdin/stdout JSON-lines)
               ▼
┌────────────────────────────────────────────────┐
│  远端服务器 (jian.ning@10.73.34.151)            │
│  ┌──────────────────────────────────────────┐  │
│  │ claude-bridge.py (sidecar, stdlib only)  │  │
│  │   - 收 start cmd → spawn claude          │  │
│  │   - 读 claude stream-json → envelope     │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │ claude CLI (真实进程)                     │  │
│  │   --output-format stream-json            │  │
│  │   --dangerously-skip-permissions          │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘
               ▲
               │ 飞书 interactive card (结果回传)
               │
┌──────────────┴─────────────────────────────────┐
│   飞书 (Nathan)  ← 收到带 diff + cost 的卡片   │
└────────────────────────────────────────────────┘
```

## 仓库结构

```
remote-claude-agent/
├── README.md                      ← 你正在看
├── LICENSE                        ← MIT
├── .gitignore
├── bridge/
│   └── claude-bridge.py           ← 部署到远端的 sidecar (Python stdlib only)
├── sdk/
│   └── remote_claude.py           ← 本地 Python SDK (RemoteClaude class)
├── feishu/
│   ├── feishu_send.py             ← 飞书卡片生成 + 发送封装
│   └── card-templates.md          ← 卡片模板示例
├── hermes-skill/
│   └── SKILL.md                   ← Hermes skill 定义(安装到 ~/.hermes/skills/remote-claude-agent/)
├── references/
│   ├── bridge-protocol.md         ← bridge 输入输出协议详细
│   └── feishu-card-spec.md        ← 飞书 interactive card schema
├── docs/
│   ├── architecture.md            ← 架构详解 + 设计权衡
│   ├── hive-comparison.md         ← 跟 hive 项目逐项对比
│   └── troubleshooting.md         ← 常见问题 + 排查路径
└── examples/
    ├── 01-basic-call.sh           ← 最简单的一次性调用
    ├── 02-resume-session.sh       ← 续接 session
    ├── 03-feishu-card.py          ← 飞书发完整卡片
    └── 04-iter-with-check.py      ← 自动检查 + 修复循环
```

## 快速开始

### 前置

- WSL / Linux / macOS 本地机器
- 远端服务器(任意 SSH 可达,本项目默认 `jian.ning@10.73.34.151`)
- 远端已安装 Claude Code CLI(`/usr/bin/claude`,版本 ≥ 2.1)
- 本地 Python ≥ 3.8
- 本地已安装 `lark-cli`(飞书 CLI)
- 已配好 SSH key 免密登录远端

### 1. 部署远端 sidecar

```bash
# 在远端创建目录
ssh jian.ning@10.73.34.151 'mkdir -p ~/.hermes/bin'

# 上传 bridge
scp bridge/claude-bridge.py jian.ning@10.73.34.151:~/.hermes/bin/
ssh jian.ning@10.73.34.151 'chmod +x ~/.hermes/bin/claude-bridge.py'
```

### 2. 安装 Hermes skill(可选)

如果你用 Hermes Agent:

```bash
mkdir -p ~/.hermes/skills/remote-claude-agent
cp -r hermes-skill/* ~/.hermes/skills/remote-claude-agent/
cp -r sdk feishu references ~/.hermes/skills/remote-claude-agent/
# 注意:scripts/ 目录需要,因为 SDK 和 feishu 脚本在 scripts/ 下
```

新会话时 hermes 会自动加载这个 skill,描述为:

> Hermes 作为总入口,通过 SSH + JSON-lines 协议,在远端服务器上 spawn 真实
> Claude Code CLI 流式执行编码任务。Use when 飞书/用户消息含 `[远端]` 或
> `/remote` 前缀。

### 3. 直接用 SDK(不需要 Hermes)

```bash
# 直接调 SDK
python3 sdk/remote_claude.py "say hi in one word" --cwd /tmp --max-turns 3
```

输出结构化 JSON:

```json
{
  "ok": true,
  "exit_code": 0,
  "session_id": "e929a7b4-a043-4810-86b6-8a0d4f0744b8",
  "cwd": "/tmp",
  "duration_seconds": 5.7,
  "duration_ms_claude": 3346,
  "total_cost_usd": 0.145,
  "num_turns": 1,
  "text": "Hi",
  "tool_calls": [],
  "num_tool_calls": 0
}
```

### 4. 飞书发卡片

```bash
# 见 examples/03-feishu-card.py
python3 examples/03-feishu-card.py
```

## 关键设计

### 为什么用 JSON-lines 而不是 PTY?

| | PTY (hive 模式) | JSON-lines (本项目) |
|---|---|---|
| 实时输出 | ✓ | ✓ |
| 中途干预 | ✓ (stdin 写 PTY) | ✓ (下次 spawn 带 resume_id) |
| 多轮对话 | 需要自管 PTY 状态 | `--resume <sid>` 一行命令 |
| 工具调用可见 | 需要解析 ANSI 转义 | 原生 stream-json 字段 |
| 渲染复杂度 | 需要 xterm.js + WebSocket | 终端直接打印即可 |
| **适合场景** | 用户要看完整终端画面 | orchestrator 只要事件 |

我们(hermes)不是要给用户渲染终端画面,只是要"claude 跑完告诉我结果 + 中间关键节点"。
JSON-lines 是为这个场景优化的协议。

### 为什么每次任务新 spawn 一个 SSH 连接?

简单可靠。代价是 ~500ms 连接开销(任务本身 1-30 分钟,可忽略)。

如果未来需要保持长连接(比如秒级高频任务),可以扩展成 keepalive 模式。但当前不是瓶颈。

### 为什么不用 claude 的 OAuth 自动续期?

不需要。Claude Code CLI 自己管 OAuth session。本项目只是 spawn 它,管不到它内部。

### 为什么不直接用 claude -p?

`claude -p` 是 fire-and-forget:
- 没有实时进度
- 没有工具调用可见性
- 没有中途干预
- 失败只能看到 exit code,看不到根因

`claude --output-format stream-json` 是结构化流式:
- 实时吐事件,hermes 可以选择性打印
- 每个 tool_use / tool_result 单独事件
- claude 自己暴露 session_id 用于续接
- 失败时 error 事件 + 详细原因

## 已验证场景

- [x] 远端 bridge 启动 + claude spawn
- [x] 流式 JSON 输出采集(33 个事件,text / tool_use / tool_result / result)
- [x] session_id 捕获 + 续接
- [x] 真实文件操作(创建、编辑、删除)
- [x] 飞书 interactive card 发送
- [x] 飞书消息撤回(注意:会留一条"机器人撤回了一条消息"的痕迹)

## 已知限制

1. **单 worker**: 1 个 hermes 同时只能跑 1 个远端 claude(进程级串行)
2. **没有 diff 审查**: 当前 SDK 不自动跑 git diff 审查,需要 hermes 在上层加
3. **没有编译/测试 driver**: 同上,SDK 只负责 spawn claude
4. **飞书卡片无法显示完整长 diff**: 飞书单元素上限 5000 字符,长 diff 需要折叠或外链
5. **SSH 断线 = 任务死**: 远端 claude 跟着 SSH 一起死,需要重连后 `--resume`

## 路线图

- [ ] 自动 diff 审查(driver 层,SDK 内)
- [ ] 自动测试运行(driver 层,SDK 内)
- [ ] 多 worker 并行(hermes 层)
- [ ] Web UI 集成(hermes-web-ui)
- [ ] 支持更多 CLI agent(Codex, OpenCode, Gemini)— 复用 bridge 协议

## License

MIT

## 作者

Nathan (宁建) — Gua Semi 解决方案部平台软件

## 相关项目

- [tt-a1i/hive](https://github.com/tt-a1i/hive) — 多 CLI agent 协作 UI,本项目的主要灵感来源
- [Hermes Agent](https://hermes-agent.nousresearch.com/docs) — orchestrator
- [Claude Code](https://docs.claude.com/en/docs/claude-code) — worker