| 1 | # Orchestrator |
| 2 | |
| 3 | Load-on-demand guidance for orchestrating external **terminal coding agents** |
| 4 | from Agent Zero without keeping a large delegation tool in every agent prompt. |
| 5 | |
| 6 | The plugin provides: |
| 7 | |
| 8 | - an `orchestrator` skill that tells Agent Zero how to use external CLIs |
| 9 | through the user's A0 CLI host bridge or the normal container shell; |
| 10 | - a Settings > External Services status screen for configured binaries and |
| 11 | detected auth state; |
| 12 | - adapter metadata for Agent Zero headless, OpenAI Codex CLI, Claude Code, |
| 13 | Cursor CLI, Gemini CLI, Grok Build, Hermes Agent, OpenCode, and future terminal agents. |
| 14 | |
| 15 | There is intentionally no `terminal_agent` tool and no settings-screen install |
| 16 | button. When the user explicitly asks for a terminal agent, the skill first |
| 17 | decides whether to use the user's own host CLI through A0 CLI or a pal agent |
| 18 | inside the Agent Zero container. |
| 19 | |
| 20 | Host CLI is the primary everyday flow: the user's Claude Code, Codex, Cursor |
| 21 | CLI, and other coding agents stay installed and logged in on their own |
| 22 | computer. Container agents remain useful when the user explicitly wants the |
| 23 | Docker runtime. |
| 24 | |
| 25 | ## Supported Agents |
| 26 | |
| 27 | | Agent | CLI | Login | |
| 28 | | --- | --- | --- | |
| 29 | | Agent Zero (headless) | `a0` | Instance `/login` session; `A0_USERNAME`/`A0_PASSWORD` in the shell for protected hosts | |
| 30 | | OpenAI Codex | `codex` | ChatGPT device login from settings or external CLI login | |
| 31 | | Claude Code | `claude` | External `claude` login or `ANTHROPIC_API_KEY` | |
| 32 | | Cursor CLI | `agent` | `CURSOR_API_KEY`, `NO_OPEN_BROWSER=1 agent login`, or cached Cursor login | |
| 33 | | Gemini CLI | `gemini` | Cached Google login, `GEMINI_API_KEY`, or Vertex AI credentials | |
| 34 | | Grok Build | `grok` | `XAI_API_KEY`, `grok login --device-auth`, or cached Grok login | |
| 35 | | Hermes Agent | `hermes` | External Hermes/provider setup, `~/.hermes/.env`, `~/.hermes/auth.json`, or provider env vars | |
| 36 | | OpenCode | `opencode` | External `opencode auth login`, provider env vars, or `~/.local/share/opencode/auth.json` | |
| 37 | |
| 38 | The `a0` adapter targets the local Agent Zero instance |
| 39 | (`http://localhost:80` inside the container) when no `host`/`AGENT_ZERO_HOST` |
| 40 | is configured, or another Agent Zero instance when you set a host. This lets A0 |
| 41 | delegate to another runtime, and also lets the same runtime ask itself a focused |
| 42 | question as a secondary use case. A0 is the setup exception: if the user did |
| 43 | not specify a target, Agent Zero should ask whether to use the same instance or |
| 44 | another/spun-up instance instead of running a generic login flow. The skill |
| 45 | tells the target A0 instance to answer directly and not delegate back through |
| 46 | terminal agents. |
| 47 | |
| 48 | ## Skill Usage |
| 49 | |
| 50 | Ask Agent Zero to load/use the `orchestrator` skill before delegating coding |
| 51 | work to one of these CLIs. The skill keeps the global setup loop in |
| 52 | `skills/orchestrator/SKILL.md` and reads one per-agent reference from |
| 53 | `skills/orchestrator/references/` before acting. |
| 54 | |
| 55 | If the user does not specify host versus container, Agent Zero asks and saves a |
| 56 | per-agent preference with `memory_save`. Local/host mode uses the connector's |
| 57 | `code_execution_remote` tool and may load `host-code-execution`; container mode |
| 58 | uses `code_execution_tool`. |
| 59 | |
| 60 | For local/host coding agents, the user should run A0 CLI on their own machine: |
| 61 | |
| 62 | ```bash |
| 63 | # macOS / Linux |
| 64 | curl -LsSf https://cli.agent-zero.ai/install.sh | sh |
| 65 | ``` |
| 66 | |
| 67 | ```powershell |
| 68 | # Windows PowerShell |
| 69 | irm https://cli.agent-zero.ai/install.ps1 | iex |
| 70 | ``` |
| 71 | |
| 72 | If A0 CLI is installed but not running, open a terminal and run `a0`, connect it |
| 73 | to the Agent Zero instance, choose the chat/session or enter the remote/VPS URL, |
| 74 | then press `F4` for Remote Code Execution. Press `F3` too when host file writes |
| 75 | are needed. After that, asking Agent Zero to use local Claude Code/Codex/etc. |
| 76 | will run commands on the host machine instead of inside Docker. |
| 77 | |
| 78 | The skill must not use Computer Use to drive coding-agent terminals or TUIs. |
| 79 | It uses headless CLI commands. The ACP community plugin can be a separate path |
| 80 | when explicitly requested or when direct CLI automation is unsuitable. |
| 81 | |
| 82 | The reference files contain the copy-ready commands, for example Codex: |
| 83 | |
| 84 | ```bash |
| 85 | cd "$WORKDIR" |
| 86 | codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$TASK" |
| 87 | ``` |
| 88 | |
| 89 | Claude Code defaults to skip permissions for non-interactive runs: |
| 90 | |
| 91 | ```bash |
| 92 | cd "$WORKDIR" |
| 93 | if [ "$(id -u)" -eq 0 ]; then |
| 94 | claude -p "$TASK" --output-format json |
| 95 | else |
| 96 | claude -p "$TASK" --output-format json --permission-mode bypassPermissions --allowedTools Bash,Read,Edit |
| 97 | fi |
| 98 | ``` |
| 99 | |
| 100 | When Claude Code is not authenticated, use `claude auth login` for the |
| 101 | human-in-the-loop login step. Do not start plain `claude`; that opens the |
| 102 | first-run TUI and can trap the agent in theme/provider menus. |
| 103 | Ask the user to choose the auth mode first: Claude subscription |
| 104 | (`--claudeai`), Anthropic Console/API billing (`--console`), SSO (`--sso`), or |
| 105 | an externally set `ANTHROPIC_API_KEY`. In Agent Zero, the user can add that |
| 106 | key from **Settings > External Services > Secrets Management**; the runtime |
| 107 | file is `/a0/usr/.env`, not the workdir `.env`. |
| 108 | If a plain `claude` TUI is already open, reset the terminal session instead of |
| 109 | sending Enter or `/login`, then use one of the explicit auth commands. |
| 110 | |
| 111 | If a non-A0 CLI is missing or asks for login/browser confirmation, Agent Zero |
| 112 | can install the requested CLI, start its setup/login command, relay the exact |
| 113 | human step, wait for the user to confirm, then retry a smoke prompt before |
| 114 | running the real task. If setup shows provider/menu choices, Agent Zero should |
| 115 | show those options in chat and ask which one to select, not send the user to a |
| 116 | Docker shell just to choose from a menu. It should not ask the user to paste |
| 117 | secrets into chat unless there is no safer path. |
| 118 | |
| 119 | ## Login And Status |
| 120 | |
| 121 | Open **Settings > External Services > Orchestrator** to see registered |
| 122 | adapters, binary paths, installed status, and detected auth source. The screen |
| 123 | can refresh status and disconnect credentials only when an adapter can safely |
| 124 | remove a known credential store. |
| 125 | |
| 126 | Codex still supports plugin-owned device-code login from the settings screen. |
| 127 | Those tokens are stored under the plugin data directory (`data/codex/auth.json`, |
| 128 | mode 600), and the skill can point Codex at that home when needed. If you have |
| 129 | already logged in with `codex login`, the status screen detects the external |
| 130 | credentials too. |
| 131 | |
| 132 | > Tokens are password-equivalent credentials. Never share one rotating |
| 133 | > refresh-token auth file between two clients; plugin-owned Codex credentials |
| 134 | > stay separate from other tools. |
| 135 | |
| 136 | ## Configuration (`default_config.yaml`) |
| 137 | |
| 138 | ```yaml |
| 139 | a0: |
| 140 | binary: a0 # falls back to /opt/venv/bin/a0 in Agent Zero Docker |
| 141 | host: "" # empty = AGENT_ZERO_HOST env, else local instance |
| 142 | codex: |
| 143 | binary: codex |
| 144 | model: "" |
| 145 | bypass_sandbox: true |
| 146 | claude: |
| 147 | binary: claude |
| 148 | model: "" |
| 149 | permission_mode: bypassPermissions |
| 150 | allowed_tools: "Bash,Read,Edit" |
| 151 | bare: false |
| 152 | cursor: |
| 153 | binary: agent |
| 154 | output_format: text |
| 155 | force: true |
| 156 | gemini: |
| 157 | binary: gemini |
| 158 | model: "" |
| 159 | grok: |
| 160 | binary: grok |
| 161 | model: "" |
| 162 | output_format: json |
| 163 | always_approve: true |
| 164 | no_auto_update: true |
| 165 | hermes: |
| 166 | binary: hermes |
| 167 | model: "" |
| 168 | provider: "" |
| 169 | toolsets: "" |
| 170 | yolo: true |
| 171 | opencode: |
| 172 | binary: opencode |
| 173 | model: "" |
| 174 | agent: "" |
| 175 | auto: true |
| 176 | ``` |
| 177 | |
| 178 | ## Adding A New Agent |
| 179 | |
| 180 | 1. Create `helpers/adapters/<name>.py` subclassing `TerminalAgentAdapter` |
| 181 | (`helpers/adapters/base.py`) and implement `auth_status()`. Add optional |
| 182 | safe disconnect or device-login support only when the credential store is |
| 183 | known. |
| 184 | 2. Register an instance in `helpers/registry.py`. |
| 185 | 3. Add a config block in `default_config.yaml`. |
| 186 | 4. Add concise command guidance to |
| 187 | `skills/orchestrator/references/<name>.md`. |
| 188 | 5. Add the reference to `skills/orchestrator/SKILL.md` and update generic |
| 189 | skill guidance only when the global orchestration loop changes. |
| 190 | |
| 191 | The status API and settings UI pick registered adapters up automatically. |