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

> Learn how to sling work to an agent with the gastownhall/gastown gt sling command. Assign issues, validate roles, and initiate execution instantly.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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:

```bash
gt sling gt-abc123 gastown

```

Dispatch a formula to a specific crew member:

```bash
gt sling mol-review --crew mel gastown

```

Spawn a new polecat on an empty rig before execution:

```bash
gt sling gt-xyz456 greenplace --create

```

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

```bash
gt sling gt-xyz456 greenplace --force

```

Run a formula against an existing bead:

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

```

Dispatch with natural-language instructions:

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

```

Skip convoy creation for headless automation:

```bash
gt sling gt-abc123 gastown --no-convoy

```

Specify merge strategy for the auto-generated convoy:

```bash
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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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.