AgentHub
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AgentHub delegate codex to add input validation to the signup handler and run its tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AgentHub

▶ Watch the demo in full quality (MP4, 43 s, with voiceover): a real run, not a mock-up.
Let Claude Code hand work to other coding agents (Codex, Antigravity, Claude, Aider, Goose, or any CLI) without handing them your whole machine.
AgentHub is a small MCP server, CLI and optional HTTP API. Use it to:
Get a second opinion. Send one question to several agents and compare the answers (
compare).Get a cross-model review of your diff before you commit (
review).Delegate safely. An agent works in its own git worktree. You see the diff, then apply or discard it.
Use the subscriptions you already pay for. ChatGPT through Codex, Google through Antigravity, all from one place, with automatic fallback when one runs out of quota.
Run long jobs in the background, wait for them, read readable logs.
Search other agents' past sessions, or continue them.
Every request goes through one policy layer: trusted folders, permission modes, a minimal environment, timeouts, quota tracking and a hash-chained audit log.
Pure Python standard library. No dependencies. Linux and macOS. About 20 MB of RAM.
Quick start
pipx install agenthub-gateway # or: uv tool install agenthub-gateway
# or run without installing: uvx agenthub-gateway doctor
agenthub config --init # writes ~/.agenthub/config.json
$EDITOR ~/.agenthub/config.json # set "trusted_workspaces": ["~/code"]
agenthub doctorThen connect it to Claude Code in one of two ways:
# A) Plugin: MCP server plus slash commands (/second-opinion, /cross-review, /delegate, /agent-tasks)
# Starts the server with `uvx agenthub-gateway mcp`, so it needs uv (https://docs.astral.sh/uv/).
claude plugin marketplace add premanand8800/agenthub-mcp
claude plugin install agenthub@agenthub
# B) MCP server only
agenthub install-claudeRestart Claude Code and try:
/cross-review codex
/delegate codex add input validation to the signup handler and run its tests
Use agenthub to compare codex and claude on: what's the safest way to migrate this table?
Related MCP server: opencode-delegate
How a delegated change works
start_task(isolation="worktree") → agent edits a private checkout (your files are untouched)
wait_task → blocks until done; returns final output, session_id, token usage
get_task_diff → file list + patch
review(task_id=…) → optional: another model reviews that patch
apply_task | discard_task → patch lands in your working tree (uncommitted), or is thrown awayThe worktree starts from your current state, including uncommitted changes to tracked files. Build junk (__pycache__, node_modules, …) is left out of the diff. If your files changed in the meantime, apply_task tries a 3-way merge. If that conflicts, it keeps the worktree so you can resolve it by hand.
Permission modes
Mode | Meaning | Codex | Claude | Antigravity | Aider | Goose |
| Inspect only |
|
|
|
|
|
| Edit files in |
|
|
| no shell commands | – |
| No sandbox, no approvals |
|
|
|
|
|
fullis off until a human sets"allow_full_access": true. A model cannot turn it on.reviewandcomparealways runread-only.If an agent can't enforce a mode, AgentHub refuses the request instead of quietly running with weaker settings.
A delegated Claude runs with
--strict-mcp-config, so it can't use your other MCP servers (email, chat, AgentHub itself).
MCP tools
Tool | What it does | Read-only |
| Installed agents, modes, features, quota health | yes |
| Run a prompt and wait. Returns | no |
| Background job, optionally | no |
| Block until a task finishes (up to 10 min per call) | yes |
| Status, final output, readable logs | yes |
| Kill a task and all its child processes | no |
| What a worktree task changed | yes |
| Land or drop a worktree task's changes | no |
| Read-only review of | yes* |
| Same prompt to 2–5 agents in parallel | yes* |
| Other agents' history | yes |
| Model IDs per agent | yes |
| Message a live session | no |
* These don't change your files, but they do send code to the agents' vendors and use quota.
Options for ask and start_task: workdir, permission_mode, model, and session_id (continue a conversation). Also:
add_dirs: extra directoriesimages: Codex onlyoutput_schema: a JSON Schema; the answer comes back parsed instructuredfallback_agents: other agents to try if this one is out of quota or not installed
Long calls send MCP progress notifications every 10 s when the client asks for them.
To skip permission prompts for tools that only read:
// ~/.claude/settings.json
{ "permissions": { "allow": [
"mcp__agenthub__list_agents", "mcp__agenthub__wait_task", "mcp__agenthub__get_task",
"mcp__agenthub__get_task_logs", "mcp__agenthub__list_tasks", "mcp__agenthub__get_task_diff",
"mcp__agenthub__list_sessions", "mcp__agenthub__search_sessions", "mcp__agenthub__get_transcript",
"mcp__agenthub__list_models"
] } }Reliability
Quota-aware. When a provider reports a quota or rate limit, AgentHub records it, including the reset time when the message gives one ("Resets in 137h"). That agent then fails fast with
quota_exhausteduntil the reset time.fallback_agentsmoves on to the next agent automatically.list_agentsshows each agent's health.No unsafe retries. An agent run that failed partway may already have edited files, so AgentHub never retries it automatically. Falling back to another agent only happens when nothing ran.
Survives restarts. Background tasks keep running if Claude Code closes, and their status still works from any process. In-flight
askcalls are killed when the client disconnects, so nothing keeps spending.Global limits.
max_concurrent_tasksholds across every Claude Code session, enforced with a file lock.
CLI (also built for agents)
Every command is non-interactive, has --json, and uses stable exit codes. Other agents can call AgentHub from their own terminals.
agenthub agents [--json]
agenthub ask codex "explain main.py" -m read-only [--session ID] [--schema s.json] [--fallback claude]
agenthub run codex "add tests" --isolation worktree → prints task ID
agenthub wait ID [--timeout 600] exit 0 succeeded · 1 failed · 3 still running
agenthub diff ID | apply ID | discard ID
agenthub review codex [--base main | --task ID]
agenthub compare codex,claude "which approach is safer?"
agenthub tasks | task ID | logs ID | cancel ID
agenthub audit [--verify] · config [--init] · token [--rotate] · serve · doctor
agenthub approve antigravity "Bash(npm test)" human-onlyExit codes: 0 ok · 1 the agent or task failed · 2 usage error · 3 still running (for wait).
Configuration
~/.agenthub/config.json. Every key is optional. Unknown keys are an error, so typos don't fail silently. Set AGENTHUB_HOME to move the whole directory.
Key | Default | |
|
| Agents may only run inside these. Narrow this. |
|
| Always refused |
|
| |
|
| Allows |
|
| Extra env vars for agents (globs), e.g. |
|
|
|
|
| |
|
| Across all sessions |
|
| |
|
| Stops agent → hub → agent loops |
|
| How long to skip an agent after a quota error with no reset time |
|
|
|
|
| Old tasks and their worktrees are deleted |
|
| Browser origins allowed to call the HTTP API |
Environment: agents get only what they need:
PATH,HOME, locale, proxies, CA bundlestoolchain variables (nvm, cargo, go, java, venv, …)
their own API-key variables (
OPENAI_*for Codex,ANTHROPIC_*for Claude, …)
Cloud credentials such as AWS_* and GH_TOKEN are not passed unless you list them in env_passthrough.
Custom agents
Put a JSON file in ~/.agenthub/agents/ (mode 600). See examples/custom-agent.json.
{
"name": "myagent",
"command": "myagent",
"args": ["run", "--prompt={prompt}"],
"model_args": ["--model", "{model}"],
"add_dir_args": ["--add-dir", "{dir}"],
"output_schema_args": ["--schema", "{schema_file}"],
"json_output": { "reply": "result", "session_id": "session_id", "cost_usd": "cost" },
"env_passthrough": ["MYAGENT_API_KEY"],
"modes": { "read-only": ["--no-write"], "workspace-write": ["--sandbox"] }
}modeslists only what your CLI can really enforce.json_outputtells AgentHub where to find the reply and session ID when your CLI prints JSON.Specs that are group- or world-writable are refused, and so are specs that reuse a built-in name.
agenthub doctorreports why.
HTTP API (optional)
agenthub serve # 127.0.0.1:8765
TOKEN=$(agenthub token)
curl -s localhost:8765/v1/agents/codex/ask -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"prompt":"hi","permission_mode":"read-only"}'Method | Path |
GET |
|
POST |
|
GET |
|
POST |
|
GET |
|
POST |
|
Errors are always {"ok": false, "error": {"code", "message"}}. A quota_exhausted error also includes retry_after_seconds.
Security model
See SECURITY.md. In short:
The model is untrusted. Defaults assume a prompt injection will reach AgentHub. Every agent run is sandboxed, limited to trusted folders, given a minimal environment, time-limited and audited. A model can't enable
fullmode or approve its own tools.No shell, ever. Prompts can't become CLI options.
Private state. All state lives in
~/.agenthub(0700), never in/tmp.Tamper-evident audit log.
agenthub audit --verify.
Development
git clone https://github.com/premanand8800/agenthub-mcp && cd agenthub-mcp
PYTHONPATH=src python -m unittest discover -s tests -t tests -vTests use a fake agent: no API keys, no quota. To add a built-in adapter, subclass agenthub.adapters.base.Adapter, then:
implement
build_command(spec), andparse_outputif your CLI prints JSONdeclare
modesandenv_allowregister it in
adapters/__init__.py
Contributing
Issues and PRs welcome — see CONTRIBUTING.md. Security reports: SECURITY.md.
License
MIT
Available Tools
18 toolsapply_taskApply task changesBDestructive
Apply a worktree-isolated task's changes to the user's working tree (not committed).
Inputs: task_id (required), keep_worktree.
askAsk an agentBDestructive
Run a prompt on an agent and wait for the answer (minutes). Returns reply, session_id, usage.
Inputs: agent (required), prompt (required), model, images, +6 more.
cancel_taskCancel taskBDestructiveIdempotent
Stop a running task and every process it started.
Inputs: task_id (required).
compareCompare agentsBRead-only
Send one prompt to 2-5 agents in parallel (read-only) and get their answers side by side.
Inputs: agents (required), prompt (required), workdir, output_schema.
discard_taskDiscard task changesADestructiveIdempotent
Throw away a worktree-isolated task's changes (cancels it if running).
Inputs: task_id (required).
get_taskGet taskBRead-only
Task status and, once finished, its final output, session_id and usage.
Inputs: task_id (required).
get_task_diffGet task diffBRead-onlyIdempotent
Changes a worktree-isolated task made (file list, stat and patch).
Inputs: task_id (required), max_chars.
get_task_logsGet task logsBRead-only
Last lines of a task's log (readable summary of commands, edits and messages).
Inputs: task_id (required), tail_lines.
get_transcriptGet transcriptCRead-onlyIdempotent
Turns (messages, tool calls) of one past session.
Inputs: agent (required), session_id (required), max_steps.
list_agentsList agentsBRead-onlyIdempotent
Installed agents, their permission modes, supported features and quota health.
Inputs: no named parameters.
list_modelsList modelsBRead-onlyIdempotent
Model IDs an agent accepts for model.
Inputs: agent (required).
list_sessionsList sessionsCRead-onlyIdempotent
An agent's recent conversation sessions.
Inputs: agent (required), limit.
list_tasksList tasksCRead-only
Recent background tasks, newest first.
Inputs: limit, status.
reviewReview changesARead-only
Ask an agent to review a diff (read-only): uncommitted changes vs base (default HEAD), or a task's worktree changes via task_id.
Inputs: agent (required), base, model, task_id, +4 more.
search_sessionsSearch sessionsCRead-onlyIdempotent
Search an agent's past sessions by keyword.
Inputs: agent (required), query (required), limit.
send_messageSend message to sessionCDestructive
Send a message into an agent's live interactive session.
Inputs: agent (required), message (required), session_id (required).
start_taskStart background taskADestructive
Start long agent work in the background; returns task_id. Use isolation='worktree' for code changes.
Inputs: agent (required), prompt (required), model, images, +7 more.
wait_taskWait for taskARead-only
Wait until a task finishes (or timeout_seconds passes) and return its result.
Inputs: task_id (required), timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have clearly distinct purposes: the task lifecycle set (start/wait/get/logs/list/cancel/diff/apply/discard) is well-partitioned by resource and action, and list/search/get_transcript for sessions are clearly differentiated. Minor overlap risk exists between ask, start_task, and send_message (all send prompts, differing mainly by sync/async/interactive mode), which descriptions largely resolve.
Nearly all names follow a consistent snake_case verb_noun pattern (list_agents, get_task_diff, cancel_task, search_sessions, send_message). A few single-verb names (ask, review, compare) deviate slightly from the pattern but remain readable and unambiguous.
18 tools is on the heavier side but justified: nine tools cover the full background-task lifecycle plus agent, session, and model operations. Each tool has a distinct role, so nothing appears redundant or padded.
Coverage is strong: agent discovery, full task lifecycle (create, monitor, diff, apply, discard, cancel), session browsing/search/transcript, and model listing. Minor gaps exist around agent lifecycle management (list_agents implies installation but there's no install/remove tool) and cross-agent model discovery.
Maintenance
Related MCP Connectors
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables Codex to delegate bounded engineering jobs to Claude Code CLI in isolated Git worktrees with strict security and allowance pacing.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code and Claude Desktop to delegate coding tasks to any model available in OpenCode while Claude remains the orchestrator, planning work, reviewing diffs, and running tests. Supports synchronous and async delegation, model selection, session continuation, and permission-aware execution.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code, Codex, and Cursor to delegate self-contained coding tasks to one another on the user's own subscriptions, with each task isolated in a git worktree and sandbox, usage tracked, budgets enforced, and results returned for review.179 npm3Apache 2.0
- AlicenseBqualityBmaintenanceEnables Claude Code to delegate tasks such as planning, coding, reviews, debugging, tests, and docs to a cheaper model that works autonomously in a project-sandboxed loop with file, search, and test tools, returning a compact report to save tokens. Routing rules, approval-gated deletes and commands, per-task model/effort settings, and backups keep the user in control of what gets handed off.7MIT