agent-hub

Local MCP orchestration layer for delegating bounded coding tasks across multiple AI coding agents.

Delegate specialized work from Claude Code, OpenCode, or any MCP client to the coding agents you already have installed — without hand-managing processes, fallbacks, retries, quotas, or execution state.

Claude Code / OpenCode / any MCP client
                  │
                  ▼
             agent-hub
                  │
      ┌───────────┼───────────┐
      ▼           ▼           ▼
     agy       OpenCode     Copilot        (…and Codex, Jules)
      │           │           │
      └───────────┼───────────┘
                  ▼
      execution · routing · recovery · workflows
                  │
                  ▼
              Dashboard

What is agent-hub?

agent-hub is a local MCP server and execution layer for delegating bounded tasks to multiple coding agents. It handles agent discovery, capability-aware routing, execution, retries, recovery, workflows, verification and monitoring — so the orchestrator states what it wants done, not which CLI to drive.

Why?

Without agent-hub, the orchestrator owns every detail:

Claude Code
   ├── manually call agy
   ├── manually call OpenCode
   ├── manually retry failures
   ├── manually inspect results
   └── manually track state

With agent-hub, those become the layer's job:

Claude Code
      │
      ▼
 agent-hub
   ├── discover     which agents are installed and healthy
   ├── route        pick an agent+model for the task
   ├── execute      run it, stream and persist the result
   ├── retry        fall back on failure, quota or breaker
   ├── verify       artifacts, deterministic checks, judge
   ├── orchestrate  multi-step DAGs with dependencies
   └── monitor      event log, metrics, dashboard

Related MCP server: agent-bridge-mcp

Key features

• Multi-agent delegation — agy (Antigravity), OpenCode, GitHub Copilot CLI, Codex CLI locally, and Google Jules in the cloud.

• Capability-aware routing — filters candidates by hard requirements and ranks them by quality, cost and latency preferences.

• Reliable execution — retries, automatic fallback chains, per-class circuit breakers, and timeouts that adapt to how long each agent and model actually takes.

• Workflow orchestration — DAGs with dependsOn and parallel waves; a step can run over a list and combine the results. Runs survive a crash and resume where they stopped.

• Evidence & verification — artifacts, deterministic verification commands and a judge/revision loop that can send work back for another pass.

• Safe write execution — worktree isolation, single-writer coordination, and a read-mode guard that fails a job which touched the disk.

• State you can trust — runs persist across restarts, a dispatch is idempotent across processes, and a slow agent is never mistaken for a dead one.

• Observability — event log, metrics, subagent tracking and a local dashboard.

• Harness integration — Claude Code, OpenCode and custom MCP clients get the waiting behaviour they expect, and a finished delegation can resume the session that asked for it.

Architecture at a glance

                    ┌────────────────────┐
                    │   Claude Code      │
                    │   OpenCode         │
                    │   External agents  │
                    └─────────┬──────────┘
                              │ MCP
                              ▼
                    ┌────────────────────┐
                    │     agent-hub      │
                    ├────────────────────┤
                    │ Planner            │
                    │ Router             │
                    │ Dispatcher         │
                    │ Policy engine      │
                    │ Workflow engine    │
                    │ Verification       │
                    │ Storage            │
                    └─────────┬──────────┘
                              │
          ┌───────────────────┼──────────────────┐
          ▼                   ▼                  ▼
      Local CLIs           Cloud              State
      agy                  Jules              SQLite
      OpenCode                                Events
      Copilot                                 Artifacts
      Codex

→ Architecture · Execution model · Storage

Supported agents

Per-agent notes: agy · OpenCode · Copilot · Jules

Quick start

Requirements: Node.js ≥ 20.19 and at least one supported agent CLI installed and authenticated.

git clone https://github.com/jalejandrov93/agent-hub.git ~/agent-hub
cd ~/agent-hub

npm install
node bin/agent-hub selftest

Connect Claude Code. Use an absolute node path: a version-manager shim only exists inside the shell that created it.

claude mcp add --scope user agent-hub -- \
  /path/to/node /path/to/agent-hub/bin/agent-hub mcp

Connect another MCP client by pointing it at /path/to/node /path/to/agent-hub/bin/agent-hub mcp over stdio. The server is harness-agnostic: Claude Code, OpenCode and custom clients call the same 28 tools, and each caller gets the waiting behaviour its harness profile declares.

Install only the runtime, keeping the checkout wherever you develop:

npm run install:local -- --restart

install:local builds the dashboard, copies the runtime into ~/.claude/mcp-servers/agent-hub, installs production dependencies there and records the exact commit. Re-run it after every git pull. It only installs a clean main checkout (pass --allow-branch to install anything else on purpose), so work in progress never reaches the live hub. Point every MCP client and the dashboard service at the installed copy, never at the checkout.

→ Full instructions, hooks, the dashboard service and skill install: Getting started

First delegation

Ask your orchestrator for the outcome, not the mechanism:

"Use agent-hub to investigate why the authentication flow is failing and return a concise diagnosis."

Under the hood that is one dispatch call:

{
  "taskType": "call-chain-trace",
  "task": "Trace how the authentication flow works and return a concise diagnosis.",
  "cwd": "/path/to/repo",
  "mode": "read",
  "timeoutS": 180
}

User ── "Trace the authentication flow..."
  ▼
Claude Code / OpenCode / any MCP client ── dispatch(taskType="call-chain-trace")
  ▼
agent-hub
  ├── route()    → primary: agy + gemini-high   fallback: OpenCode
  ├── execute    → policy, retries, fallback chain
  ├── verify     → artifacts, deterministic checks, judge
  └── result     → stdout, artifacts, status, tokens
  ▼
Claude Code ── the job record and its result

Useful tools to know: route (who can do this), dispatch (run it with policy and idempotency — the default choice), delegate (raw escape hatch: one exact agent+model, no policy), job_wait, job_result, and plan_task/execute_plan for multi-step work. The complete surface is in MCP tools.

Common use cases

Workflows

Workflows are DAGs: steps declare dependsOn, independent steps run in parallel waves, and a step can run over a list and combine the results. Runs are persisted, so a crash resumes where it stopped and a succeeded step is never re-executed.

      Research
      ├─────────────┐
      ▼             ▼
   Analysis       Security
      │             │
      └──────┬──────┘
             ▼
        Implementation
             │
             ▼
          Verify
             │
             ▼
          Review

→ Workflows · Verification · execution contract

Dashboard

A local dashboard ships with the runtime:

node bin/agent-hub dashboard
# http://127.0.0.1:7777

It shows agent availability, running jobs, execution history, metrics, subagents, the timeline, routing proposals, learnings and configuration.

→ Observability and dashboard

Configuration

→ Configuration reference · Quota (Quota-Arc / CodexBar)

Security

agent-hub is designed for local execution. The dashboard binds to loopback and is not authenticated: do not expose it through a reverse proxy, port forwarding, or a shared network.

Delegated agents run outside Claude Code's sandbox, so never put secrets, .env contents or credentials in a task string. Isolation profiles, credential hygiene and the read-mode guard are documented separately.

→ Security and isolation

Documentation

Getting started

• Installation and registration

• Configuration reference

• Dashboard

Concepts

• Architecture

• Routing

• Execution model

• Workflows

• Verification

• Context, handoffs and messaging

Providers

• agy (Antigravity)

• OpenCode

• GitHub Copilot CLI

• Jules (cloud)

Reference

• MCP tools

• Environment variables

• Storage

• Quota (Quota-Arc / CodexBar)

• Execution contract

• Security and isolation

Development

• Testing and reliability

• Contributing

Project history — changelog · audits, roadmaps and reports · versioning

Development

npm test                              # unit + integration suite
npm run -w dashboard test             # dashboard
npm run -w dashboard run typecheck    # dashboard types
AGENT_HUB_LIVE=1 npm run test:live    # opt-in live tests
npm run bench                         # offline benchmark corpus
node bin/agent-hub selftest           # end-to-end self check

Node must be the version the runtime uses (the native SQLite binding is compiled per ABI). If your shell resolves a different major version, pin it explicitly:

export PATH="$HOME/.local/share/fnm/aliases/default/bin:$PATH"

→ Testing and reliability

Contributing

See CONTRIBUTING.md.

License

MIT