Agent Management Commands

This page documents the Agent Management commands for the gt CLI.

gt agents

Switch between Gas Town agent sessions

Display a popup menu of core Gas Town agent sessions.

Shows Mayor, Deacon, Witnesses, Refineries, and Crew workers.
Polecats are hidden (use 'gt polecat list' to see them).

The menu appears as a tmux popup for quick session switching.

Usage:
  gt agents [flags]
  gt agents [command]

Aliases:
  agents, ag

Available Commands:
  check       Check for identity collisions and stale locks
  fix         Fix identity collisions and clean up stale locks
  list        List agent sessions (no popup)
  state       Get or set operational state on agent beads

Flags:
  -a, --all    Include polecats in the menu
  -h, --help   help for agents

Use "gt agents [command] --help" for more information about a command.

gt boot

Manage Boot (Deacon watchdog)

Manage Boot - the daemon's watchdog for Deacon triage.

Boot is a special dog that runs fresh on each daemon tick. It observes
the system state and decides whether to start/wake/nudge/interrupt the
Deacon, or do nothing. This centralizes the "when to wake" decision in
an agent that can reason about it.

Boot lifecycle:
  1. Daemon tick spawns Boot (fresh each time)
  2. Boot runs triage: observe, decide, act
  3. Boot cleans inbox (discards stale handoffs)
  4. Boot exits (or handoffs in non-degraded mode)

Location: ~/gt/deacon/dogs/boot/
Session: gt-boot

Usage:
  gt boot [command]

Available Commands:
  spawn       Spawn Boot for triage
  status      Show Boot status
  triage      Run triage directly (degraded mode)

Flags:
  -h, --help   help for boot

Use "gt boot [command] --help" for more information about a command.

gt callbacks

Handle agent callbacks

Handle callbacks from agents during Deacon patrol.

Callbacks are messages sent to the Mayor from:
- Witnesses reporting polecat status
- Refineries reporting merge results
- Polecats requesting help or escalation
- External triggers (webhooks, timers)

This command processes the Mayor's inbox and handles each message
appropriately, routing to other agents or updating state as needed.

Usage:
  gt callbacks [command]

Available Commands:
  process     Process pending callbacks

Flags:
  -h, --help   help for callbacks

Use "gt callbacks [command] --help" for more information about a command.

gt deacon

Manage the Deacon (town-level watchdog)

Manage the Deacon - the town-level watchdog for Gas Town.

The Deacon ("daemon beacon") is the only agent that receives mechanical
heartbeats from the daemon. It monitors system health across all rigs:
  - Watches all Witnesses (are they alive? stuck? responsive?)
  - Manages Dogs for cross-rig infrastructure work
  - Handles lifecycle requests (respawns, restarts)
  - Receives heartbeat pokes and decides what needs attention

The Deacon patrols the town; Witnesses patrol their rigs; Polecats work.

Role shortcuts: "deacon" in mail/nudge addresses resolves to this agent.

Usage:
  gt deacon [flags]
  gt deacon [command]

Aliases:
  deacon, dea

Available Commands:
  attach          Attach to the Deacon session
  cleanup-orphans Clean up orphaned claude subagent processes
  force-kill      Force-kill an unresponsive agent session
  health-check    Send a health check ping to an agent and track response
  health-state    Show health check state for all monitored agents
  heartbeat       Update the Deacon heartbeat
  pause           Pause the Deacon to prevent patrol actions
  restart         Restart the Deacon session
  resume          Resume the Deacon to allow patrol actions
  stale-hooks     Find and unhook stale hooked beads
  start           Start the Deacon session
  status          Check Deacon session status
  stop            Stop the Deacon session
  trigger-pending Trigger pending polecat spawns (bootstrap mode)
  zombie-scan     Find and clean zombie Claude processes not in active tmux sessions

Flags:
  -h, --help   help for deacon

Use "gt deacon [command] --help" for more information about a command.

gt dog

Manage dogs (cross-rig infrastructure workers)

Manage dogs - reusable workers for infrastructure and cleanup.

CATS VS DOGS:
  Polecats (cats) build features. One rig. Ephemeral (one task, then nuked).
  Dogs clean up messes. Cross-rig. Reusable (multiple tasks, eventually recycled).

Dogs are managed by the Deacon for town-level work:
  - Infrastructure tasks (rebuilding, syncing, migrations)
  - Cleanup operations (orphan branches, stale files)
  - Cross-rig work that spans multiple projects

Each dog has worktrees into every configured rig, enabling cross-project
operations. Dogs return to idle state after completing work (unlike cats).

The kennel is at ~/gt/deacon/dogs/. The Deacon dispatches work to dogs.

Usage:
  gt dog [command]

Aliases:
  dog, dogs

Available Commands:
  add         Create a new dog in the kennel
  call        Wake idle dog(s) for work
  dispatch    Dispatch plugin execution to a dog
  list        List all dogs in the kennel
  remove      Remove dogs from the kennel
  status      Show detailed dog status

Flags:
  -h, --help   help for dog

Use "gt dog [command] --help" for more information about a command.

gt mayor

Manage the Mayor (Chief of Staff for cross-rig coordination)

Manage the Mayor - the Overseer's Chief of Staff.

The Mayor is the global coordinator for Gas Town:
  - Receives escalations from Witnesses and Deacon
  - Coordinates work across multiple rigs
  - Handles human communication when needed
  - Routes strategic decisions and cross-project issues

The Mayor is the primary interface between the human Overseer and the
automated agents. When in doubt, escalate to the Mayor.

Role shortcuts: "mayor" in mail/nudge addresses resolves to this agent.

Usage:
  gt mayor [flags]
  gt mayor [command]

Aliases:
  mayor, may

Available Commands:
  attach      Attach to the Mayor session
  restart     Restart the Mayor session
  start       Start the Mayor session
  status      Check Mayor session status
  stop        Stop the Mayor session

Flags:
  -h, --help   help for mayor

Use "gt mayor [command] --help" for more information about a command.

gt polecat

Manage polecats (ephemeral workers, one task then nuked)

Manage polecat lifecycle in rigs.

Polecats are EPHEMERAL workers: spawned for one task, nuked when done.
There is NO idle state. A polecat is either:
  - Working: Actively doing assigned work
  - Stalled: Session crashed mid-work (needs Witness intervention)
  - Zombie: Finished but gt done failed (needs cleanup)

Self-cleaning model: When work completes, the polecat runs 'gt done',
which pushes the branch, submits to the merge queue, and exits. The
Witness then nukes the sandbox. Polecats don't wait for more work.

Session vs sandbox: The Claude session cycles frequently (handoffs,
compaction). The git worktree (sandbox) persists until nuke. Work
survives session restarts.

Cats build features. Dogs clean up messes.

Usage:
  gt polecat [flags]
  gt polecat [command]

Aliases:
  polecat, polecats

Available Commands:
  check-recovery Check if polecat needs recovery vs safe to nuke
  gc             Garbage collect stale polecat branches
  git-state      Show git state for pre-kill verification
  identity       Manage polecat identities
  list           List polecats in a rig
  nuke           Completely destroy a polecat (session, worktree, branch, agent bead)
  remove         Remove polecats from a rig
  stale          Detect stale polecats that may need cleanup
  status         Show detailed status for a polecat
  sync           Sync beads for a polecat

Flags:
  -h, --help   help for polecat

Use "gt polecat [command] --help" for more information about a command.

gt refinery

Manage the Refinery (merge queue processor)

Manage the Refinery - the per-rig merge queue processor.

The Refinery serializes all merges to main for a rig:
  - Receives MRs submitted by polecats (via gt done)
  - Rebases work branches onto latest main
  - Runs validation (tests, builds, checks)
  - Merges to main when clear
  - If conflict: spawns FRESH polecat to re-implement (original is gone)

Work flows: Polecat completes → gt done → MR in queue → Refinery merges.
The polecat is already nuked by the time the Refinery processes.

One Refinery per rig. Persistent agent that processes work as it arrives.

Role shortcuts: "refinery" in mail/nudge addresses resolves to this rig's Refinery.

Usage:
  gt refinery [flags]
  gt refinery [command]

Aliases:
  refinery, ref

Available Commands:
  attach      Attach to refinery session
  blocked     List MRs blocked by open tasks
  claim       Claim an MR for processing
  queue       Show merge queue
  ready       List MRs ready for processing (unclaimed and unblocked)
  release     Release a claimed MR back to the queue
  restart     Restart the refinery
  start       Start the refinery
  status      Show refinery status
  stop        Stop the refinery
  unclaimed   List unclaimed MRs available for processing

Flags:
  -h, --help   help for refinery

Use "gt refinery [command] --help" for more information about a command.

gt role

Show or manage agent role

Display the current agent role and its detection source.

Role is determined by:
1. GT_ROLE environment variable (authoritative if set)
2. Current working directory (fallback)

If both are available and disagree, a warning is shown.

Usage:
  gt role [flags]
  gt role [command]

Available Commands:
  def         Display role definition (session, health, env config)
  detect      Force cwd-based role detection (debugging)
  env         Print export statements for current role
  home        Show home directory for a role
  list        List all known roles
  show        Show current role

Flags:
  -h, --help   help for role

Use "gt role [command] --help" for more information about a command.

gt session

Manage polecat sessions

Manage tmux sessions for polecats.

Sessions are tmux sessions running Claude for each polecat.
Use the subcommands to start, stop, attach, and monitor sessions.

TIP: To send messages to a running session, use 'gt nudge' (not 'session inject').
The nudge command uses reliable delivery that works correctly with Claude Code.

Usage:
  gt session [flags]
  gt session [command]

Aliases:
  session, sess

Available Commands:
  at          Attach to a running session
  capture     Capture recent session output
  check       Check session health for polecats
  inject      Send message to session (prefer 'gt nudge')
  list        List all sessions
  restart     Restart a polecat session
  start       Start a polecat session
  status      Show session status details
  stop        Stop a polecat session

Flags:
  -h, --help   help for session

Use "gt session [command] --help" for more information about a command.

gt witness

Manage the Witness (per-rig polecat health monitor)

Manage the Witness - the per-rig polecat health monitor.

The Witness patrols a single rig, watching over its polecats:
  - Detects stalled polecats (crashed or stuck mid-work)
  - Nudges unresponsive sessions back to life
  - Cleans up zombie polecats (finished but failed to exit)
  - Nukes sandboxes when polecats complete via 'gt done'

The Witness does NOT force session cycles or interrupt working polecats.
Polecats manage their own sessions (via gt handoff). The Witness handles
failures and edge cases only.

One Witness per rig. The Deacon monitors all Witnesses.

Role shortcuts: "witness" in mail/nudge addresses resolves to this rig's Witness.

Usage:
  gt witness [flags]
  gt witness [command]

Available Commands:
  attach      Attach to witness session
  restart     Restart the witness
  start       Start the witness
  status      Show witness status
  stop        Stop the witness

Flags:
  -h, --help   help for witness

Use "gt witness [command] --help" for more information about a command.