Agents
The built-in agents Hull ships with, what each one can do, and how to switch between them.
An agent is the persona Hull works as in a session. Each agent has its own instructions and its own permissions, so you pick the one that fits the job: build something, plan it first, track down a bug, or ask a question without touching any files.
Built-in agents
You work directly with four primary agents. Code is the default.
| Agent | Use it to | What it can do |
|---|---|---|
| Code | Write code, implement features and make changes across your project. | Every tool, subject to your permissions. |
| Plan | Agree on an approach before anything changes. | Reads and searches your code, asks questions, and writes plan files only (for example .hull/plans/*.md). All other edits are denied. |
| Debug | Diagnose and fix a bug methodically. | The same tools as Code, with instructions focused on reproducing, isolating and fixing issues. |
| Ask | Get explanations and answers about your code. | Read-only. It can read, search, fetch web pages and run read-only shell commands. Edits and subagents are blocked. |
Older configs that refer to the build agent still work. Hull treats build as code.
Subagents
Primary agents can hand work to subagents, which run in their own isolated session and report back. Hull includes two:
- general researches complex questions and runs multi-step work, including several units of work in parallel.
- explore is a fast, read-only agent for finding files, searching code and answering questions about a codebase.
You can also define your own. See Subagents.
Switch agents
- Choose an agent from the agent picker under the composer.
- Press ⌘ . for the next agent, or ⌘ ⇧ . for the previous one.
- Type
/plan, or choose Plan mode from the + menu, to plan first. See Plan mode.
Change the default agent
Set default_agent in hull.jsonc to start every session with a different primary agent:
{
"default_agent": "plan"
}The default must be a primary agent. A subagent or a hidden agent can't be the default.
Custom agents
Create your own agents with their own instructions, model, tool access and permissions, or adjust the built-in ones. See Custom modes for primary agents and Subagents for delegates.