Concepts
Towns, rigs, beads, convoys and the agents that work on them
Hull Fleet is built from a few building blocks. Knowing them makes it easier to plan work and understand what agents are doing.
Towns
A town is a persistent workspace where agents operate on your code. It maintains:
- Configuration: models, merge strategy, review settings, custom instructions
- Agent state: which agents exist, what they're working on, their capabilities
- Work history: every bead that's been created, worked on, reviewed, and closed
- Rig connections: which repositories are connected and how they're configured
A town belongs to you or to an organization. Organization towns are shared with members of that organization.
Beads
A bead is the fundamental unit of work. Every task, review, and coordination action is represented as a bead with a lifecycle:
| Status | What's happening |
|---|---|
open | Waiting to be picked up by an agent |
in_progress | An agent is actively working on it |
in_review | Work is complete, awaiting review by the refinery |
closed | Successfully completed and merged |
failed | Could not be completed, for example after repeated failed dispatch attempts |
Bead Types
| Type | Purpose |
|---|---|
issue | A coding task: bug fix, feature, refactor |
merge_request | A review task for the refinery |
convoy | A container for multi-step workflows |
escalation | An issue the agents couldn't resolve, needs human input |
message | Inter-agent communication |
Convoys
A convoy is a multi-bead workflow where tasks can depend on each other. Convoys let you express larger work as a set of tasks with dependencies between them.
When you create a convoy, you define:
- Tasks: what needs to be done (each becomes a bead)
- Dependencies: which tasks must complete before others can start
- Merge mode: whether beads land on a shared convoy branch first (Review then land) or each gets its own pull request (Review and merge)
Hull Fleet only dispatches a bead once the beads it depends on are done, so later work builds on earlier, reviewed work.
Staged Convoys
Convoys can be staged: created but not started. Review the plan, then start the convoy when you're ready. New towns stage convoys by default.
Rigs
A rig connects a repository to your town. Each rig has:
- Its own set of agents (polecats, refinery)
- A default branch
- Optional overrides of town settings, such as models, review mode and merge strategy
A town can have multiple rigs: useful when your project spans several repositories.
Agents
Agents are the workers in your town. Each has a specialized role:
Polecats (Coding Agents)
Polecats do the actual software engineering:
- Read and understand your codebase
- Write code changes in isolated git worktrees
- Run tests and commands to verify their work
- Push branches when done
Several polecats can work in parallel on different beads. Set the limit with Max Polecats per Rig in Settings.
Each polecat gets its own git worktree, they never conflict with each other or with your local development.
The Refinery (Review Agent)
The refinery is the quality gate. When a polecat finishes a bead:
- The refinery runs your quality gates and reviews the diff
- It checks for problems, convention issues and missing tests
- It either approves the work or requests changes
- If it requests changes, a polecat revises and resubmits
One agent writes and another critiques, so work improves before it lands.
The Mayor (Coordination Agent)
The mayor is your interface to the town:
- Plans convoys from high-level descriptions
- Reports on status and progress
- Triages issues and escalations
- Manages agent configuration
- Answers questions about the codebase and work history
The mayor runs persistently, always available for conversation.
The scheduler
Behind the scenes, a scheduler keeps the town moving. While agents are working it checks every few seconds to:
- Process events such as agent completions, status changes and failures
- Decide which beads need agents and which convoys can advance
- Dispatch agents, create reviews and update convoy progress
- Prevent double assignments and retry failed dispatches a bounded number of times
You don't interact with it directly.
Write, review, revise
Rather than trusting a single agent's output, each piece of work goes through a write and review cycle:
The cycle compounds with convoys:
- Bead 1: Explore the codebase → reviewed → merged to convoy branch
- Bead 2: Design the schema (builds on bead 1's context) → reviewed → merged
- Bead 3: Implement the feature (builds on beads 1+2) → reviewed → merged
- Landing review: with Review then land, the full convoy branch is reviewed as one change before it goes to your default branch
See Review and merge for review settings, and Hull code review to add another review pass on pull requests.
How It All Fits Together
| Component | Responsibility |
|---|---|
| You | Describe work, review PRs, set direction |
| Mayor | Plan, coordinate, communicate |
| Scheduler | Assign work, dispatch agents, enforce limits |
| Polecats | Write code, run tests, push branches |
| Refinery | Review, critique, merge |
| Container | Isolated environment with git, tools, runtime |
| Rig | Repository connection and configuration |