Work Management Commands

Utilities for managing beads across repositories.

Usage:
  gt bead [command]

Aliases:
  bead, bd

Available Commands:
  move        Move a bead to a different repository
  read        Show details of a bead (alias for 'show')
  show        Show details of a bead

Flags:
  -h, --help   help for bead

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

Display the content of a bead (issue, task, molecule, etc.).

This is a convenience wrapper around 'bd show' that integrates with gt.
Accepts any bead ID (bd-*, hq-*, mol-*).

Examples:
  gt cat bd-abc123       # Show a bead
  gt cat hq-xyz789       # Show a town-level bead
  gt cat bd-abc --json   # Output as JSON

Usage:
  gt cat <bead-id> [flags]

Flags:
  -h, --help   help for cat
      --json   Output as JSON

Close one or more issues.

If no issue ID is provided, closes the last touched issue (from most recent
create, update, show, or close operation).

Usage:
  bd close [id...] [flags]

Flags:
      --continue         Auto-advance to next step in molecule
  -f, --force            Force close pinned issues
  -h, --help             help for close
      --no-auto          With --continue, show next step but don't claim it
  -r, --reason string    Reason for closing
      --session string   Claude Code session ID (or set CLAUDE_SESSION_ID env var)
      --suggest-next     Show newly unblocked issues after closing

Global Flags:
      --actor string            Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
      --allow-stale             Allow operations on potentially stale data (skip staleness check)
      --db string               Database path (default: auto-discover .beads/*.db)
      --json                    Output in JSON format
      --lock-timeout duration   SQLite busy timeout (0 = fail immediately if locked) (default 30s)
      --no-auto-flush           Disable automatic JSONL sync after CRUD operations
      --no-auto-import          Disable automatic JSONL import when newer than DB
      --no-daemon               Force direct storage mode, bypass daemon if running
      --no-db                   Use no-db mode: load from JSONL, no SQLite
      --profile                 Generate CPU profile for performance analysis
  -q, --quiet                   Suppress non-essential output (errors only)
      --readonly                Read-only mode: block write operations (for worker sandboxes)
      --sandbox                 Sandbox mode: disables daemon and auto-sync
  -v, --verbose                 Enable verbose/debug output

Git commit wrapper that automatically sets git author identity for agents.

When run by an agent (GT_ROLE set), this command:
1. Detects the agent identity from environment variables
2. Converts it to a git-friendly name and email
3. Runs 'git commit' with the correct identity

The email domain is configurable in town settings (agent_email_domain).
Default: gastown.local

Examples:
  gt commit -m "Fix bug"              # Commit as current agent
  gt commit -am "Quick fix"           # Stage all and commit
  gt commit -- --amend                # Amend last commit

Identity mapping:
  Agent: gastown/crew/jack  →  Name: gastown/crew/jack
                                Email: gastown.crew.jack@gastown.local

When run without GT_ROLE (human), passes through to git commit with no changes.

Usage:
  gt commit [flags] [-- git-commit-args...]

[Help extracted from source - see github.com/steveyegge/gastown/issues/975]

Manage convoys - the primary unit for tracking batched work.

A convoy is a persistent tracking unit that monitors related issues across
rigs. When you kick off work (even a single issue), a convoy tracks it so
you can see when it lands and what was included.

WHAT IS A CONVOY:
  - Persistent tracking unit with an ID (hq-*)
  - Tracks issues across rigs (frontend+backend, beads+gastown, etc.)
  - Auto-closes when all tracked issues complete → notifies subscribers
  - Can be reopened by adding more issues

WHAT IS A SWARM:
  - Ephemeral: "the workers currently assigned to a convoy's issues"
  - No separate ID - uses the convoy ID
  - Dissolves when work completes

TRACKING SEMANTICS:
  - 'tracks' relation is non-blocking (tracked issues don't block convoy)
  - Cross-prefix capable (convoy in hq-* tracks issues in gt-*, bd-*)
  - Landed: all tracked issues closed → notification sent to subscribers

COMMANDS:
  create    Create a convoy tracking specified issues
  add       Add issues to an existing convoy (reopens if closed)
  close     Close a convoy (manually, regardless of tracked issue status)
  status    Show convoy progress, tracked issues, and active workers
  list      List convoys (the dashboard view)

Usage:
  gt convoy [flags]
  gt convoy [command]

Available Commands:
  add         Add issues to an existing convoy
  check       Check and auto-close completed convoys
  close       Close a convoy
  create      Create a new convoy
  list        List convoys
  status      Show convoy status
  stranded    Find stranded convoys with ready work but no workers

Flags:
  -h, --help          help for convoy
  -i, --interactive   Interactive tree view

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

Signal that your work is complete and ready for the merge queue.

This is a convenience command for polecats that:
1. Submits the current branch to the merge queue
2. Auto-detects issue ID from branch name
3. Notifies the Witness with the exit outcome
4. Exits the Claude session (polecats don't stay alive after completion)

Exit statuses:
  COMPLETED      - Work done, MR submitted (default)
  ESCALATED      - Hit blocker, needs human intervention
  DEFERRED       - Work paused, issue still open
  PHASE_COMPLETE - Phase done, awaiting gate (use --phase-complete)

Phase handoff workflow:
  When a molecule has gate steps (async waits), use --phase-complete to signal
  that the current phase is complete but work continues after the gate closes.
  The Witness will recycle this polecat and dispatch a new one when the gate
  resolves.

Examples:
  gt done                              # Submit branch, notify COMPLETED, exit session
  gt done --issue gt-abc               # Explicit issue ID
  gt done --status ESCALATED           # Signal blocker, skip MR
  gt done --status DEFERRED            # Pause work, skip MR
  gt done --phase-complete --gate g-x  # Phase done, waiting on gate g-x

Usage:
  gt done [flags]

Flags:
      --cleanup-status string   Git cleanup status: clean, uncommitted, unpushed, stash, unknown (ZFC: agent-observed)
      --gate string             Gate bead ID to wait on (with --phase-complete)
  -h, --help                    help for done
      --issue string            Source issue ID (default: parse from branch name)
      --phase-complete          Signal phase complete - await gate before continuing
  -p, --priority int            Override priority (0-4, default: inherit from issue) (default -1)
      --status string           Exit status: COMPLETED, ESCALATED, or DEFERRED (default "COMPLETED")

Manage workflow formulas - reusable molecule templates.

Formulas are TOML/JSON files that define workflows with steps, variables,
and composition rules. They can be "poured" to create molecules or "wisped"
for ephemeral patrol cycles.

Commands:
  list    List available formulas from all search paths
  show    Display formula details (steps, variables, composition)
  run     Execute a formula (pour and dispatch)
  create  Create a new formula template

Search paths (in order):
  1. .beads/formulas/ (project)
  2. ~/.beads/formulas/ (user)
  3. $GT_ROOT/.beads/formulas/ (orchestrator)

Examples:
  gt formula list                    # List all formulas
  gt formula show shiny              # Show formula details
  gt formula run shiny --pr=123      # Run formula on PR #123
  gt formula create my-workflow      # Create new formula template

Usage:
  gt formula [flags]
  gt formula [command]

Aliases:
  formula, formulas

Available Commands:
  create      Create a new formula template
  list        List available formulas
  run         Execute a formula
  show        Display formula details

Flags:
  -h, --help   help for formula

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

Gate commands for async coordination.

Most gate commands are in beads:
  bd gate create   - Create a gate (timer, gh:run, human, mail)
  bd gate show     - Show gate details
  bd gate list     - List open gates
  bd gate close    - Close a gate
  bd gate approve  - Approve a human gate
  bd gate eval     - Evaluate and close elapsed gates

The gt gate command provides Gas Town integration:
  gt gate wake     - Send wake mail to gate waiters after close

Usage:
  gt gate [command]

Available Commands:
  wake        Send wake mail to gate waiters

Flags:
  -h, --help   help for gate

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

End watch. Hand off to a fresh agent session.

This is the canonical way to end any agent session. It handles all roles:

  - Mayor, Crew, Witness, Refinery, Deacon: Respawns with fresh Claude instance
  - Polecats: Calls 'gt done --status DEFERRED' (Witness handles lifecycle)

When run without arguments, hands off the current session.
When given a bead ID (gt-xxx, hq-xxx), hooks that work first, then restarts.
When given a role name, hands off that role's session (and switches to it).

Examples:
  gt handoff                          # Hand off current session
  gt handoff gt-abc                   # Hook bead, then restart
  gt handoff gt-abc -s "Fix it"       # Hook with context, then restart
  gt handoff -s "Context" -m "Notes"  # Hand off with custom message
  gt handoff -c                       # Collect state into handoff message
  gt handoff crew                     # Hand off crew session
  gt handoff mayor                    # Hand off mayor session

The --collect (-c) flag gathers current state (hooked work, inbox, ready beads,
in-progress items) and includes it in the handoff mail. This provides context
for the next session without manual summarization.

Any molecule on the hook will be auto-continued by the new session.
The SessionStart hook runs 'gt prime' to restore context.

Usage:
  gt handoff [bead-or-role] [flags]

Flags:
  -c, --collect          Auto-collect state (status, inbox, beads) into handoff message
  -n, --dry-run          Show what would be done without executing
  -h, --help             help for handoff
  -m, --message string   Message body for handoff mail (optional)
  -s, --subject string   Subject for handoff mail (optional)
  -w, --watch            Switch to new session (for remote handoff) (default true)

Show what's on your hook, or attach new work.

With no arguments, shows your current hook status (alias for 'gt mol status').
With a bead ID, attaches that work to your hook.

The hook is the "durability primitive" - work on your hook survives session
restarts, context compaction, and handoffs. When you restart (via gt handoff),
your SessionStart hook finds the attached work and you continue from where
you left off.

Examples:
  gt hook                           # Show what's on my hook
  gt hook status                    # Same as above
  gt hook gt-abc                    # Attach issue gt-abc to your hook
  gt hook gt-abc -s "Fix the bug"   # With subject for handoff mail

Related commands:
  gt sling <bead>    # Hook + start now (keep context)
  gt handoff <bead>  # Hook + restart (fresh context)
  gt unsling         # Remove work from hook

Usage:
  gt hook [bead-id] [flags]
  gt hook [command]

Aliases:
  hook, work

Available Commands:
  show        Show what's on an agent's hook (compact)
  status      Show what's on your hook

Flags:
      --clear            Clear your hook (alias for 'gt unhook')
  -n, --dry-run          Show what would be done
  -f, --force            Replace existing incomplete hooked bead
  -h, --help             help for hook
      --json             Output as JSON (for status)
  -m, --message string   Message for handoff mail (optional)
  -s, --subject string   Subject for handoff mail (optional)

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

Agent-specific molecule workflow operations.

These commands operate on YOUR hook and YOUR attached molecules.
Use 'gt hook' to see what's on your hook (alias for 'gt mol status').

VIEWING YOUR WORK:
  gt hook              Show what's on your hook
  gt mol current       Show what you should be working on
  gt mol progress      Show execution progress

WORKING ON STEPS:
  gt mol step done     Complete current step (auto-continues)

LIFECYCLE:
  gt mol attach        Attach molecule to your hook
  gt mol detach        Detach molecule from your hook
  gt mol burn          Discard attached molecule (no record)
  gt mol squash        Compress to digest (permanent record)

TO DISPATCH WORK (with molecules):
  gt sling mol-xxx target   # Pour formula + sling to agent
  gt formulas               # List available formulas

Usage:
  gt mol [flags]
  gt mol [command]

Aliases:
  mol, molecule

Available Commands:
  attach           Attach a molecule to a pinned bead
  attach-from-mail Attach a molecule from a mail message
  attachment       Show attachment status of a pinned bead
  burn             Burn current molecule without creating a digest
  current          Show what agent should be working on
  detach           Detach molecule from a pinned bead
  progress         Show progress through a molecule's steps
  squash           Compress molecule into a digest
  status           Show what's on an agent's hook
  step             Molecule step operations

Flags:
  -h, --help   help for mol

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

Manage merge requests and the merge queue for a rig.

Alias: 'gt mr' is equivalent to 'gt mq' (merge request vs merge queue).

The merge queue tracks work branches from polecats waiting to be merged.
Use these commands to view, submit, retry, and manage merge requests.

Usage:
  gt mq [flags]
  gt mq [command]

Aliases:
  mq, mr

Available Commands:
  integration Manage integration branches for epics
  list        Show the merge queue
  next        Show the highest-priority merge request
  reject      Reject a merge request
  retry       Retry a failed merge request
  status      Show detailed merge request status
  submit      Submit current branch to the merge queue

Flags:
  -h, --help   help for mq

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

Find orphaned commits that were never merged to main.

Polecat work can get lost when:
- Session killed before merge
- Refinery fails to process
- Network issues during push

This command uses 'git fsck --unreachable' to find dangling commits,
filters to recent ones, and shows details to help recovery.

Examples:
  gt orphans              # Last 7 days (default)
  gt orphans --days=14    # Last 2 weeks
  gt orphans --all        # Show all orphans (no date filter)

Usage:
  gt orphans [flags]
  gt orphans [command]

Available Commands:
  kill        Remove all orphans (commits and processes)
  procs       Manage orphaned Claude processes

Flags:
      --all        Show all orphans (no date filter)
      --days int   Show orphans from last N days (default 7)
  -h, --help       help for orphans

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

Park current work on a gate, allowing the agent to exit safely.

When you need to wait for an external condition (timer, CI, human approval),
park your work on a gate. When the gate closes, you'll receive wake mail.

The park command:
  1. Saves your current hook state (molecule/bead you're working on)
  2. Adds you as a waiter on the gate
  3. Stores context notes in the parked state

After parking, you can exit the session safely. Use 'gt resume' to check
for cleared gates and continue work.

Examples:
  # Create a timer gate and park work on it
  bd gate create --await timer:30m --title "Coffee break"
  gt park <gate-id> -m "Taking a break, will resume auth work"

  # Park on a human approval gate
  bd gate create --await human:deploy-approval --notify ops/
  gt park <gate-id> -m "Deploy staged, awaiting approval"

  # Park on a GitHub Actions gate
  bd gate create --await gh:run:123456789
  gt park <gate-id> -m "Waiting for CI to complete"

Usage:
  gt park <gate-id> [flags]

Flags:
  -n, --dry-run          Show what would be done without executing
  -h, --help             help for park
  -m, --message string   Context notes for resumption

Display all ready work items across the town and all rigs.

Aggregates ready issues from:
- Town beads (hq-* items: convoys, cross-rig coordination)
- Each rig's beads (project-level issues, MRs)

Ready items have no blockers and can be worked immediately.
Results are sorted by priority (highest first) then by source.

Examples:
  gt ready              # Show all ready work
  gt ready --json       # Output as JSON
  gt ready --rig=gastown  # Show only one rig

Usage:
  gt ready [flags]

Flags:
  -h, --help         help for ready
      --json         Output as JSON
      --rig string   Filter to a specific rig

Release one or more in_progress issues back to open/pending status.

This is used to recover stuck steps when a worker dies mid-task.
The issue is moved to "open" status and the assignee is cleared,
allowing another worker to claim and complete it.

Examples:
  gt release gt-abc           # Release single issue
  gt release gt-abc gt-def    # Release multiple issues
  gt release gt-abc -r "worker died"  # Release with reason

This implements nondeterministic idempotence - work can be safely
retried by releasing and reclaiming stuck steps.

Usage:
  gt release <issue-id>... [flags]

Flags:
  -h, --help            help for release
  -r, --reason string   Reason for releasing (added as note)

Resume work that was parked on a gate, or check for handoff messages.

By default, this command checks for parked work (from 'gt park') and whether
its gate has cleared. If the gate is closed, it restores your work context.

With --handoff, it checks the inbox for handoff messages (messages with
"HANDOFF" in the subject) and displays them formatted for easy continuation.

The resume command:
  1. Checks for parked work state (default) or handoff messages (--handoff)
  2. For parked work: verifies gate has closed
  3. Restores the hook with your previous work
  4. Displays context notes to help you continue

Examples:
  gt resume              # Check for and resume parked work
  gt resume --status     # Just show parked work status without resuming
  gt resume --handoff    # Check inbox for handoff messages

Usage:
  gt resume [flags]

Flags:
      --handoff   Check for handoff messages instead of parked work
  -h, --help      help for resume
      --json      Output as JSON
      --status    Just show parked work status

Show issue details

Usage:
  bd show [id...] [flags]

Aliases:
  show, view

Flags:
      --as-of string   Show issue as it existed at a specific commit hash or branch (requires Dolt)
      --children       Show only the children of this issue
  -h, --help           help for show
      --refs           Show issues that reference this issue (reverse lookup)
      --short          Show compact one-line output per issue
      --thread         Show full conversation thread (for messages)

Global Flags:
      --actor string            Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
      --allow-stale             Allow operations on potentially stale data (skip staleness check)
      --db string               Database path (default: auto-discover .beads/*.db)
      --json                    Output in JSON format
      --lock-timeout duration   SQLite busy timeout (0 = fail immediately if locked) (default 30s)
      --no-auto-flush           Disable automatic JSONL sync after CRUD operations
      --no-auto-import          Disable automatic JSONL import when newer than DB
      --no-daemon               Force direct storage mode, bypass daemon if running
      --no-db                   Use no-db mode: load from JSONL, no SQLite
      --profile                 Generate CPU profile for performance analysis
  -q, --quiet                   Suppress non-essential output (errors only)
      --readonly                Read-only mode: block write operations (for worker sandboxes)
      --sandbox                 Sandbox mode: disables daemon and auto-sync
  -v, --verbose                 Enable verbose/debug output

Sling work onto an agent's hook and start working immediately.

This is THE command for assigning work in Gas Town. It handles:
  - Existing agents (mayor, crew, witness, refinery)
  - Auto-spawning polecats when target is a rig
  - Dispatching to dogs (Deacon's helper workers)
  - Formula instantiation and wisp creation
  - Auto-convoy creation for dashboard visibility

Auto-Convoy:
  When slinging a single issue (not a formula), sling automatically creates
  a convoy to track the work unless --no-convoy is specified. This ensures
  all work appears in 'gt convoy list', even "swarm of one" assignments.

  gt sling gt-abc gastown              # Creates "Work: <issue-title>" convoy
  gt sling gt-abc gastown --no-convoy  # Skip auto-convoy creation

Target Resolution:
  gt sling gt-abc                       # Self (current agent)
  gt sling gt-abc crew                  # Crew worker in current rig
  gt sling gp-abc greenplace               # Auto-spawn polecat in rig
  gt sling gt-abc greenplace/Toast         # Specific polecat
  gt sling gt-abc mayor                 # Mayor
  gt sling gt-abc deacon/dogs           # Auto-dispatch to idle dog
  gt sling gt-abc deacon/dogs/alpha     # Specific dog

Spawning Options (when target is a rig):
  gt sling gp-abc greenplace --create               # Create polecat if missing
  gt sling gp-abc greenplace --force                # Ignore unread mail
  gt sling gp-abc greenplace --account work         # Use specific Claude account

Natural Language Args:
  gt sling gt-abc --args "patch release"
  gt sling code-review --args "focus on security"

The --args string is stored in the bead and shown via gt prime. Since the
executor is an LLM, it interprets these instructions naturally.

Formula Slinging:
  gt sling mol-release mayor/           # Cook + wisp + attach + nudge
  gt sling towers-of-hanoi --var disks=3

Formula-on-Bead (--on flag):
  gt sling mol-review --on gt-abc       # Apply formula to existing work
  gt sling shiny --on gt-abc crew       # Apply formula, sling to crew

Compare:
  gt hook <bead>      # Just attach (no action)
  gt sling <bead>     # Attach + start now (keep context)
  gt handoff <bead>   # Attach + restart (fresh context)

The propulsion principle: if it's on your hook, YOU RUN IT.

Batch Slinging:
  gt sling gt-abc gt-def gt-ghi gastown   # Sling multiple beads to a rig

  When multiple beads are provided with a rig target, each bead gets its own
  polecat. This parallelizes work dispatch without running gt sling N times.

Usage:
  gt sling <bead-or-formula> [target] [flags]

Flags:
      --account string    Claude Code account handle to use
      --agent string      Override agent/runtime for this sling (e.g., claude, gemini, codex, or custom alias)
  -a, --args string       Natural language instructions for the executor (e.g., 'patch release')
      --create            Create polecat if it doesn't exist
  -n, --dry-run           Show what would be done
      --force             Force spawn even if polecat has unread mail
  -h, --help              help for sling
      --hook-raw-bead     Hook raw bead without default formula (expert mode)
  -m, --message string    Context message for the work
      --no-convoy         Skip auto-convoy creation for single-issue sling
      --on string         Apply formula to existing bead (implies wisp scaffolding)
  -s, --subject string    Context subject for the work
      --var stringArray   Formula variable (key=value), can be repeated

Manage synthesis steps for convoy formulas.

Synthesis is the final step in a convoy workflow that combines outputs
from all parallel legs into a unified deliverable.

Commands:
  start     Start synthesis for a convoy (checks all legs complete)
  status    Show synthesis readiness and leg outputs
  close     Close convoy after synthesis complete

Examples:
  gt synthesis status hq-cv-abc     # Check if ready for synthesis
  gt synthesis start hq-cv-abc      # Start synthesis step
  gt synthesis close hq-cv-abc      # Close convoy after synthesis

Usage:
  gt synthesis [flags]
  gt synthesis [command]

Aliases:
  synthesis, synth

Available Commands:
  close       Close convoy after synthesis
  start       Start synthesis for a convoy
  status      Show synthesis readiness

Flags:
  -h, --help   help for synthesis

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

Show recent activity in the workspace.

Without a subcommand, shows recent commits from agents.

Subcommands:
  commits    Recent git commits from agents
  beads      Recent beads (work items)
  hooks      Recent hook activity

Flags:
  --since    Show activity since this time (e.g., "1h", "24h", "7d")
  --limit    Maximum number of items to show (default: 20)
  --json     Output as JSON
  --all      Include all activity (not just agents)

Examples:
  gt trail                     # Recent commits (default)
  gt trail commits             # Same as above
  gt trail commits --since 1h  # Last hour
  gt trail beads               # Recent beads
  gt trail hooks               # Recent hook activity
  gt recent                    # Alias for gt trail
  gt recap --since 24h         # Activity from last 24 hours

Usage:
  gt trail [flags]
  gt trail [command]

Aliases:
  trail, recent, recap

Available Commands:
  beads       Show recent beads
  commits     Show recent commits from agents
  hooks       Show recent hook activity

Flags:
      --all            Include all activity (not just agents)
  -h, --help           help for trail
      --json           Output as JSON
      --limit int      Maximum number of items to show (default 20)
      --since string   Show activity since this time (e.g., 1h, 24h, 7d)

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

Remove work from an agent's hook (the inverse of sling/hook).

With no arguments, clears your own hook. With a bead ID, only unslings
if that specific bead is currently hooked. With a target, operates on
another agent's hook.

Examples:
  gt unsling                        # Clear my hook (whatever's there)
  gt unsling gt-abc                 # Only unsling if gt-abc is hooked
  gt unsling greenplace/joe            # Clear joe's hook
  gt unsling gt-abc greenplace/joe     # Unsling gt-abc from joe

The bead's status changes from 'hooked' back to 'open'.

Related commands:
  gt sling <bead>    # Hook + start (inverse of unsling)
  gt hook <bead>     # Hook without starting
  gt hook      # See what's on your hook

Usage:
  gt unsling [bead-id] [target] [flags]

Aliases:
  unsling, unhook

Flags:
  -n, --dry-run   Show what would be done
  -f, --force     Unsling even if work is incomplete
  -h, --help      help for unsling