Your Crew

Headmaster's built-in agent engine works out of the box — zero setup. But if you already use a CLI agent (Claude Code, Codex, Gemini CLI, Cursor Agent, or any of the 20+ ACP-compatible CLIs), Headmaster auto-detects it and lets you drive it from the Headmaster desktop interface. This is Your Crew — the backing agents that power your specialists behind the scenes.

Multi-Agent Mode vs. Built-in Agent Mode

| Aspect | Built-in Agent Mode | Multi-Agent Mode (Your Crew) | | --- | --- | --- | | Install requirements | None — bundled with Headmaster | You install the external CLI yourself; Headmaster auto-detects it | | Architecture | Headmaster's built-in engine + ACP | External CLI processes spoken to over ACP | | Feature integration | Full: image generation, MCP, multi-key rotation, scheduled tasks, file management | Agent's native features only — Headmaster provides the chat and file UI | | Configuration | One Headmaster config covers everything | Each external CLI handles its own auth and config | | Best for | Daily use, full Headmaster feature surface | Power users who already live in a specific CLI |

Multi-Agent Mode is optional. You can use Headmaster without installing anything else. Your Crew is for users who already have a CLI agent they love and want to use it from the Headmaster GUI instead of a terminal.

ACP (Agent Client Protocol)

ACP is the standard that lets Headmaster talk to external CLI agents. Every supported CLI speaks ACP, which means:

Single workspace — a single Headmaster window replaces switching between multiple terminal sessions.
Protocol standardization — every external agent talks to Headmaster over the same protocol.
Independent capabilities — each external agent keeps its own model, auth, tools, and behaviors.
Custom agents — any protocol-compatible CLI can be added through Settings.

Auto-detection

Headmaster scans your PATH on startup and lights up agents already installed. You don't need to configure anything — if the CLI command is callable from a fresh terminal, Headmaster finds it.

The detected agents appear on the welcome screen and in the specialist picker. You can pick one the same way you pick a built-in specialist.

Verifying installation

Make sure the CLI command is callable from a fresh terminal:

macOS/Linux: which <command>
Windows: where <command>

If the terminal can find it, Headmaster can too. Restart Headmaster after installing a new CLI to trigger a re-scan.

Detected CLI agents

Headmaster auto-detects any of these if their CLI is on your PATH:

| Agent | CLI command | Vendor | | --- | --- | --- | | Claude Code | claude | Anthropic | | Codex | codex | OpenAI | | Qwen Code | qwen | Alibaba Qwen | | Gemini CLI | gemini | Google | | Cursor Agent | cursor-agent | Cursor | | Snow CLI | snow | Snow | | Kiro | kiro | Kiro | | Goose | goose | Block | | OpenCode | opencode | OpenCode | | OpenClaw | openclaw | OpenClaw (gateway mode) | | Augment Code | auggie | Augment | | CodeBuddy | codebuddy | Tencent | | Kimi CLI | kimi | Moonshot | | Factory Droid | droid | Factory | | GitHub Copilot CLI | copilot | GitHub | | Qoder CLI | qoder | Qoder | | Mistral Vibe | vibe-acp | Mistral | | Nanobot | nanobot | Nanobot |

New ACP-compatible CLIs are added regularly. The exact set may grow with each Headmaster release — check the welcome screen for the up-to-date list, or define your own under Settings → Agent Management → Custom Agents.

Installing a CLI agent

Headmaster does not ship external CLIs. Install whichever ones you want, following the vendor's official documentation. The package names and install commands change frequently, so this guide points to upstream:

| Agent | Install URL | | --- | --- | | Claude Code | https://docs.anthropic.com/claude/claude-code | | Codex | https://developers.openai.com/codex/cli/ | | Qwen Code | https://github.com/QwenLM/qwen-code | | Gemini CLI | https://github.com/google-gemini/gemini-cli | | Cursor Agent | https://docs.cursor.com/ | | Snow CLI | https://snowcli.dev/ | | Kiro | https://kiro.dev/ | | Goose | https://github.com/block/goose | | OpenCode | https://github.com/opencode-ai/opencode | | OpenClaw | https://github.com/openclaw/openclaw | | Augment Code | https://www.augmentcode.com/ | | CodeBuddy | https://github.com/Tencent/CodeBuddy | | Kimi CLI | https://platform.moonshot.cn/ | | Factory Droid | https://www.factory.ai/ | | GitHub Copilot CLI | https://docs.github.com/en/copilot/github-copilot-in-the-cli | | Qoder CLI | https://qoder.com/ | | Mistral Vibe | https://github.com/mistralai/vibe-acp | | Nanobot | https://github.com/nanobot-ai/nanobot |

After installing, verify the CLI is callable from a fresh terminal. If the terminal can find it, Headmaster can too. Restart Headmaster after installing a new CLI to trigger a re-scan.

Using a CLI agent from Headmaster

Install the CLI agent and verify it's on your PATH.
Launch Headmaster.
On the welcome screen, the detected CLI agents appear alongside the built-in agent.
Pick one and start a conversation.

The external agent keeps its own model, auth, tools, and behaviors. Headmaster provides the unified chat and file UI. When you switch agents (via the specialist picker), you switch the underlying CLI — each agent has its own model list, its own capabilities, and its own approach.

What Headmaster provides for external agents

Chat UI — the same streaming, markdown, tool call display, and approval gates as the built-in agent.
File manager — browse, upload, and preview files.
Preview panel — multi-format file viewer.
Workspace — open a project folder.
Approvals — human-in-the-loop approval gates.

What the external CLI provides

Model — the CLI's own model selection and auth.
Tools — the CLI's own tool set (may differ from Headmaster's built-in tools).
Behavior — the CLI's own reasoning, coding style, and approach.
MCP — the CLI's own MCP server config (which Headmaster can sync to — see Connections).

Custom agents

Any protocol-compatible CLI can be added, even if it's not on the auto-detect list:

Open Settings → Agent Management → Custom Agents.
Click Add custom agent.
Enter the CLI command, a display name, and any required arguments.
Save. The custom agent appears in the picker alongside the built-in and auto-detected ones.

Agent management

In Settings → Agent Management, you can:

See all detected agents — built-in and external, with their status (available, not found, error).
Enable / disable individual agents. Disabled agents don't appear in the picker.
Configure agent-specific settings (model defaults, allowed tools).
Add custom agents that aren't on the auto-detect list.
Rescan — forces Headmaster to re-scan your PATH for newly installed CLIs.

Local agents

The Local Agents tab shows all agents detected on this machine. Each card shows:

Agent name and vendor.
CLI command.
Status (available, not found, error).
Detected model count.
Enable/disable toggle.

Remote agents

The Remote Agents tab lets you connect to agents running on a remote machine. This is useful when you have a CLI agent installed on a server but want to drive it from your laptop's Headmaster UI.

Preset management

Presets are saved combinations of agent + model + specialist + settings. You can:

Create a preset for a common workflow ("Code Review" = Claude Code + Sonnet + The Architect).
Switch between presets from the specialist picker.
Share presets with your team (export as JSON).

One window for everything

The point of Your Crew is: a single Headmaster window replaces switching between multiple terminal sessions. You get the same chat UI, the same file manager, the same preview panel, the same approval gates, regardless of which CLI is doing the work behind the scenes.

Switching between agents is as easy as switching specialists — click the picker, choose a different agent, and the next message goes to the new one. Each agent's conversations are saved separately in the sidebar.

MCP sync

When you enable an MCP server in Headmaster, it's synced to all detected CLI agents. If you have Claude Code and Codex both installed, enabling a server in Headmaster makes it available to both. See Connections (MCP) for details.