A Claude-first plugin and utility package for using Claude Code as a coordinator of Claude, Codex, DeepSeek and optional MiMo and Grok workers. Includes client patches, a separate localhost Docker LiteLLM gateway, multi-account launchers, direct Codex recovery, skills and an operations runbook.
Architecture posters: command center and pig-kidney transplant unit.
Give this repository to Claude and ask it to follow the installation contract below. It can finish preparation, deployment and validation autonomously. Browser/device logins require the owner. Do not paste tokens or API keys into chat.
Community tooling, not endorsed by Anthropic or OpenAI. Subscription proxies and native-client patches are unsupported interfaces; vendors may change or restrict them. Use accounts you control and check applicable terms. The package does not grant entitlements or bypass login, quota, org policy or managed rules.
In Claude Code:
/plugin marketplace add tpurtell/claude-multi-agent
/plugin install hybrid-agents@tpurtell-agent-tools
For local development: claude plugin validate /path/to/repo, then
claude --plugin-dir /path/to/repo. Skills are:
/hybrid-agents:agent-orchestration/hybrid-agents:litellm-setup/hybrid-agents:codex-fallback/hybrid-agents:multi-account/hybrid-agents:external-agents- restart-safe interactive Grok/Gemini CLI supervision, steering and independent verification
Skills can bundle scripts; ordinary skill loading is on demand. This plugin's SessionStart hook injects the orchestration core on startup/resume/clear/compact; SubagentStart injects the worker contract. Loading is automatic while its hooks are enabled, not a guarantee of obedience. Hooks make no network calls, install nothing, read no credentials, and respect disabled hooks/managed policy. Plugin-only installation does not create services or patch the Agent schema.
Read this section and OPS.md, then inspect the scripts. Preserve the
user's existing configurations/services. Install only new cma* names; never
overwrite claude, claude2, hybrid-claude, codex2 or another LiteLLM stack.
Complete all non-login stages if the owner is absent and report pending logins.
Linux/Bash, Python 3.10+, Docker Compose, and a native ELF64/Bun Claude Code installation on PATH. Patches were tested with Claude Code 2.1.299; compatible updates rebuild automatically, unknown layouts fail closed. macOS/Windows binaries are unsupported. Codex CLI is needed only for direct fallback. The user needs Docker access; don't silently escalate/change group membership.
Installed launchers need a stable utility checkout, not a versioned plugin cache:
git clone https://github.com/tpurtell/claude-multi-agent.git \
~/.local/share/claude-multi-agent-src
cd ~/.local/share/claude-multi-agent-src
./scripts/cma --helpState defaults to ~/.local/share/claude-multi-agent, outside the checkout.
Set CMA_HOME to a dedicated absolute directory for another installation.
Choose a free port; examples use 4000. Leave existing services alone.
./scripts/cma init --accounts 2 --port 4000 --yolo
./scripts/cma up
./scripts/cma check--yolo explicitly enables unsandboxed, no-approval Claude execution. Use it only with full-access authorization on a trusted machine; omit it for ordinary permission checks. It does not expand task scope or change global settings.
init generates real private master/worker/salt/database secrets (0700 state,
0600 files), refuses existing state, and starts nothing. up starts only its
randomly named Compose project, provisions a restricted virtual key and verifies
the catalog. Only 127.0.0.1:4000 is published; PostgreSQL and OAuth workers
have no host ports. Public/LAN exposure requires a separate review.
The reviewed image is docker.litellm.ai/berriai/litellm:1.104.0. PostgreSQL
persists keys/permissions/usage/spend; each Codex worker has its own OAuth volume.
The intentionally single-process proxy has no Redis. There is no automatic
account switch or paid-provider fallback. Use --accounts 1 for one subscription.
The coordinator reuses the existing native Claude login. Only if missing, ask
the owner to run ./scripts/cma login-claude primary; don't replace a working
login to test setup. Authorize the gateway Codex subscriptions separately:
./scripts/cma login-chatgpt primary
./scripts/cma login-chatgpt backup
./scripts/cma upThe owner opens each printed URL, enters its code, and chooses the right account.
Do not log/share/commit device codes. These worker logins are distinct from the
native Codex CLI's login. Without the owner, leave this explicit handoff pending.
A healthy stack/correct catalog does not establish inference. check reports
OAuth file presence, not token validity, model entitlement or remaining quota.
Before explicit login succeeds, workers start with no active ChatGPT deployments
to avoid LiteLLM's eager device flow blocking unattended startup. Login runs in
a one-off container using the same private OAuth volume; the following up
recreates only workers/proxy to activate routes without recreating PostgreSQL.
./scripts/cma prepare-client
./scripts/cma install-launchers
cma-claudePut ~/.local/bin on PATH. Installs only cma, cma-claude, cma-claude2,
cma-codex, cma-codex2, refusing conflicts. The launcher loads this plugin,
fetches its exact gateway catalog and prepares a checksum-verified isolated
client. It never edits the installed binary. Cache identity includes source,
patcher, origin and enabled models; preparation is locked and atomic.
Check /model AND the actual Agent definition. Enhanced clients expose custom Agent.model and per-agent effort; a picker alone cannot do that. Native choices stay built in, while the gateway lists only these configured extras:
| Gateway ID | Source |
|---|---|
claude/chatgpt/gpt-6.1-sol |
Codex subscription 1 |
claude/chatgpt/gpt-6-astra |
Codex subscription 1 |
claude/chatgpt/gpt-6.1-sol-backup |
Codex subscription 2 |
claude/chatgpt/gpt-6-astra-backup |
Codex subscription 2 |
claude/deepseek/deepseek-flash |
Optional official API |
claude/xiaomi/mimo-v2.6-pro |
Optional OpenRouter API |
claude/xai/grok-4.7 |
Optional Grok subscription |
claude/xai/grok-4.7-build-fast |
Optional Grok subscription |
claude/xai/grok-4.6 |
Optional Grok subscription |
claude/xai/grok-4.5 |
Optional Grok subscription |
Sol/Astra allow low/medium/high/xhigh/max; DeepSeek low/high/max (the client maps medium→high and xhigh→max); MiMo default only; Grok low/medium/high/xhigh (grok-4.5 up to high). No forced gateway effort. See the model guide. Codex advertises 272k input/128k output, though unfamiliar IDs can still use Claude's conservative internal context budget.
Native Anthropic IDs/aliases remain permitted but hidden from gateway listings,
avoiding duplicates. cma refresh-native fetches the account's current catalog;
then cma up applies it. Native Max OAuth is forwarded only for native Anthropic
groups, never stored as a Docker/PostgreSQL provider credential.
With DEEPSEEK_API_KEY, OPENROUTER_API_KEY or EXA_API_KEY supplied through the owner's private environment/secret manager (never a CLI argument or chat):
cma provider deepseek
cma provider openrouter
cma provider exa
cma upThese enable their models/search and are separately billable. EXA intercepts
non-native search; native Claude retains its path. Without EXA, don't assume
non-native workers support Claude's server-side WebSearch. Provider permissions
must allow the model. Disable with cma provider NAME --disable then cma up.
Opt-in per installation. A separate grok1 worker signs in to the owner's Grok
subscription with LiteLLM's xAI OAuth and sends inference to the Grok CLI's
endpoint (cli-chat-proxy.grok.com), behind the same Anthropic-to-Responses bridge
as Codex:
cma enable-grok
cma login-grok # owner: open the printed URL within 3 minutes, approve
cma up
cma smoke --model claude/xai/grok-4.7 --effort xhigh --allow-spendLiteLLM's xAI login is PKCE with its callback on 127.0.0.1:56121 inside the
process, so login-grok runs a one-off container with host networking; open the
URL in a browser on the same machine (WSL forwards that loopback port). Or store an
existing LiteLLM xAI auth.json with cma import-grok-token PATH, then stop using
the source: refresh tokens rotate, so the worker must be the only refresher.
Efforts are low/medium/high/xhigh (grok-4.5: low/medium/high); there is no max and
the gateway clamps higher requests. 256k input/64k output. The proxy answers HTTP
426 to an outdated client version: cma enable-grok --client-version X.Y.Z, then
cma up. gateway/grok_compat.py sends store:false, drops the user field
(Claude account/device ids), gives each Claude Code subagent its own prompt-cache
key, and keeps a malformed final stream event from truncating the reply. Imitating
the Grok CLI client is unsupported; xAI may change or restrict it. Usage draws on
the subscription's Grok credits.
cma smoke --model claude/chatgpt/gpt-6.1-sol --effort high --allow-spend
cma smoke --model claude/chatgpt/gpt-6-astra-backup --effort xhigh --allow-spend
cma smoke --model claude-sonnet-5-5 --allow-spendThese streaming tool-call/follow-up tests use quota or paid API money. Next ask enhanced Claude to launch a harmless custom-model Agent and verify its result. Neither --version nor readiness proves live account access/Agent execution.
Read OPS.md for accounts, process stopping, updates, backup/recovery and Remote Control; ARCHITECTURE.md explains auth and patches.
cma check
CMA_NO_PATCH=1 cma-claude # no custom Agent schema; native client
CMA_REMOTE_CONTROL_PATCH=1 cma-claude --rc # opt-in unsupported RC workaround
cma login-codex backup
cma-codex2 # native fallback bypasses the gatewayNo account launcher uses Bubblewrap. Second Claude credentials are separate while sessions/settings are shared. Second native Codex uses separate CODEX_HOME, including separate config/history. Defaults are not rewritten globally.
The external-agents skill bundles a stdlib tmux
supervisor for interactive grok and Antigravity agy workers. A low-cost driver
steers an authorized task and checks its results; detached workers survive a
coordinator restart. Requires Linux, Python 3.10+, tmux and owner-authenticated
CLIs. Run state is private; approval bypass is opt-in with --auto-approve.
Executable paths/run root are environment-configurable, and preambles are explicit
file arguments. See the architecture, lessons and scorecard guide.
Fake-CLI tests do not establish live provider access or current vendor compatibility.
PYTHONPATH=patches:scripts python3 -m unittest discover -s tests -p 'test_*.py' -v
./scripts/test-gateway.sh
claude plugin validate .
python3 tests/integration.py --allow-docker
python3 tests/install_check.py --allow-nativeThe external-agent unit tests require tmux for their fake-CLI integration cases (and skip those cases if it is absent). They use private temporary socket/state namespaces and stop only their own workers; no provider login or inference runs.
The opt-in Docker test creates its own random project/port, uses fake upstreams
and removes only its own containers/volumes. No live credentials are used.
The native install check prepares a copy of the installed Claude binary and
installs the public marketplace only into a disposable home, without inference
or account login. Root CLAUDE.md is contributor guidance; installed plugin
runtime guidance is provided by the skills and startup hooks.
VERIFICATION.md lists tested behavior and remaining login/
upgrade limitations. Third-party binaries/images are not redistributed;
see THIRD_PARTY_NOTICES.md.