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.

---

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

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  → /brains//{events.jsonl, tasks//}
  wait:true        → run inline, return reply now (subagent-style)
  wait:false       → enqueue to /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 /brains//, 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:

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 = '\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 ` / 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 > AGENTHUBCLAUDE_CLI=reclaude` (or let the wrappers auto-detect it).

Quick start

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 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 (/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

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  [--out handoff.json]
agent-hub codex-task  --prompt "..." [--thread ] [--new-thread] [--open | --execute]
agent-hub claude-task --prompt "..." [--resume ] [--new-session] [--model haiku|sonnet|opus] [--cli reclaude]
agent-hub antigravity-visible-send --session  --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

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/.

---

中文

目录

• [功能简介](#功能简介)
• [工作原理](#工作原理)
• [安装](#安装)
• [快速开始](#快速开始)
• [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 之间的交互式 > 消息收发尚未完全验证。

工作原理

任意主脑（Claude Code / Codex / Antigravity / 任意 MCP 客户端，或 CLI）
        │  MCP 工具（delegate_to_* / setup_agent_hub / read_task）
        ▼
Agent Hub
  provision/       → 检测 agent、写 MCP 配置 + 装扩展
  每主脑看板        → /brains//{events.jsonl, tasks//}
  wait:true        → 内联执行、立刻返回回复（子代理式）
  wait:false       → 入队 /jobs，由 daemon 执行
        │                         │
        ▼                         ▼
  目标 agent              耐久 daemon（在编辑器进程树之外，抗窗口重载；
  (Codex / Claude /        并发消费任务队列）
   Antigravity)                    │
        ▼                         ▼
  reply.md + task.json  ◄── read_task(taskId)（跨任意主脑看板解析）

每个主脑有独立看板 /brains//，两个并行主脑不会串日志；同窗口的 面板解析同一看板。细节见 docs/architecture.md 与 docs/orchestration.md。

安装

要求：Node ≥ 20，无需 npm install（只用 Node 内置模块）。走 Codex 路径还 需 PATH 上有 Codex CLI。

一键装机（推荐）。 在你的 clone 目录：

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，重载。

> 路径： 把 ` / C:\agent-hub 换成你自己的 clone 位置。.cmd 包装器 > 路径无关（%~dp0）。装好后跑 node ./src/cli.js doctor 自检 Node、各 CLI、daemon、 > 以及哪些 agent 还没装。中转用户（如 reclaude）：设 AGENTHUBCLAUDE_CLI=reclaude` > （或让包装器自动检测）。

快速开始

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-hu

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uncle-tyson
• Source: uncle-tyson/Ur-Agent-Team
• License: MIT

Install and usage instructions live in the source repository linked above.