Work Management Commands
This page documents the Work Management commands for the gt CLI.
gt bead
Bead management utilities
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.gt cat
Display bead content
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 JSONgt close
Close one or more beads
Close one or more issues.
If no issue ID is provided, closes the last touched issue (from most recentcreate, 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 outputgt commit
Git commit with automatic agent identity
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 variables2. Converts it to a git-friendly name and email3. 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: [email protected]
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]gt convoy
Track batches of work across rigs
Manage convoys - the primary unit for tracking batched work.
A convoy is a persistent tracking unit that monitors related issues acrossrigs. When you kick off work (even a single issue), a convoy tracks it soyou 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.gt done
Signal work ready for merge queue
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 queue2. Auto-detects issue ID from branch name3. Notifies the Witness with the exit outcome4. 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")gt formula
Manage workflow formulas
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.gt gate
Gate coordination commands
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.gt handoff
Hand off to a fresh session, work continues from hook
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 contextfor 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)gt hook
Show or attach work on your hook
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 sessionrestarts, context compaction, and handoffs. When you restart (via gt handoff),your SessionStart hook finds the attached work and you continue from whereyou 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.gt mol
Agent molecule workflow commands
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.gt mq
Merge queue operations
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.gt orphans
Find lost polecat work
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.gt park
Park work on a gate for async resumption
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 checkfor 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 resumptiongt ready
Show work ready across town
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 riggt release
Release stuck in_progress issues back to pending
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 safelyretried 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)gt resume
Resume from parked work or check for handoff messages
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 whetherits 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 statusgt show
Show details of a bead
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 outputgt sling
Assign work to an agent (THE unified work dispatch command)
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 theexecutor 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 repeatedgt synthesis
Manage convoy synthesis steps
Manage synthesis steps for convoy formulas.
Synthesis is the final step in a convoy workflow that combines outputsfrom 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.gt trail
Show recent agent activity
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.gt unsling
Remove work from an agent’s hook
Remove work from an agent's hook (the inverse of sling/hook).
With no arguments, clears your own hook. With a bead ID, only unslingsif that specific bead is currently hooked. With a target, operates onanother 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