GraphCode：多编码 Agent 会话编排

项目简介

GraphCode 是一款 macOS 应用，用来把多个真实的 CLI 编码 Agent 会话组织成一张可视化图。你在终端里通常只能跑一个编码 Agent 会话，GraphCode 让你同时跑十个：它们彼此相连、可以无人值守运行，而每一段仍然是你可以随时接入并在中途纠正的实时终端，不是无头的后台任务。

每个节点是某个真实 CLI 编码 Agent 会话中的一个工作单元，可选 Claude Code、GitHub Copilot CLI、Codex、OpenCode 或 pi，且每个循环可单独指定。每条边是两个循环之间的交接、消息或派生，边本身不关心两端分别是哪个 Agent——例如 Codex 循环可以把工作交给 Claude Code 循环，后者再给 Copilot 循环发消息。

主要功能

四种循环类型——每种都是「一个 Agent 反复运行」，区别在于你把什么交出去：

循环类型	你交出的东西	运行到何时	例子
Turn-based（回合式）	检查	由你结束——每回合在会话内暂停等你审阅	想逐步查看的重构
Goal-based（目标式）	停止条件	目标达成（可选 shell 谓词退出码为 0）	「修好构建」——make test 通过即完成
Time-based（时间式）	触发器	由你停止——节奏写在 prompt 里（/loop 1h …）	每小时处理一次 issue
Composite（复合式）	prompt	由子图端到端跑完	自行规划步骤的流水线

两个关键设计：

• GraphCode 自身不做调度。 时间式循环的重复发生在会话内部，由 Agent 自己的 /loop 技能写进 prompt，守护进程只负责让会话活着。因此运行中的循环是一个你可以接入并纠正的东西，而不是某个早已在别处跑完的任务。
• 会话比一切活得更久。 每个循环的终端都是一个 zmx 会话，退出应用、重启机器都不会丢；后端会话 ID 会被持久化，重新启动时用 --resume 恢复对话，而不是另开一个副本。

组成部分：

组件	说明
graphcode.app	界面——项目侧边栏、图画布，以及带标签页和分屏的单循环终端工作区
graphcoded	后台守护进程（launchd agent），持有每个项目的图、触发交接边、轮询目标谓词，无论应用是否打开都维持无人值守会话
graphcode	面向同一守护进程的 CLI
zmx	第三方会话守护进程，维持每个循环的 PTY
GhosttyKit	第三方终端引擎，渲染每个终端表面

工作区（Workspace）：通过 File ▸ Workspace ▸ New Workspace… 可以再开一个 GraphCode，拥有完全独立的项目、循环和终端会话，适合把不相干的工作线分开。工作区就是一个目录 ~/.graphcode-<name>，与默认的 ~/.graphcode 并列，各有自己的图和 graphcoded，彼此不共享任何东西。⌥⌘1 … ⌥⌘9 切换工作区，⌘`` 切到下一个，⌥⌘N` 新建。注意它和循环内部的「终端工作区」（一个循环里的标签页与分屏）不是一回事。

安装与使用

需要 macOS 15+ 的 Apple Silicon（arm64），并且 PATH 上至少有一个 Agent CLI：claude、copilot、codex、opencode 或 pi。GraphCode 启动循环指定的那个，自身不捆绑任何一个。

brew install --cask scgopi/graphcode/graphcode

也可以从最新 .dmg 把 GraphCode 拖进 Applications。发布版经过 Developer ID 签名和公证。

使用流程：

1. 添加项目 —— 侧边栏的 ⊕ 菜单：本地文件夹、从 URL 克隆，或通过 SSH 连接远程仓库（服务器上需要密钥认证和 zmx；循环在服务器上跑，这台 Mac 负责操控）。
2. 创建循环 —— 画布上的 ⊕。写 prompt、选它运行的 Agent（未改 Settings ▸ New loops use 时为 Claude Code），然后 Create；类型选择器会说明每种类型交出什么，目标式循环的完成检查有 Test 按钮，可按守护进程的方式试跑。在 shell 中，graphcode node create 用 --backend claudeCode | copilotCLI | codex | openCode | pi 做同样的选择；未指定 Agent 就创建子循环的循环，会把自身的 Agent 传下去。
3. 打开它 —— 点击节点进入该循环的终端工作区：标签页、分屏、⌘K 跳到任意循环、⌘⇧R 依次走过正在等你的循环（见快捷键）。你接入的是活着的会话。
4. 连接循环 —— 在节点之间拖拽。边默认是交接（源循环 resolve 时触发），也可以是消息或派生，并可带条件和循环保护。两端的 Agent 可以不同。

CLI 从 graphcode projects 和 graphcode --help 开始；重试前先用 status，用 node send --follow-up 避免打断当前回合，做 PTY 恢复前先 reap --dry-run。

若要固定 Copilot CLI 版本，需在每台运行 Copilot 的机器（包括远程主机）上安装该版本，然后在 Settings ▸ Preferred versions ▸ Copilot CLI 中填入版本号；不使用应用时，可在 ~/.graphcode/settings.json 里设置 "copilotPreferredVersion": "1.0.84-5"，每次启动读取，无需重启守护进程。清空该字段即回到 CLI 自身的版本选择。

注意事项

• GraphCode 不安装任何 Agent CLI；主机上没有安装的版本不会在循环启动时出现。
• 时间式循环依赖 Agent 的 /loop 技能；Codex、OpenCode 和 pi 没有该技能，需要先在设置中打开实验性的 Daemon heartbeat。
• 状态存放在 ~/.graphcode/（图、最近记录、布局、守护进程 socket 与日志、已安装的二进制），不会写进你打开的任何项目文件夹。
• 许可证为 FSL-1.1-MIT：可自托管、修改、再分发，但不允许据此发布竞争性商业产品，每个版本在发布两年后转为纯 MIT；GraphcodeKit/ 与 graphcode-cli/ 始终为 MIT。
• 从源码构建需要 mise 与子模块，先跑 make doctor 检查前置条件；Windows 移植目前仍是 preview，不作为正式支持平台。

---

本作品整理自 GitHub 开源项目 scgopi/GraphCode，原作者 @scgopi。中文介绍由 AI 根据项目 README 整理，以原仓库为准。