How to Sling Work to an Agent Using the `gt sling` Command

The gt sling command assigns a bead (issue or formula) to an agent such as a polecat, crew member, or dog, validates the caller's role against restrictions, resolves the target into a concrete hook, and initiates execution immediately in a tmux session.

The gt sling command serves as the primary dispatch mechanism in the gastownhall/gastown repository for moving work onto execution agents. It handles the complete lifecycle from CLI invocation through resource provisioning to active session management, ensuring that beads reach their assigned targets without manual intervention.

Understanding the gt sling Workflow

The command implementation in internal/cmd/sling.go drives a multi-stage workflow that bridges the CLI and the agent execution environment.

Role Validation and Security Constraints

Before any dispatch occurs, the command validates the caller's identity. Polecats are explicitly prohibited from slinging work—a restriction enforced at the start of the command flow (see the role check in internal/cmd/sling.go lines 15-27). This security boundary ensures that only mayors (human operators) and authorized roles can trigger agent assignments.

Target Resolution and Hook Attachment

The second positional argument undergoes expansion into a concrete hook target. This argument may specify:

• A rig name (e.g., gastown)
• A specific polecat identifier
• A crew member (e.g., mel)
• A dog (dedicated resource)

The system expands these shortcuts into canonical hook paths such as gastown/crew/mel (lines 53-61 of internal/cmd/sling.go). Once resolved, the bead attaches to the target agent and prepares the workspace.

Automatic Resource Provisioning

When the target is a rig without an existing polecat, gt sling can provision the necessary infrastructure automatically. The --create flag triggers polecat spawning if none exists, while --force respawns a polecat even if it has unread mail (lines 51-54). For single-bead dispatches, the command generates a convoy automatically unless you supply the --no-convoy flag (lines 39-42), ensuring visibility in the dashboard UI.

Command Syntax and Flag Reference

The command supports several flags defined in internal/cmd/sling.go lines 30-68 that control dispatch behavior:

• --create – Spawns a new polecat on the target rig if none exists
• --force – Forces polecat recreation even when unread mail is present
• --no-convoy – Suppresses automatic convoy creation for ad-hoc scripts
• --merge – Specifies merge strategy (e.g., --merge=direct) for the auto-convoy
• --crew – Targets a specific crew member within the rig
• --on – Runs a formula on an existing bead (formula-on-bead mode)
• --args – Passes natural-language instructions to the LLM executor
• --subject – Sets the subject line for the dispatched work

Practical Examples for Dispatching Work

Replace gt with your CLI entry point and adjust identifiers as needed for your environment.

Basic issue dispatch that creates a polecat and convoy automatically:

gt sling gt-abc123 gastown

Dispatch a formula to a specific crew member:

gt sling mol-review --crew mel gastown

Spawn a new polecat on an empty rig before execution:

gt sling gt-xyz456 greenplace --create

Force-spawn a polecat even when unread mail exists (use cautiously):

gt sling gt-xyz456 greenplace --force

Run a formula against an existing bead:

gt sling mol-release --on gt-abc123 gastown

Dispatch with natural-language instructions:

gt sling gt-abc123 gastown --args "patch the release notes" --subject "Release Update"

Skip convoy creation for headless automation:

gt sling gt-abc123 gastown --no-convoy

Specify merge strategy for the auto-generated convoy:

gt sling gt-abc123 gastown --merge=direct

Telemetry and Observability

All sling operations are instrumented for monitoring. The command calls RecordSling to emit metrics such as gastown.sling.dispatches.total, enabling observability dashboards to track total sling attempts and failure rates (see internal/telemetry/recorder.go). This telemetry integrates with the broader Gas Town monitoring stack to provide real-time visibility into work distribution patterns.

Web Dashboard Integration

The web interface registers sling as a Work command type that requires explicit confirmation before execution. According to internal/web/commands.go lines 87-90, this classification ensures that only vetted, high-privilege operations are exposed through the UI, adding a layer of safety for browser-based interactions.

Summary

• gt sling is the central dispatch command for assigning beads to agents (polecats, crew, or dogs) in gastownhall/gastown
• Role validation blocks polecats from slinging, restricting the operation to authorized roles
• Target resolution expands shorthand rig or crew names into canonical hook paths like gastown/crew/mel
• Automatic provisioning creates polecats (--create, --force) and convoys (unless --no-convoy) as needed
• Telemetry via RecordSling tracks all dispatch attempts for operational monitoring
• Web security requires confirmation for sling operations in the dashboard UI per internal/web/commands.go

Frequently Asked Questions

What is a bead in the context of gt sling?

A bead represents a unit of work, which may be either an issue (e.g., gt-abc123) or a formula (e.g., mol-review). The bead encapsulates the task context, instructions, and metadata required for the agent to execute the work.

Why are polecats prohibited from using the sling command?

The role check at lines 15-27 of internal/cmd/sling.go explicitly prevents polecats from slinging work to prevent recursive dispatch loops and privilege escalation. This restriction ensures that only human operators (mayors) or other authorized roles can trigger agent assignments.

What is the difference between the --create and --force flags?

The --create flag spawns a new polecat only if one does not already exist on the target rig. The --force flag destroys and recreates a polecat even if it has unread mail or active state, which is useful for recovering from corrupted environments but risks losing unsaved work.

How does automatic convoy creation work?

By default, gt sling generates a convoy for single-bead dispatches (lines 39-42 of internal/cmd/sling.go), which groups the work visually in the dashboard UI. You can suppress this behavior with --no-convoy when running ad-hoc scripts that do not require dashboard visibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}