agent-fleet-mcp
# agent-fleet-mcp (beta)
An MCP server that lets a **lead** agent (you in Claude Desktop, ChatGPT, Antigravity, Claude Code, VS Code, ...) run **manager** agents, and lets managers run their own **child** agents — across:
| Backend | How it is driven | Needs |
|---|---|---|
| `codex` — ChatGPT desktop (Codex mode) / Codex CLI | OpenAI's official `codex app-server` JSON-RPC | `npm i -g @openai/codex`, signed in |
| `antigravity` — Google Antigravity | official `agy -p --output-format stream-json` | Antigravity CLI (`agy`), signed in |
| `claude-code` — Claude Code | `claude -p --output-format stream-json` | Claude Code CLI, signed in |
| `ollama`, `lmstudio`, `vllm`, any OpenAI-compatible server | `/v1/chat/completions` | server running locally |
Agents created through Codex show up in the ChatGPT desktop app's Codex history, and Antigravity agents in Antigravity's history.
## Install
Needs Python 3.11+ and [uv](https://docs.astral.sh/uv/) (or pip).
```powershell
uv tool install git+https://github.com/s0wingseason/agent-fleet-mcp
agent-fleet install # adds agent-fleet to every supported app it finds
agent-fleet doctor # shows which apps and backends were found
```
Then fully quit and reopen each app (Claude Desktop and ChatGPT keep running in the tray).
`agent-fleet install --hosts claude-desktop,codex` limits it to some apps; `--dry-run` shows what would change. `agent-fleet uninstall` removes it again. Every edited config file gets a one-time `*.agent-fleet.bak` backup.
Apps it configures: Claude Desktop (including the Microsoft Store build), Claude Code, ChatGPT desktop / Codex CLI (`~/.codex/config.toml`), Google Antigravity (`~/.gemini/.../mcp_config.json`), Gemini CLI, VS Code, Cursor, Windsurf, LM Studio, Hermes Agent.
Not MCP hosts, so nothing is installed into them: Ollama, vLLM (use them as agent backends). Bionic and Open WebUI need manual setup (not covered yet).
## Tools
| Tool | Who |
|---|---|
| `fleet_status` | everyone |
| `spawn_agent`, `send_message`, `wait_for_agents`, `get_agent`, `get_transcript`, `interrupt_agent`, `stop_agent` | lead: any agent; manager: its own children |
| `send_files`, `fetch_files`, `list_files` | same; files go through each agent's `inbox` / `outbox` |
| `list_app_conversations`, `read_app_conversation`, `adopt_conversation` | lead only — reads Codex, Claude Code and Antigravity history saved on this PC, or takes over one of those conversations |
Typical lead prompt: *"Use agent-fleet: spawn a codex manager to refactor X, an antigravity manager to write tests, wait for both, then fetch their files."*
Calls never block more than ~55 s (MCP hosts time out around 60 s); poll `wait_for_agents` for long jobs.
## How it works
- Every app launches its own `agent-fleet serve` process. Agents run inside the process that created them; all processes share one SQLite database in `~/.agent-fleet`, so every app sees every agent, its status and transcript. An agent can only be messaged from the app that runs it — unless that app has closed, in which case the next app to message it takes it over and resumes the same conversation.
- Managers get the agent-fleet tools injected (Codex via `-c mcp_servers...`, Claude Code via `--mcp-config`) with their own identity; children run without them.
- Folders: `~/.agent-fleet/agents/<id>/{work,inbox,outbox}`, shared drop folder `~/.agent-fleet/exchange`. Config: `~/.agent-fleet/config.toml` (models, sandbox modes, limits, allowed folders).
## Known limits of this beta
- Not yet tested end to end on Windows with all backends together; please file issues.
- No Windows `.exe` installer yet (planned), and no desktop/UI automation.
- Regular ChatGPT chats (not Codex) live in OpenAI's cloud and aren't readable here. Automating the ChatGPT window to scrape replies conflicts with OpenAI's Terms of Use; this project only uses OpenAI's own `codex app-server` interface.
- Antigravity history reading is best-effort (undocumented storage format).
- Local-model agents are chat-only (no file tools yet).
- If `codex` on your PATH is a different program (e.g. the PyPI "codex" comic server), agent-fleet ignores it and looks for OpenAI's CLI under npm's global folder; `agent-fleet doctor` reports this.
## Safety
Agents run with your user account. Codex agents default to `workspace-write` sandbox; Claude Code agents to `acceptEdits`; Antigravity agents to `--sandbox`. File tools refuse paths outside allowed folders and anything that looks like keys or credentials. Review `~/.agent-fleet/config.toml` before giving agents broader access.
MIT licensed.
TDQS
Scored across 14 tools
Most tools target clearly distinct operations: lifecycle (spawn/stop/interrupt), communication (send_message/wait_for_agents), inspection (get_agent/get_transcript), and file transfer (send/fetch/list_files). The retrieval cluster is slightly fuzzy — fleet_status vs get_agent vs get_transcript, and wait_for_agents vs get_agent — but descriptions clarify the polling/blocking distinction well enough that misselection is unlikely.
Nearly all names follow a snake_case verb_noun pattern (spawn_agent, send_message, stop_agent, list_files). The main deviations are fleet_status (noun-first, no verb) and inconsistent retrieval verbs (get vs fetch vs list vs read), but the overall convention is readable and predictable.
Fourteen tools is well within a healthy range for a multi-agent orchestration server that spans agent lifecycle, messaging, file exchange, and conversation import. Each tool maps to a distinct operation with no padding or redundancy.
The surface covers the full agent lifecycle (spawn, message, wait, inspect, interrupt, stop) plus file transfer and conversation adoption, which is strong coverage. Minor gaps exist: no way to remove/clean up a stopped agent from the fleet, no batch/multi-agent messaging or broadcast, and no way to update an agent's configuration after spawn.