agent-zero/plugins/_orchestrator/README.md

Orchestrator

Load-on-demand guidance for orchestrating external terminal coding agents from Agent Zero without keeping a large delegation tool in every agent prompt.

The plugin provides:

• an orchestrator skill that tells Agent Zero how to use external CLIs through the user's A0 CLI host bridge or the normal container shell;
• a Settings > External Services status screen for configured binaries and detected auth state;
• adapter metadata for Agent Zero headless, OpenAI Codex CLI, Claude Code, Cursor CLI, Grok Build, Hermes Agent, OpenCode, and future terminal agents.

There is intentionally no terminal_agent tool and no settings-screen install button. When the user explicitly asks for a terminal agent, the skill first decides whether to use the user's own host CLI through A0 CLI or a pal agent inside the Agent Zero container.

Host CLI is the primary everyday flow: the user's Claude Code, Codex, Cursor CLI, and other coding agents stay installed and logged in on their own computer. Container agents remain useful when the user explicitly wants the Docker runtime.

Supported Agents

Agent	CLI	Login
Agent Zero (headless)	a0	Instance /login session; A0_USERNAME/A0_PASSWORD in the shell for protected hosts
OpenAI Codex	codex	ChatGPT device login from settings or external CLI login
Claude Code	claude	External claude login or ANTHROPIC_API_KEY
Cursor CLI	agent	CURSOR_API_KEY, NO_OPEN_BROWSER=1 agent login, or cached Cursor login
Grok Build	grok	XAI_API_KEY, grok login --device-auth, or cached Grok login
Hermes Agent	hermes	External Hermes/provider setup, ~/.hermes/.env, ~/.hermes/auth.json, or provider env vars
OpenCode	opencode	External opencode auth login, provider env vars, or ~/.local/share/opencode/auth.json

The a0 adapter targets the local Agent Zero instance (http://localhost:80 inside the container) when no host/AGENT_ZERO_HOST is configured, or another Agent Zero instance when you set a host. This lets A0 delegate to another runtime, and also lets the same runtime ask itself a focused question as a secondary use case. A0 is the setup exception: if the user did not specify a target, Agent Zero should ask whether to use the same instance or another/spun-up instance instead of running a generic login flow. The skill tells the target A0 instance to answer directly and not delegate back through terminal agents.

Skill Usage

Ask Agent Zero to load/use the orchestrator skill before delegating coding work to one of these CLIs. The skill keeps the global setup loop in skills/orchestrator/SKILL.md and reads one per-agent reference from skills/orchestrator/references/ before acting.

If the user does not specify host versus container, Agent Zero asks and saves a per-agent preference with memory_save. Local/host mode uses the connector's code_execution_remote tool and may load host-code-execution; container mode uses code_execution_tool.

For local/host coding agents, the user should run A0 CLI on their own machine:

# macOS / Linux
curl -LsSf https://cli.agent-zero.ai/install.sh | sh

# Windows PowerShell
irm https://cli.agent-zero.ai/install.ps1 | iex

If A0 CLI is installed but not running, open a terminal and run a0, connect it to the Agent Zero instance, choose the chat/session or enter the remote/VPS URL, then press F4 for Remote Code Execution. Press F3 too when host file writes are needed. After that, asking Agent Zero to use local Claude Code/Codex/etc. will run commands on the host machine instead of inside Docker.

The skill must not use Computer Use to drive coding-agent terminals or TUIs. It uses headless CLI commands. The ACP community plugin can be a separate path when explicitly requested or when direct CLI automation is unsuitable.

The reference files contain the copy-ready commands, for example Codex:

cd "$WORKDIR"
codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$TASK"

Claude Code defaults to skip permissions for non-interactive runs:

cd "$WORKDIR"
if [ "$(id -u)" -eq 0 ]; then
  claude -p "$TASK" --output-format json
else
  claude -p "$TASK" --output-format json --permission-mode bypassPermissions --allowedTools Bash,Read,Edit
fi

When Claude Code is not authenticated, use claude auth login for the human-in-the-loop login step. Do not start plain claude; that opens the first-run TUI and can trap the agent in theme/provider menus. Ask the user to choose the auth mode first: Claude subscription (--claudeai), Anthropic Console/API billing (--console), SSO (--sso), or an externally set ANTHROPIC_API_KEY. In Agent Zero, the user can add that key from Settings > External Services > Secrets Management; the runtime file is /a0/usr/.env, not the workdir .env. If a plain claude TUI is already open, reset the terminal session instead of sending Enter or /login, then use one of the explicit auth commands.

If a non-A0 CLI is missing or asks for login/browser confirmation, Agent Zero can install the requested CLI, start its setup/login command, relay the exact human step, wait for the user to confirm, then retry a smoke prompt before running the real task. If setup shows provider/menu choices, Agent Zero should show those options in chat and ask which one to select, not send the user to a Docker shell just to choose from a menu. It should not ask the user to paste secrets into chat unless there is no safer path.

Login And Status

Open Settings > External Services > Orchestrator to see registered adapters, binary paths, installed status, and detected auth source. The screen can refresh status and disconnect credentials only when an adapter can safely remove a known credential store.

Codex still supports plugin-owned device-code login from the settings screen. Those tokens are stored under the plugin data directory (data/codex/auth.json, mode 600), and the skill can point Codex at that home when needed. If you have already logged in with codex login, the status screen detects the external credentials too.

Tokens are password-equivalent credentials. Never share one rotating refresh-token auth file between two clients; plugin-owned Codex credentials stay separate from other tools.

Configuration (default_config.yaml)

a0:
  binary: a0          # falls back to /opt/venv/bin/a0 in Agent Zero Docker
  host: ""           # empty = AGENT_ZERO_HOST env, else local instance
codex:
  binary: codex
  model: ""
  bypass_sandbox: true
claude:
  binary: claude
  model: ""
  permission_mode: bypassPermissions
  allowed_tools: "Bash,Read,Edit"
  bare: false
cursor:
  binary: agent
  output_format: text
  force: true
grok:
  binary: grok
  model: ""
  output_format: json
  always_approve: true
  no_auto_update: true
hermes:
  binary: hermes
  model: ""
  provider: ""
  toolsets: ""
  yolo: true
opencode:
  binary: opencode
  model: ""
  agent: ""
  auto: true

Adding A New Agent

1. Create helpers/adapters/<name>.py subclassing TerminalAgentAdapter (helpers/adapters/base.py) and implement auth_status(). Add optional safe disconnect or device-login support only when the credential store is known.
2. Register an instance in helpers/registry.py.
3. Add a config block in default_config.yaml.
4. Add concise command guidance to skills/orchestrator/references/<name>.md.
5. Add the reference to skills/orchestrator/SKILL.md and update generic skill guidance only when the global orchestration loop changes.

The status API and settings UI pick registered adapters up automatically.