Custom agents

An agent is a named setup for Hull: a system prompt, an optional model, and the tools it's allowed to use. Hull comes with built-in agents, and you can add your own, such as a docs writer that only edits Markdown or a reviewer that can't change files.

Built-in agentsCopy Anchor Link

Primary agents are the ones you pick and talk to. Subagents are started by other agents for a focused piece of work. See Subagents.

Switch primary agents with Tab in the CLI, Cmd+. / Ctrl+. in VS Code, or the agent picker. Set default_agent in hull.json to start with a different agent.

Create an agentCopy Anchor Link

Ask HullCopy Anchor Link

The quickest way is to describe the agent you want:

Create an agent called docs-writer that can read anything but only edit Markdown files.

In the CLI, hull agent create walks you through the same thing and writes the file for you.

Write a Markdown fileCopy Anchor Link

Create a .md file in an agents folder. The file name becomes the agent's name, the frontmatter sets its options, and the body is its prompt:

Hull also reads agent/ as well as agents/, and the legacy .hullcode/ folders.

.hull/agents/docs-writer.md:

---
description: Writes and edits technical documentation
mode: primary
color: "#10B981"
permission:
  edit:
    "*": deny
    "*.md": allow
  bash: deny
---

You are a technical writer. Write clear, well-structured documentation
with short examples. Only edit Markdown files.

Or use configCopy Anchor Link

Define the same agent under agent in hull.json:

{
  "agent": {
    "docs-writer": {
      "description": "Writes and edits technical documentation",
      "mode": "primary",
      "prompt": "You are a technical writer...",
      "permission": {
        "edit": { "*": "deny", "*.md": "allow" },
        "bash": "deny"
      }
    }
  }
}

To keep a long prompt in its own file, use "prompt": "{file:./prompts/docs-writer.md}".

In VS Code you can also create and edit agents in Settings > Agent Behaviour > Agents, and import or export agent definitions there.

OptionsCopy Anchor Link

Other options are passed to the model provider, so you can set provider-specific parameters.

Change a built-in agentCopy Anchor Link

Use a built-in agent's name to change only the parts you specify. Everything else stays the same:

{
  "agent": {
    "code": {
      "steps": 50,
      "permission": { "bash": { "*": "ask", "npm test *": "allow" } }
    },
    "general": { "disable": true }
  }
}

Where agents come fromCopy Anchor Link

Hull merges agent settings from built-in defaults, your global config, the project's config and agent Markdown files. When the same agent is defined in several places, the settings are merged field by field, so you can override a single option.

If you belong to a Hull organization, your admins can also provide agents. They appear in your agent list next to your own, can't be removed locally, and take priority over a built-in agent with the same name. To change one, ask whoever manages Hull for your organization.

Project agents load only after you trust the project. To check what an agent ends up with, run hull debug agent <name>, or hull agent list to see all agents.

Migrate legacy modesCopy Anchor Link

Hull converts custom modes from older versions into agents when it starts. It reads them from:

• .hullcodemodes in the project
• ~/.hullcodemodes
• custom_modes.yaml in the old extension's settings folder

Each mode becomes a primary agent: its role definition and custom instructions become the prompt, and its tool groups (read, edit, command, browser, mcp) become permission rules. Groups a mode didn't have are denied. Modes named after built-in agents (code, architect, ask, debug) are skipped, and the retired Orchestrator mode is not migrated: use subagents instead.

To edit a migrated mode, create an agent file with the same name in .hull/agents/.

RelatedCopy Anchor Link

• Subagents
• Permissions
• Skills