Diagnostics
Commands for monitoring, auditing, and troubleshooting Gas Town. These tools provide visibility into system health, agent activity, resource usage, and operational state.
Town Status
gt status
Display overall town status.
gt status [options]
Description: Shows the current state of the Gas Town workspace including registered rigs, active polecats, and agent status.
Options:
| Flag | Description |
|---|---|
--fast | Skip mail lookups for faster execution |
--json | Output as JSON |
--verbose, -v | Show detailed multi-line output per agent |
--watch, -w | Watch mode: refresh status continuously |
--interval, -n | Refresh interval in seconds (default: 2) |
Aliases: stat
Example:
# Quick status
gt status
# Watch mode with custom interval
gt status --watch --interval 5
# Fast mode (skip mail lookups)
gt status --fast
gt whoami
Show the identity used for mail commands.
gt whoami
Description: Displays the identity determined by the GT_ROLE environment variable. If set, you are an agent session. If not, you are the overseer (human). Use the --identity flag with mail commands to override.
Example:
gt whoami
Activity & Monitoring
gt activity
Show recent system activity.
gt activity [options]
Description: Displays a chronological log of significant events across the town, including agent starts/stops, work assignments, completions, escalations, and merges.
Options:
| Flag | Description |
|---|---|
--rig <name> | Filter to a specific rig |
--agent <name> | Filter to a specific agent |
--type <type> | Filter by event type: work, agent, merge, escalation, mail |
--since <duration> | Show events since (e.g., 1h, 30m, 1d) |
--limit <n> | Maximum events to show |
--json | Output in JSON format |
Example:
# Recent activity
gt activity
# Last hour of work events
gt activity --type work --since 1h
# Activity for a specific rig
gt activity --rig myproject --limit 50
Sample output:
TIME TYPE AGENT EVENT
14:30 work polecat/toast Completed gt-abc12 (fix/login-bug)
14:28 merge refinery Merged mr-001 to main
14:25 agent witness Started patrol cycle
14:20 work polecat/alpha Started gt-def34 (feat/email-validation)
14:15 escalation polecat/bravo Escalated gt-ghi56 (P2: need design input)
gt audit
Generate an audit report.
gt audit [options]
Description: Produces a comprehensive audit of system state, including agent uptime, work throughput, error rates, and resource usage. Useful for periodic reviews and compliance.
Options:
| Flag | Description |
|---|---|
--since <duration> | Audit period (default: 24h) |
--rig <name> | Audit a specific rig |
--format <fmt> | Output format: text, json, csv |
--output <file> | Write report to a file |
Example:
# Daily audit
gt audit
# Weekly audit for a specific rig
gt audit --since 7d --rig myproject --format json
# Export to file
gt audit --output audit-report.json --format json
gt feed
Watch the live activity feed.
gt feed [options]
Description: Displays a real-time stream of system events. Similar to gt activity but shows events as they happen. Press Ctrl+C to exit.
Options:
| Flag | Description |
|---|---|
--rig <name> | Filter to a specific rig |
--type <type> | Filter by event type |
--quiet | Show only significant events |
Example:
# Watch all events
gt feed
# Watch a specific rig
gt feed --rig myproject
# Watch only work and merge events
gt feed --type work,merge
gt trail
Show the execution trail for a specific bead or agent.
gt trail <target> [options]
Description: Traces the full lifecycle of a bead or agent, showing every state change, assignment, message, and action in chronological order.
Options:
| Flag | Description |
|---|---|
--json | Output in JSON format |
--verbose | Include full message content |
Example:
# Trail a bead
gt trail gt-abc12
# Trail an agent
gt trail polecat/toast
Sample output (bead trail):
gt-abc12: Fix login redirect loop
14:00 created by mayor priority=high type=bug
14:05 assigned to myproject via gt sling
14:05 hooked on polecat/toast branch=fix/login-bug
14:10 started by polecat/toast
14:25 committed 4 files changed
14:28 done by polecat/toast exit=COMPLETED
14:28 submitted mr-001 to merge queue
14:30 merged to main by refinery
14:30 closed auto
gt log
View system logs.
gt log [options]
Description: Accesses the raw event log (.events.jsonl) with filtering and formatting options. More detailed than gt activity -- includes internal system events.
Options:
| Flag | Description |
|---|---|
--level <level> | Filter: debug, info, warn, error |
--since <duration> | Time filter |
--limit <n> | Maximum entries |
--follow, -f | Follow the log in real time |
--json | Raw JSON output |
Example:
# Recent errors
gt log --level error
# Follow log in real time
gt log -f
# Debug output for the last 30 minutes
gt log --level debug --since 30m
gt doctor
Diagnose system health issues.
gt doctor [options]
Description: Runs a comprehensive health check of the Gas Town installation, verifying dependencies, configuration, agent state, database integrity, and common issues.
Options:
| Flag | Description |
|---|---|
--fix | Attempt to fix detected issues |
--verbose | Show detailed check results |
--json | Output in JSON format |
Example:
# Run health check
gt doctor
# Run and attempt fixes
gt doctor --fix
Sample output:
Gas Town Doctor
===============
[OK] Go version: 1.23.4
[OK] Git version: 2.43.0
[OK] Beads (bd) version: 0.44.2
[OK] SQLite3 available
[OK] Tmux version: 3.4
[OK] Claude Code available
[OK] Workspace structure valid
[OK] Beads database integrity
[WARN] Stale polecat worktree: myproject/polecats/toast (2d old)
[OK] Daemon running (PID 1200)
[OK] Mayor session active
[OK] Deacon session active
11 checks passed, 1 warning, 0 errors
Run gt doctor after installation, after upgrading Gas Town, or whenever something seems wrong. It catches most common configuration issues.
gt dashboard
Start the convoy tracking web dashboard.
gt dashboard [options]
Description: Starts a web server that displays a convoy tracking dashboard with real-time status indicators, progress tracking, and last activity indicators. Auto-refreshes every 30 seconds via htmx.
Options:
| Flag | Description |
|---|---|
--port <number> | HTTP port to listen on (default: 8080) |
--open | Open browser automatically |
Example:
# Start on default port
gt dashboard
# Start on custom port
gt dashboard --port 3000
# Start and open browser
gt dashboard --open
gt costs
Show resource usage and cost metrics.
gt costs [options]
Description: Displays token usage, API costs, agent session time, and other resource metrics. Helps track spending across agents and rigs.
Options:
| Flag | Description |
|---|---|
--since <duration> | Time period (default: 24h) |
--rig <name> | Filter by rig |
--agent <name> | Filter by agent |
--format <fmt> | Output format: text, json, csv |
--group-by <field> | Group by: rig, agent, role, hour |
Example:
# Daily costs
gt costs
# Weekly costs by rig
gt costs --since 7d --group-by rig
# Costs for a specific agent
gt costs --agent polecat/toast
Sample output:
Gas Town Costs (last 24h)
=========================
Total tokens: 2,450,000 (input: 1,800,000 / output: 650,000)
Estimated cost: $12.35
By rig:
myproject $8.20 (66%)
docs $2.15 (17%)
backend $2.00 (16%)
By role:
polecats $9.50 (77%)
refinery $1.85 (15%)
mayor $0.60 (5%)
other $0.40 (3%)
gt cleanup
Clean up temporary files and stale resources.
gt cleanup [options]
Description: Removes temporary files, stale worktrees, dead session artifacts, and other accumulated debris. A more action-oriented companion to gt stale.
Options:
| Flag | Description |
|---|---|
--rig <name> | Clean up a specific rig |
--all | Clean up across all rigs |
--dry-run | Show what would be cleaned without doing it |
--force | Skip confirmation |
--age <duration> | Only clean items older than this (default: 24h) |
Example:
# Preview cleanup
gt cleanup --dry-run
# Clean up everything
gt cleanup --all --force
# Clean up a specific rig
gt cleanup --rig myproject --age 12h
gt patrol digest
Generate a patrol cycle digest.
gt patrol digest [options]
Description: Summarizes the results of recent patrol cycles run by persistent agents (Deacon, Witnesses, Refinery). Shows what was detected and what actions were taken.
Options:
| Flag | Description |
|---|---|
--since <duration> | Time period (default: 1h) |
--agent <name> | Filter to a specific agent's patrols |
--json | Output in JSON format |
Example:
gt patrol digest
gt patrol digest --since 6h --agent witness
Orphan Management
gt orphans
Find orphaned resources.
gt orphans [options]
Description: Identifies orphaned resources across the town -- processes without parent agents, worktrees without polecats, branches without beads, and other disconnected artifacts.
Options:
| Flag | Description |
|---|---|
--json | Output in JSON format |
--verbose | Show detailed information about each orphan |
Example:
gt orphans
Sample output:
Orphaned Resources
==================
Processes (2):
PID 4521 claude session (no parent agent)
PID 4789 claude session (no parent agent)
Worktrees (1):
myproject/polecats/ghost/ (no active polecat)
Branches (3):
fix/old-bug (no associated bead)
feat/abandoned (no associated bead)
tmp/experiment (no associated bead)
gt orphans procs
List orphaned processes specifically.
gt orphans procs [options]
Options:
| Flag | Description |
|---|---|
--json | Output in JSON format |
Example:
gt orphans procs
gt orphans kill
Terminate orphaned processes.
gt orphans kill [options]
Description: Kills orphaned processes that have no parent agent managing them. These are typically leftover sessions from crashed agents.
Options:
| Flag | Description |
|---|---|
--force | Kill without confirmation |
--dry-run | Show what would be killed |
Example:
gt orphans kill --dry-run
gt orphans kill --force
Verify orphans are truly orphaned before killing. Use gt orphans procs first to review, then gt orphans kill --dry-run to preview the action.
Peek & Sessions
For session handoffs, molecules, and formulas, see the Session & Handoff page.
gt peek
Peek at an agent's current state without interrupting it.
gt peek <agent> [options]
Description: Non-invasively inspects what an agent is currently doing, including its hook state, recent activity, and resource usage. Does not send any messages to the agent.
Options:
| Flag | Description |
|---|---|
--json | Output in JSON format |
Example:
gt peek polecat/toast
gt peek witness --rig myproject
gt peek mayor
Sample output:
Peek: polecat/toast (myproject)
Status: running
Hook: gt-abc12 "Fix login redirect loop"
Last activity: 2m ago (editing src/auth/callback.ts)
Session: sess-xyz789
Commits: 3 (uncommitted changes: 2 files)
Branch: fix/login-bug
gt session
Manage tmux sessions for polecats.
gt session <subcommand> [options]
Aliases: sess
Subcommands:
| Subcommand | Description |
|---|---|
gt session list | List all sessions |
gt session status <name> | Show session status details |
gt session start <name> | Start a polecat session |
gt session stop <name> | Stop a polecat session |
gt session restart <name> | Restart a polecat session |
gt session at <name> | Attach to a running session |
gt session capture <name> | Capture recent session output |
gt session check <name> | Check session health |
gt session inject <name> | Send message to session (prefer gt nudge) |
Example:
# List all sessions
gt session list
# Check session health
gt session check toast
# Capture recent output
gt session capture toast
# Restart a session
gt session restart toast
To send messages to a running session, use gt nudge instead of gt session inject. The nudge command uses reliable delivery that works correctly with Claude Code.