​

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

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:

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: 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

1. Install the CLI agent and verify it’s on your PATH.
2. Launch Headmaster.
3. On the welcome screen, the detected CLI agents appear alongside the built-in agent.
4. 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:

1. Open Settings → Agent Management → Custom Agents.
2. Click Add custom agent.
3. Enter the CLI command, a display name, and any required arguments.
4. 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.