Ur-Agent-Team

# Agent Hub 1.2 **Local-first multi-agent orchestration on one machine — any agent can be the "brain".** 🌐 **[English](#english)** · **[中文](#中文)** Agent Hub lets **any AI agent on your computer act as the orchestrator ("brain")** and dispatch tasks to the others — read the reply back, watch it live, and keep long-running work alive across editor reloads. It exposes everything as an **MCP server** (so any MCP-capable agent can drive it) plus a plain **CLI**, writes a per-brain task log you can watch in a **VS Code panel**, and ships a **one-call provisioner** that sets itself up across every agent it detects. > ⚠️ **Tested status (alpha).** The "any agent can be the brain" model is the > design. In practice it has only been **tested with the three agents on the > maintainer's machine: Claude Code, Codex, and Antigravity** (all three verified > both as brain and as target, replies returned). Other MCP hosts (Cursor, > Windsurf, opencode, Gemini CLI, …) are **not tested** — the architecture is > built to accept them via a host registry, but they are added by contribution, > not claimed to work. Real-time UI has been verified on GUI surfaces (Codex > Desktop, the VS Code agents, Antigravity IDE); pure CLI-to-CLI interactive > messaging is not fully verified. --- <a name="english"></a> ## English ### Table of contents - [What it does](#what-it-does) - [How it works](#how-it-works) - [Install](#install) - [Quick start](#quick-start) - [MCP server & tools](#mcp-server--tools) - [Dispatch modes: wait vs background](#dispatch-modes-wait-vs-background) - [Session-choice guard](#session-choice-guard) - [Durability daemon](#durability-daemon) - [Reply-return](#reply-return) - [Live streaming (Codex)](#live-streaming-codex) - [CLI reference](#cli-reference) - [Adding another agent](#adding-another-agent) - [Known limitations](#known-limitations) - [Safety model](#safety-model) - [Development](#development) ### What it does - **Any agent is the brain.** Whichever agent you're talking to (Claude Code, Codex, Antigravity) can dispatch work to the others through Agent Hub. The three have been verified as brain and as target, both directions. - **One-call setup.** `setup_agent_hub` (MCP) / `node src/cli.js setup` detects the agents on the machine and registers Agent Hub for **all** of them at once — it never provisions "just the caller". - **Dispatch + reply-return.** Send a task to another agent and get its actual reply back (`delegate_to_codex` / `delegate_to_claude` / the Antigravity tools), then `read_task` to collect a result from any brain's board. - **Subagent-style by default.** `wait:true` blocks, returns the reply inline, and you auto-continue — like a native subagent. `wait:false` queues to a durable daemon for long/background work. - **Survives reloads.** Background jobs run in a daemon **outside** the editor's process tree, so a VS Code window reload doesn't kill in-flight work. - **Ask before hijacking a session.** Dispatching without a chosen session returns `needs-session-choice` so the brain asks the user which session to join. - **Live task board.** Every dispatch writes to a per-brain board shown live in the **Agent Hub Panel** VS Code extension. - **Codex extras.** Resume a real Codex thread, stream the reply token-by-token into the Codex UI, and use Codex's browser-takeover on your live Chrome. ### How it works ```text Any brain (Claude Code / Codex / Antigravity / any MCP client, or the CLI) │ MCP tool (delegate_to_* / setup_agent_hub / read_task) ▼ Agent Hub provision/ → detect agents, write MCP config + install extensions per-brain board → <root>/brains/<brain>/{events.jsonl, tasks/<id>/} wait:true → run inline, return reply now (subagent-style) wait:false → enqueue to <root>/jobs, run by the daemon │ │ ▼ ▼ target agent durability daemon (outside the editor process tree, (Codex / Claude / survives window reloads; drains jobs concurrently) Antigravity) │ ▼ ▼ reply.md + task.json ◄── read_task(taskId) (resolves across any brain's board) ``` Each brain gets its **own board** under `<root>/brains/<brain>/`, so two concurrent brains never mix logs. The panel in the same window resolves the same board. See `docs/architecture.md` and `docs/orchestration.md` for detail. ### Install Requirements: **Node ≥ 20**. No `npm install` — Agent Hub uses only Node built-ins. For the Codex path you also need the **Codex CLI** on `PATH`. **One-shot setup (recommended).** From your clone: ```text node ./src/cli.js setup # dry-run: shows what would change, for every detected agent node ./src/cli.js setup --apply # writes MCP config + installs the panel/companion extensions ``` Or, from a brain that already has Agent Hub, call the **`setup_agent_hub`** MCP tool (dry-run by default; `apply:true` to write). It covers Codex, Claude Code and Antigravity in one call, is idempotent, and backs up any file it changes (`.bak`). It **cannot restart the agents** — restart/reload each host listed in the returned `restartsRequired`. **Manual fallback** (per agent) — see `docs/install.md`. In short: - Codex Desktop → add `[mcp_servers.agent_hub]\ncommand = '<clone>\agent-hub-mcp.cmd'` to `~/.codex/config.toml`, restart. - Claude Code → add `agent-hub` to `mcpServers` in `~/.claude.json` (or a project `.mcp.json`), reload. - Antigravity → install the companion from `extensions/antigravity-companion`, reload. > **Paths:** replace `<clone>` / `C:\agent-hub` with your own clone location. > The `.cmd` wrappers are path-portable (`%~dp0`). After setup run > `node ./src/cli.js doctor` to self-check Node, the CLIs, the daemon, and which > agents still need provisioning. Relay users (e.g. reclaude): set > `AGENT_HUB_CLAUDE_CLI=reclaude` (or let the wrappers auto-detect it). ### Quick start ```powershell cd C:\agent-hub # See what's on this machine and what setup would do node .\src\cli.js setup # Provision everything detected node .\src\cli.js setup --apply # Environment self-check node .\src\cli.js doctor # List sessions of each agent (to choose one to resume) node .\src\cli.js codex-threads node .\src\cli.js sessions node .\src\cli.js antigravity-sessions ``` From inside a brain, dispatch via the MCP tools (e.g. `delegate_to_codex`, `delegate_to_claude`) — dry-run by default, `open`/`execute`/`wait` to act. ### MCP server & tools Run manually: `C:\agent-hub\agent-hub-mcp.cmd` · Smoke test: `C:\agent-hub\examples\mcp-smoke.ps1` | Tool | Purpose | |------|---------| | `setup_agent_hub` | Detect the agents on this machine and register Agent Hub for ALL of them. Dry-run by default; `apply:true` to write. Reports `restartsRequired`. | | `delegate_to_codex` | Delegate to Codex; returns its reply. `open` to dispatch, `threadId` to resume, `wait` for sync vs background. | | `delegate_to_claude` | Run a Claude worker (`claude -p` / relay) and return its reply. `resume <sessionId>` targets a session; `newSession` to start fresh. | | `delegate_to_antigravity` | Mirror/send a dispatch into an Antigravity conversation via agentapi (`execute` to send). | | `send_to_active_antigravity_panel` | Send through Antigravity's active Agent panel and best-effort read its reply (`expectToken`). | | `create_antigravity_conversation` | Explicit new-conversation escape hatch for Antigravity. | | `read_task` | Fetch a task's reply + package by `taskId` — resolves across **any** brain's board (works after reloads / for another brain's task). | | `list_codex_threads` / `list_claude_sessions` / `list_antigravity_sessions` | Enumerate sessions to choose one to resume. | | `create_handoff` | Build a compact handoff package from a Claude transcript. | All dispatch tools emit events to the per-brain board, shown live in the **Agent Hub Panel** (`extensions/agent-hub-panel`, command "Agent Hub: Open Panel"). ### Dispatch modes: `wait` vs background `delegate_to_codex` / `delegate_to_claude` take a `wait` flag: - **`wait: true` (default) — subagent-style.** Blocks, returns the reply inline, and you auto-continue to the next step with zero user interaction. Best for short/medium subtasks and multi-step orchestration. - **`wait: false` — background.** Enqueues to the durability daemon, returns a `taskId` immediately, and the daemon runs it outside the editor so it survives reloads. Collect the result later with `read_task(taskId)` once `status` is `done`. To auto-continue when it finishes, each host re-wakes differently (see the auto-wake "probe" section in `docs/orchestration.md`). ### Session-choice guard Enforced **in code**, for any brain: when a dispatch would touch a session without one chosen, the tool returns `mode:"needs-session-choice"` with the target's session list instead of silently starting/creating one. Applies to `delegate_to_codex` (`threadId`/`newThread`), `delegate_to_claude` (`resume`/`newSession`), and the Antigravity tools (`sessionId`/`newSession`); `create_antigravity_conversation` is the explicit new-conversation escape hatch. The brain must then ask the user which session to join and re-call with the choice. Full spec: `docs/orchestration.md`. ### Durability daemon `wait:false` jobs go to a shared queue (`<root>/jobs/{pending,running,done,failed}`) drained by a daemon that runs **outside** the editor's process tree, so a window reload doesn't kill in-flight work (verified live through repeated reloads). It claims jobs concurrently and keeps a fresh heartbeat while long jobs run. Manage it with `node src/cli.js daemon run|install|status|stop`; `doctor` summarizes it. ### Reply-return Every dispatch persists `reply.md` (the delegate's actual answer) plus `task.json` / `conversation.md` / `events.jsonl` under the owning brain's board. `read_task(taskId)` returns the reply and **resolves the task across any brain's board**, so you can read back a result even if a different brain dispatched it or you reloaded in between. ### Live streaming (Codex) During a Codex turn the app-server emits `item/agentMessage/delta` token events. `createCodexStreamForwarder` (`src/hubCore.js`) accumulates them and pushes throttled `thread-stream-state-changed` snapshots over `\\.\pipe\codex-ipc` (`src/codexIpc.js`), so the reply appears token by token. This costs **no extra model tokens** — it only re-displays output the model already generated. ### CLI reference ```text agent-hub setup [--apply] [--force] [--agents codex,claude-code,antigravity] agent-hub doctor # environment self-check agent-hub daemon run|install|status|stop agent-hub sessions | codex-threads | antigravity-sessions [--limit 20] agent-hub handoff --session <claude-session-id> [--out handoff.json] agent-hub codex-task --prompt "..." [--thread <id>] [--new-thread] [--open | --execute] agent-hub claude-task --prompt "..." [--resume <id>] [--new-session] [--model haiku|sonnet|opus] [--cli reclaude] agent-hub antigravity-visible-send --session <id|latest> --prompt "..." [--expect-token TOKEN] agent-hub codex-ping ``` Default (no `--open`/`--execute`): dry-run, writes a local task package only. Dispatching without a chosen session returns the session list to choose from (pass `--new-thread` / `--new-session` for an explicit new one). ### Adding another agent Agent Hub ships the three verified hosts, but the provisioner is a **host registry + config-format adapters** (`src/provision/`). Adding an MCP host (Cursor, Windsurf, opencode, Gemini CLI, Zed, …) is one descriptor in `detect.js`, reusing an existing format adapter (`json-mcpServers` covers most) or adding a small new one. Contributions welcome — open a PR. We don't claim support for tools we haven't run. ### Known limitations - A **brand-new** Codex thread doesn't appear in **Codex Desktop** until reload; resume a known thread via `threadId` for live rendering. - Only Codex / Claude Code / Antigravity are tested; other MCP hosts are untested. - Pure CLI-to-CLI interactive messaging is not fully verified. - The Codex `codex://` deep link doesn't reliably raise Desktop on all installs. ### Safety model - Default commands are **dry-run**: no session creation, no automation — they only write under the hub folder. - `setup` writes to other agents' config files only with `--apply`/`apply:true`, idempotently, and backs up (`.bak`) first. - Only `--open` / `--execute` / a real dispatch crosses into another agent and can consume its model quota. - Codex browser-takeover acts on your real browser — only dispatch prompts you trust. ### Development ```powershell node --test # run the test suite ``` Source layout: `src/cli.js` (CLI), `src/mcp-server.js` (MCP), `src/hubCore.js` (orchestration), `src/provision/` (detect + setup), `src/daemon.js` + `src/jobQueue.js` (durable background jobs), `src/codexClient.js` / `src/codexIpc.js` (Codex app-server + UI streaming), `src/antigravityRegistry.js`, `src/claudeRegistry.js`. Docs in `docs/`. --- <a name="中文"></a> ## 中文 ### 目录 - [功能简介](#功能简介) - [工作原理](#工作原理) - [安装](#安装) - [快速开始](#快速开始) - [MCP 服务与工具](#mcp-服务与工具) - [派单模式：wait 与后台](#派单模式wait-与后台) - [会话选择守卫](#会话选择守卫) - [耐久 daemon](#耐久-daemon) - [回复回传](#回复回传) - [实时流式（Codex）](#实时流式codex) - [CLI 参考](#cli-参考) - [接入其它 agent](#接入其它-agent) - [已知限制](#已知限制) - [安全模型](#安全模型) - [开发](#开发) ### 功能简介 Agent Hub 让**你电脑上的任何一个 AI agent 都能充当主脑（orchestrator）**，把任务 派给其它 agent——读回它的回复、实时观察，并让长任务扛过编辑器重载。它把全部能力 暴露成 **MCP 服务**（任何支持 MCP 的 agent 都能驱动），也提供纯 **CLI**；每个主脑 有自己的任务看板，可在 **VS Code 面板**里实时查看；还带一个**一键装机器**，能给它 检测到的每个 agent 自动装好。 > ⚠️ **测试状态（alpha）。** "任何 agent 都能当主脑"是设计目标。实际**只在维护者 > 本机的三方（Claude Code、Codex、Antigravity）上测过**（三方都验证了互为主脑、双向 > 回复回传）。其它 MCP host（Cursor、Windsurf、opencode、Gemini CLI…）**未测试** > ——架构用注册表预留了接入位，但需经贡献加入，不保证可用。实时界面在 GUI 上验证过 > （Codex 桌面端、VS Code 系 agent、Antigravity IDE）；纯 CLI 与 CLI 之间的交互式 > 消息收发尚未完全验证。 ### 工作原理 ```text 任意主脑（Claude Code / Codex / Antigravity / 任意 MCP 客户端，或 CLI） │ MCP 工具（delegate_to_* / setup_agent_hub / read_task） ▼ Agent Hub provision/ → 检测 agent、写 MCP 配置 + 装扩展 每主脑看板 → <root>/brains/<brain>/{events.jsonl, tasks/<id>/} wait:true → 内联执行、立刻返回回复（子代理式） wait:false → 入队 <root>/jobs，由 daemon 执行 │ │ ▼ ▼ 目标 agent 耐久 daemon（在编辑器进程树之外，抗窗口重载； (Codex / Claude / 并发消费任务队列） Antigravity) │ ▼ ▼ reply.md + task.json ◄── read_task(taskId)（跨任意主脑看板解析） ``` 每个主脑有**独立看板** `<root>/brains/<brain>/`，两个并行主脑不会串日志；同窗口的 面板解析同一看板。细节见 `docs/architecture.md` 与 `docs/orchestration.md`。 ### 安装 要求：**Node ≥ 20**，**无需 `npm install`**（只用 Node 内置模块）。走 Codex 路径还 需 `PATH` 上有 **Codex CLI**。 **一键装机（推荐）。** 在你的 clone 目录： ```text node ./src/cli.js setup # 干跑：列出对每个检测到的 agent 会改什么 node ./src/cli.js setup --apply # 写 MCP 配置 + 安装 panel/companion 扩展 ``` 或者，从已经装了 Agent Hub 的主脑里调 **`setup_agent_hub`** MCP 工具（默认干跑； `apply:true` 才写）。它**一次覆盖** Codex / Claude Code / Antigravity，幂等，改任何 文件前先备份（`.bak`）。它**不能替你重启 agent**——按返回的 `restartsRequired` 逐个重启/重载。 **手动兜底**（逐个 agent）见 `docs/install.md`。简言之： - Codex 桌面端 → 在 `~/.codex/config.toml` 加 `[mcp_servers.agent_hub]`，重启。 - Claude Code → 在 `~/.claude.json`（或项目 `.mcp.json`）的 `mcpServers` 加 `agent-hub`，重载。 - Antigravity → 从 `extensions/antigravity-companion` 装 companion，重载。 > **路径：** 把 `<clone>` / `C:\agent-hub` 换成你自己的 clone 位置。`.cmd` 包装器 > 路径无关（`%~dp0`）。装好后跑 `node ./src/cli.js doctor` 自检 Node、各 CLI、daemon、 > 以及哪些 agent 还没装。中转用户（如 reclaude）：设 `AGENT_HUB_CLAUDE_CLI=reclaude` > （或让包装器自动检测）。 ### 快速开始 ```powershell cd C:\agent-hub # 看本机有什么、setup 会做什么 node .\src\cli.js setup # 给检测到的全部装好 node .\src\cli.js setup --apply # 环境自检 node .\src\cli.js doctor # 列出各 agent 的会话（用于选择复用） node .\src\cli.js codex-threads node .\src\cli.js sessions node .\src\cli.js antigravity-sessions ``` 在主脑里通过 MCP 工具派单（如 `delegate_to_codex`、`delegate_to_claude`）——默认 干跑，加 `open`/`execute`/`wait` 才动作。 ### MCP 服务与工具 手动运行：`C:\agent-hub\agent-hub-mcp.cmd` · 冒烟测试： `C:\agent-hub\examples\mcp-smoke.ps1` | 工具 | 作用 | |------|------| | `setup_agent_hub` | 检测本机 agent 并给**全部**装好 Agent Hub。默认干跑；`apply:true` 才写。返回 `restartsRequired`。 | | `delegate_to_codex` | 派给 Codex，返回回复。`open` 派单、`threadId` 复用、`wait` 选同步/后台。 | | `delegate_to_claude` | 跑 Claude worker（`claude -p`/中转）并返回回复。`resume <sessionId>` 定向会话，`newSession` 新开。 | | `delegate_to_antigravity` | 把派单镜像/发送进 Antigravity 会话（`execute` 才发）。 | | `send_to_active_antigravity_panel` | 经 Antigravity 激活面板发送并尽力读回回复（`expectToken`）。 | | `create_antigravity_conversation` | Antigravity 的"显式新建会话"出口。 | | `read_task` | 按 `taskId` 取回复+任务包——**跨任意主脑看板解析**（重载后 / 别的主脑派的也能读）。 | | `list_codex_threads` / `list_claude_sessions` / `list_antigravity_sessions` | 枚举会话供选择复用。 | | `create_handoff` | 从 Claude 对话记录构建精简交接包。 | 所有派单工具都会把事件写入每主脑看板，在 **Agent Hub 面板**里实时显示 （`extensions/agent-hub-panel`，命令 "Agent Hub: Open Panel"）。 ### 派单模式：`wait` 与后台 `delegate_to_codex` / `delegate_to_claude` 带 `wait` 参数： - **`wait: true`（默认）——子代理式。** 阻塞、内联返回回复，你无需业主介入即可自动 进入下一步。适合中短子任务与多步编排。 - **`wait: false`——后台。** 入队耐久 daemon，立刻返回 `taskId`，由 daemon 在编辑器 之外执行、抗重载。完成后用 `read_task(taskId)`（`status` 为 `done` 时）取结果。要在 完成时自动续上，各宿主的自唤醒方式（"探针"）见 `docs/orchestration.md`。 ### 会话选择守卫 **固化在代码里**，对任何主脑生效：当派单会动到某个会话却没指定会话时，工具返回 `mode:"needs-session-choice"` 和目标的会话列表，而不是静默新建/接管。覆盖 `delegate_to_codex`（`threadId`/`newThread`）、`delegate_to_claude` （`resume`/`newSession`）、Antigravity 工具（`sessionId`/`newSession`）； `create_antigravity_conversation` 是显式新建出口。主脑须据此询问业主接哪个会话， 再带选择重调。完整说明见 `docs/orchestration.md`。 ### 耐久 daemon `wait:false` 任务进共享队列（`<root>/jobs/{pending,running,done,failed}`），由一个 在**编辑器进程树之外**运行的 daemon 消费，因此窗口重载不会杀掉进行中的任务 （已多次重载实测存活）。它并发领单，长任务运行时也保持心跳新鲜。用 `node src/cli.js daemon run|install|status|stop` 管理；`doctor` 会汇总状态。 ### 回复回传 每次派单都会在归属主脑的看板里持久化 `reply.md`（对方的真实回复）以及 `task.json` / `conversation.md` / `events.jsonl`。`read_task(taskId)` 返回回复并 **跨任意主脑看板解析**——即便是别的主脑派的、或你中间重载过，也能读回。 ### 实时流式（Codex） Codex turn 进行中，app-server 发出 `item/agentMessage/delta` 逐字 token 事件。 `createCodexStreamForwarder`（`src/hubCore.js`）累加后，经 `\\.\pipe\codex-ipc` （`src/codexIpc.js`）节流推送 `thread-stream-state-changed` 快照，于是回复逐字出现。 这**不消耗额外模型 token**——只是把模型已生成的输出重新显示。 ### CLI 参考 ```text agent-hub setup [--apply] [--force] [--agents codex,claude-code,antigravity] agent-hub doctor # 环境自检 agent-hub daemon run|install|status|stop agent-hub sessions | codex-threads | antigravity-sessions [--limit 20] agent-hub handoff --session <claude-session-id> [--out handoff.json] agent-hub codex-task --prompt "..." [--thread <id>] [--new-thread] [--open | --execute] agent-hub claude-task --prompt "..." [--resume <id>] [--new-session] [--model haiku|sonnet|opus] [--cli reclaude] agent-hub antigravity-visible-send --session <id|latest> --prompt "..." [--expect-token TOKEN] agent-hub codex-ping ``` 默认（无 `--open`/`--execute`）：干跑，仅写本地任务包。不带会话派单时会返回会话列表 供选择（要显式新建就加 `--new-thread` / `--new-session`）。 ### 接入其它 agent Agent Hub 只发布经验证的三方，但装机器本身是**主机注册表 + 配置格式适配器** （`src/provision/`）。接一个新的 MCP host（Cursor、Windsurf、opencode、Gemini CLI、 Zed…）= 在 `detect.js` 加一条描述符，复用现有格式适配器（`json-mcpServers` 能覆盖 大多数）或加一个小的新适配器。欢迎提 PR。我们不为没跑过的工具背书。 ### 已知限制 - **新建**的 Codex 线程在 **Codex 桌面端**需重载后才显示；用 `threadId` 复用已知 线程可实时渲染。 - 仅测过 Codex / Claude Code / Antigravity；其它 MCP host 未测。 - 纯 CLI 与 CLI 之间的交互式消息收发尚未完全验证。 - Codex `codex://` deep link 在部分环境无法可靠唤起桌面端。 ### 安全模型 - 默认命令均为**干跑**：不创建会话、不做自动化——只在 hub 目录下写文件。 - `setup` 只在加 `--apply`/`apply:true` 时才改其它 agent 的配置文件，幂等，且先备份 （`.bak`）。 - 只有 `--open` / `--execute` / 真实派单会进入另一个 agent，并可能消耗其模型额度。 - Codex 浏览器接管会操作你的真实浏览器——只派发你信任的指令。 ### 开发 ```powershell node --test # 运行测试套件 ``` 源码结构：`src/cli.js`（CLI）、`src/mcp-server.js`（MCP）、`src/hubCore.js`（编排）、 `src/provision/`（检测+装机）、`src/daemon.js` + `src/jobQueue.js`（耐久后台任务）、 `src/codexClient.js` / `src/codexIpc.js`（Codex app-server + UI 流式）、 `src/antigravityRegistry.js`、`src/claudeRegistry.js`。文档在 `docs/`。