# AgentHub

AgentHub is a **local MCP agent-team runtime** for coding projects. An **external orchestrator** (Cursor, Codex, Claude, a custom MCP client, etc.) spawns named workers, delegates scoped tasks, waits for results, and resumes sessions. The human watches a **read-only board**; they do not drive the team from provider tabs.

**North star:** [docs/MUST-DO-DIRECTION.md](docs/MUST-DO-DIRECTION.md)

## What you get

| Piece | Role |
|-------|------|
| **MCP server** (`agenthub mcp`) | Primary product contract — session lifecycle, workers, delegation, updates |
| **Daemon + HTTP** | Same runtime for TUI board and automation |
| **Read-only TUI** (`agenthub launch`) | Dynamic worker board; legacy operator UI behind `/debug on` |
| **`.agenthub/`** | Durable mailbox, sessions, team state on disk |

Implementation: `agenthub-daemon` (TypeScript) + `agenthub-tui` (Rust).

## Provider support (V1)

| Provider | Level | Resume in board |
|----------|-------|-----------------|
| **Codex** | `supported` | Yes — adapter-tested `codex exec` / `exec resume`, CLI 0.128.0 |
| **Cursor** | `supported` | Yes — adapter-tested headless `cursor-agent`, stream-json |
| **Grok** | `experimental` | No — use for scoped tasks; live two-turn resume not proven |
| **OpenCode** | `experimental` | No — use for cost/model routing; permission server not wired |

Details: [docs/PROVIDER-SUPPORT-MATRIX.md](docs/PROVIDER-SUPPORT-MATRIX.md)  
Per-provider CLI evidence and orchestrator notes: [docs/PROVIDER-KNOWLEDGE.md](docs/PROVIDER-KNOWLEDGE.md)

**Experimental providers:** Grok and OpenCode may spawn and delegate, but AgentHub does not claim durable resume (`runtimeCanResume: false`). Prefer Codex or Cursor when restart-safe work matters.

## V1 release status

Core V1 is release-ready when the local release gates are green: build, daemon tests, TUI tests, package validation, packed install smoke, and the final dogfood transcript.

- Current status: [docs/STATUS.md](docs/STATUS.md)
- Final dogfood: [docs/V1-DOGFOOD-2026-06-06.md](docs/V1-DOGFOOD-2026-06-06.md)
- Release notes: [docs/RELEASE-NOTES-V1.md](docs/RELEASE-NOTES-V1.md)

## Install

Requires **Node.js 20+**. No Rust/MSVC at install time.

### Installer channel (`irm` / `curl`)

The live `stoyanco.com` channel currently publishes the Windows x64 artifact.

```powershell
irm https://stoyanco.com/agenthub/install.ps1 | iex
```

macOS/Linux use the same channel after their platform artifacts are built and uploaded:

```bash
curl -fsSL https://stoyanco.com/agenthub/install.sh | bash
```

Maintainer build/upload flow: [docs/INSTALLER-CHANNEL.md](docs/INSTALLER-CHANNEL.md)

### npm package

```powershell
npm install -g @agenthub-mcp/cli
agenthub doctor
agenthub init .
agenthub mcp
```

Connect your orchestrator to `agenthub mcp` (stdio MCP). Typical flow:

```text
create_session → get_session_state → spawn_worker → delegate_to_worker
→ wait_for / get_updates → recover_session (after daemon restart)
```

| Target name | MCP tool |
|-------------|----------|
| `create_session` | `agenthub_create_session` |
| `activate_session` | `agenthub_activate_session` |
| `get_session_state` | `agenthub_get_session_state` |
| `spawn_worker` | `agenthub_spawn_worker` |
| `delegate_task` | `agenthub_delegate_to_worker` |
| `wait_for` | `agenthub_wait_for` |
| `get_updates` | `agenthub_get_updates` |
| `recover_session` | `agenthub_recover_session` |
| `stop_worker` / `archive_worker` | `agenthub_stop_worker` / `agenthub_archive_worker` |

Also: `agenthub_list_sessions`, `agenthub_get_runtime_manifest` (includes `providerCapabilities` + knowledge doc paths).

Full orchestrator guide: [docs/AGENTHUB-SKILL.md](docs/AGENTHUB-SKILL.md)

## Read-only board

```powershell
agenthub launch .
```

Starts the daemon and TUI board (worker tabs, ops queue, settings). Default UX is **read-only observation** — orchestration stays in MCP.

- Requires a prebuilt TUI binary when installed from npm (`vendor/tui/<platform>-<arch>/`).
- **Legacy / debug (not V1 product path):** provider-first tabs (`/debug on`), Home slash orchestration, F2/F3 writer lock, conductor MCP tools. See [docs/LEGACY-RETIREMENT.md](docs/LEGACY-RETIREMENT.md).

## Dev checkout

```powershell
git clone <repo-url>
cd agenthub
npm install
npm run build
agenthub doctor
agenthub mcp
```

### Cursor MCP (dev checkout)

This repo ships [`.cursor/mcp.json`](.cursor/mcp.json) so Cursor loads AgentHub automatically for this workspace (`bin/agenthub.js mcp` with `AGENTHUB_PROJECT=${workspaceFolder}`). After `npm run build`, reload MCP servers in Cursor settings.

Smoke test (mock adapters, no provider credits):

```powershell
npm run smoke:mcp
```

Windows TUI builds need MSVC (`npm run build:tui`). See [docs/RELEASE-CHECKLIST.md](docs/RELEASE-CHECKLIST.md).

HTTP API (optional): `agenthub daemon` on port 4367.

## Docs map

| Doc | Purpose |
|-----|---------|
| [STATUS.md](docs/STATUS.md) | Current snapshot, tests, V1 verdict |
| [PROVIDER-SUPPORT-MATRIX.md](docs/PROVIDER-SUPPORT-MATRIX.md) | Machine-readable support contract |
| [PROVIDER-KNOWLEDGE.md](docs/PROVIDER-KNOWLEDGE.md) | CLI evidence, models, permissions, risks |
| [AGENTHUB-SKILL.md](docs/AGENTHUB-SKILL.md) | MCP orchestrator workflow |
| [CLI-FLAGS.md](docs/CLI-FLAGS.md) | Provider CLI flags |
| [V1-MAILBOX.md](docs/V1-MAILBOX.md) | File-backed mailbox protocol |
| [RELEASE-CHECKLIST.md](docs/RELEASE-CHECKLIST.md) | Build/test gates |

## Adapter overrides (optional)

```powershell
$env:AGENTHUB_CODEX_ARGS="-m gpt-5.4-mini"
$env:AGENTHUB_CURSOR_ARGS="--model composer-2.5"
$env:AGENTHUB_GROK_ARGS="-m grok-build-0.1"
$env:AGENTHUB_OPENCODE_ARGS="-m opencode-go/kimi-k2.6"
```

See [docs/CLI-FLAGS.md](docs/CLI-FLAGS.md) and provider knowledge files for launch templates and resume behavior.