packages/kilo-docs/pages/code-with-ai/gastown/mayor.md
The Mayor is your primary interface to a Gas Town. It's a persistent conversational agent that coordinates work, answers questions, and takes action on your behalf.
The Mayor operates as a technical lead that:
Unlike polecats (which spin up to work on specific beads), the Mayor runs persistently. It's always available, even when no coding agents are active.
{% browserFrame url="app.kilo.ai/gastown/town" caption="The Mayor chat — always available for coordination and questions" %} {% image src="/docs/img/gastown/gt-town-overview.png" alt="Gas Town Mayor chat interface" /%} {% /browserFrame %}
Open the Mayor panel from your town dashboard. The conversation is persistent — the Mayor remembers context from previous messages within the same session.
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:
"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.
"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 inspect agent status messages, review feedback, and container logs to diagnose issues.
"Switch the model to Auto Frontier for this town" "Set max polecats to 4" "Add a custom instruction: always use TypeScript strict mode"
The Mayor can modify town settings on your behalf through natural language.
The Mayor has access to 21 specialized tools for town management:
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
gt_report_bug | File a bug report on the Gastown GitHub repo (checks for duplicates first) |
These tools are used automatically when you make requests — you don't need to invoke them directly.
Instead of: "Fix the bugs"
Try: "Fix the TypeScript type errors in src/auth/. There are 3 reported in the CI output."
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."
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 resolve issues (reset agents, close stuck convoys, re-dispatch work) without you needing to dig into the admin panel.