The Mayor
Plan work, check status and change settings by talking to your town's coordinator
The Mayor is your main interface to a Hull Fleet town. It is a conversational agent that coordinates work, answers questions, and takes action on your behalf.
What the Mayor Does
The Mayor operates as a technical lead that:
- Plans work: converts high-level descriptions into convoys and beads
- Reports status: knows what every agent is doing, what's stuck, what's shipped
- Triages issues: investigates failures, stuck agents, and escalations
- Manages work and agents: edits and reassigns beads, starts and closes convoys, resets stuck agents
- Answers questions: about the codebase, work history, and town state
Polecats start up to work on specific beads. The Mayor stays with the town and is available even when no coding agents are working. In a new town, you may need to click Start Mayor the first time.
Talking to the Mayor
Open the Mayor tab at the bottom of the town. The Mayor keeps context from earlier messages in the same conversation.
Planning Work
Ask the Mayor to create work for the town:
"Create a convoy to add authentication to the API. We need JWT token generation, middleware for protected routes, and integration tests."
The Mayor will:
- Break this into individual beads with dependencies
- Propose a convoy plan for your review
- Create the convoy (staged by default, so you can review before agents start)
Checking Status
"What's everyone working on?" "Is anything stuck?" "How did the last convoy go?"
The Mayor has full visibility into agent state, bead progress, and recent history.
Investigating Problems
"The auth refactor bead has been in progress for 20 minutes, what's happening?" "Why did the refinery reject the last review?"
The Mayor can look at agent status, bead history and review feedback to work out what went wrong.
Finding settings
"Open the town settings"
The Mayor can open pages and drawers in the dashboard for you, such as a bead, a convoy, an agent or Settings. Change settings yourself on the Settings page; the Mayor can suggest what to change.
Mayor Tools
The Mayor uses a set of tools to manage the town. You'll see their names in the Mayor's activity:
Work Creation
| Tool | What it does |
|---|---|
gt_sling | Delegate a single task to a polecat agent in a specific rig |
gt_sling_batch | Create a multi-bead convoy with dependency ordering, merge mode, and staging options |
Convoy Management
| Tool | What it does |
|---|---|
gt_convoy_status | Show detailed status of a convoy, each bead's progress and assignee |
gt_convoy_start | Start a staged convoy, begin agent dispatch |
gt_convoy_close | Force-close a convoy and optionally its tracked beads |
gt_convoy_update | Edit convoy metadata (merge mode, feature branch) |
gt_convoy_add_bead | Add an existing bead to a convoy's tracking |
gt_convoy_remove_bead | Remove a bead from a convoy |
gt_list_convoys | List active convoys with progress counts |
Bead Management
| Tool | What it does |
|---|---|
gt_bead_update | Edit a bead's status, title, body, priority, labels, or dependencies |
gt_bead_reassign | Reassign a bead to a different agent |
gt_bead_delete | Delete one or more beads (supports bulk, up to 5000) |
gt_list_beads | List beads in a rig, filterable by status and type |
Agent Management
| Tool | What it does |
|---|---|
gt_agent_reset | Force-reset an agent to idle, unhooking it from any bead |
gt_nudge | Send a real-time nudge to a polecat (immediate, wait-idle, or queued) |
gt_list_agents | List all agents in a rig with their roles and status |
gt_mail_send | Send a persistent mail message to any agent in any rig |
Town & UI
| Tool | What it does |
|---|---|
gt_list_rigs | List all rigs (repositories) in the town |
gt_ui_action | Trigger UI actions, open drawers, navigate pages, highlight items |
gt_escalation_acknowledge | Acknowledge an escalation as reviewed |
When a town is connected to Hull Commons, the Mayor also gets tools to browse, claim, post and complete Hull Commons items.
The Mayor picks tools automatically. You don't call them yourself.
Tips for Effective Communication
Be specific about scope
Instead of: "Fix the bugs"
Try: "Fix the TypeScript type errors in src/auth/. There are 3 reported in the CI output."
Use convoys for complex work
Instead of: "Add a user dashboard with charts, settings, and notifications"
Try: "Create a staged convoy for the user dashboard. Break it into: 1) dashboard layout and navigation, 2) chart components with mock data, 3) settings page, 4) notification system. Each should build on the previous."
Let the Mayor triage
When something goes wrong, ask the Mayor before investigating yourself:
"Bead abc123 has been stuck for 30 minutes, can you investigate?"
The Mayor can often diagnose and fix problems itself, for example by resetting an agent, closing a stuck convoy or re-dispatching work.
Mayor Limitations
- The Mayor coordinates; polecats write the code.
- It sees what happens inside your town, not in outside systems.
- Its context is limited, so very long conversations can lose early details.