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.Built-in agent vs. multi-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 — one 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 yourPATH on startup and lights up agents already installed. No configuration needed — if the CLI command is callable from a fresh terminal, Headmaster finds it.
Detected agents appear on the welcome screen and in the specialist picker.
Verifying installation:
Detected CLI agents
New ACP-compatible CLIs are added regularly. Check the welcome screen for the up-to-date list, or add 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:Using a CLI agent from Headmaster
1
Install the CLI agent
Install it and verify it’s callable from a fresh terminal.
2
Launch Headmaster
Restart Headmaster — it rescans
PATH on launch.3
Pick the agent
The detected CLI agents appear on the welcome screen alongside the built-in agent. Pick one and start a conversation.
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.
Custom agents
Any protocol-compatible CLI can be added, even if it’s not on the auto-detect list:1
Open Agent Management
Go to Settings → Agent Management → Custom Agents.
2
Add a custom agent
Click Add custom agent, enter the CLI command, a display name, and any required arguments.
3
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.
- Configure agent-specific settings (model defaults, allowed tools).
- Rescan — forces a re-scan of your
PATHfor newly installed CLIs.
Preset management
Presets are saved combinations of agent + model + specialist + settings. Create a preset for a common workflow (e.g., “Code Review” = Claude Code + Sonnet + The Architect), switch between them from the specialist picker, and export them as JSON to share with your team.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.Connections (MCP)
Add MCP servers that sync to all your CLI agents.
Specialists
Assign specific backend agents per specialist.