Finding, creating, claiming, and closing work items (beads)
API server and web dashboard — config, start, monitor
Managing agents — list, peek, nudge, suspend, drain
City lifecycle — status, start, stop, init
Sending and reading messages between agents
Managing rigs — add, list, status, suspend, resume
| name | gc-dispatch |
| description | Routing work to agents with gc sling and formulas |
gc sling routes work to session configs. Multi-session configs are valid
targets — sling to the config and any eligible session can claim the work.
You do NOT need to find or create an individual session first.
gc sling <bead-id> # Auto-target via rig's default_sling_target
gc sling <session-config> <bead-id> # Route to a specific session config
gc sling <session-config> -f <formula> # Instantiate formula, route wisp root
gc sling <session-config> <bead-id> --on <formula> # Attach wisp to existing bead
The <session-config> is a qualified config name from gc session list:
mayor, hello-world/refineryhello-world/polecat — routes to the config's shared work queue1-arg shorthand: When target is omitted, sling derives it from the
bead's rig prefix. The rig's default_sling_target in city.toml determines
where work goes. Example: bead hw-42 → rig hello-world → target
hello-world/polecat.
Rig-scoped beads: gc sling automatically resolves the rig directory
for rig-scoped bead IDs (e.g. hw-abc) and runs bd update from there,
so the rig's .beads database is found without manual intervention.
Beads must be in the agent's rig database. Sling operates on the
target agent's rig database — formula cooking, labeling, and convoy
creation all happen there. Create beads with --rig so they land in
the right database:
bd create "fix the bug" --rig frontend # Creates fe-xxx in frontend's db
gc sling frontend/polecat fe-xxx # Works — bead is in the right db
If the bead is in the wrong database (e.g. gc-xxx in HQ but targeting
a frontend agent), sling's cross-rig guard will block the route.
gc sling <session-config> <bead-id> # Route a bead to a session config
gc sling <bead-id> # Use rig's default_sling_target
The agent receives the bead on its hook and runs it per GUPP.
gc sling <agent> -f <formula> # Run a formula, creating a molecule
Creates a molecule from the formula and hooks the root bead to the agent.
gc sling <agent> <bead-id> --on <formula> # Attach formula wisp to bead
Creates a molecule wisp on the bead and routes to the agent.
gc formula list # List available formulas
gc formula show <name> # Show formula definition
mol-do-work — Simple work lifecycle. Agent reads the bead, implements the solution in the current working directory, and closes the bead. No git branching, no worktree isolation, no refinery handoff. Good for demos and simple single-agent workflows.
gc sling <agent> <bead-id> --on mol-do-work
mol-polecat-commit — Direct-commit variant. Creates a worktree but commits directly to base_branch with no feature branch or refinery step. Includes preflight tests, implementation, and self-review quality gates. For small installations where merge review is unnecessary.
gc sling <agent> <bead-id> --on mol-polecat-commit
mol-polecat-base — Shared base for polecat work formulas. Defines the common steps (load context, preflight, implement, self-review) that variant formulas extend. Not typically used directly — use a variant like mol-polecat-commit or mol-polecat-work instead.
These require the gastown pack. They extend the built-in
mol-polecat-base.
mol-polecat-work — Feature-branch variant. Creates a worktree and
feature branch, implements, then pushes and reassigns to the refinery
for merge review. Production default for multi-agent setups. The polecat's
base_branch comes from metadata.target on the work bead if present,
otherwise from a parent convoy with metadata.target, otherwise from
the rig repo's default branch.
gc sling <agent> <bead-id> --on mol-polecat-work
mol-idea-to-plan — Planning workflow for a coordinator session. Turns a
rough idea into a PRD, reviewed design doc, and beads DAG using Gas City's
existing primitives: repo-local artifact files, review task beads, gc sling,
and mail. Best run from a crew worker in the target rig.
gc sling <coordinator-agent> -f mol-idea-to-plan --var problem="..." --var review_target=<rig>/polecat
mol-review-leg — Helper formula used by mol-idea-to-plan review tasks.
Persists the full report to bead notes, mails the coordinator, closes the bead,
and drains the session. Usually not slung by hand.
Patrol formulas are auto-poured by agent startup prompts — you typically don't sling these manually:
gc convoy create <name> <bead-ids...> # Group beads into a convoy
gc convoy create <name> --owned --target integration/<slug> # Long-lived initiative convoy
gc convoy target <id> <branch> # Set/update convoy target branch
gc convoy list # List active convoys
gc convoy status <id> # Show convoy progress + metadata
gc convoy add <id> <bead-ids...> # Add beads to convoy
gc convoy close <id> # Close convoy
gc convoy check <id> # Check if all beads done
gc convoy stranded # Find convoys with no progress
gc convoy autoclose # Close convoys where all beads done
Migration note:
gc convoy target, gc sling <convoy>, or the Gastown refinery convoy flow.gc order list # List order rules
gc order show <name> # Show order definition
gc order run <name> # Manually trigger an order
gc order check <name> # Check if trigger conditions are met
gc order history <name> # Show order run history