cursor-gastown

Cursor Gas Town

Multi-agent orchestration for Cursor CLI with persistent work tracking.

This is a fork of Gas Town, originally built for Claude Code. This repo converts it to work with Cursor CLI.

Overview

Cursor Gas Town coordinates multiple Cursor agents working on different tasks. Work state persists in git-backed hooks, enabling reliable multi-agent workflows that survive crashes and restarts.

Core Concepts

• Mayor - Your primary AI coordinator. Start here.
• Town - Workspace directory (e.g., ~/gt/)
• Rigs - Project containers wrapping git repositories
• Crew - Your personal workspace within a rig
• Polecats - Ephemeral worker agents
• Hooks - Git worktree-based persistent storage
• Convoys - Work tracking units bundling multiple tasks
• Beads - Git-backed issue tracking system
• Formulas - Reusable workflow templates (design → implement → test → submit)

Installation

Prerequisites

• Go 1.23+
• Git 2.25+ (for worktree support)
• beads (bd) 0.47.0+
• tmux 3.0+ (recommended)
• Cursor CLI

Setup

# Install Gas Town and Beads
go install github.com/cursorworkshop/cursor-gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest
export PATH="$PATH:$HOME/go/bin"

# Create workspace
gt install ~/gt --git
cd ~/gt

# Add a project
gt rig add myproject https://github.com/you/repo.git

# Create crew workspace
gt crew add yourname --rig myproject

# Verify setup
gt doctor

End-to-End Workflow: From Plan to Done

This is the core workflow. You have work to do—here's how Gas Town handles it.

Step 1: Define Your Work as Beads

A bead is a trackable unit of work (like a GitHub issue, but git-backed).

# Navigate to your rig
cd ~/gt/myproject

# Create beads for your tasks
bd create "Add user authentication"           # Creates gt-abc
bd create "Fix login page styling"            # Creates gt-def
bd create "Write integration tests"           # Creates gt-ghi

# See your beads
bd list

From a plan file? If you have a plan.md with tasks, create a bead for each:

# For each task in your plan:
bd create "Task 1 from plan"
bd create "Task 2 from plan"
# etc.

Step 2: Group Work into a Convoy

A convoy tracks related work and notifies you when it's done.

# Create a convoy tracking your beads
gt convoy create "Auth Feature" gt-abc gt-def gt-ghi --notify

# Output: Created convoy hq-cv-xyz tracking 3 issues

Step 3: Assign Work to Agents

Use gt sling to assign beads to agents. This is the command for dispatching work.

# Assign to a rig (auto-spawns a polecat worker)
gt sling gt-abc myproject

# Assign multiple beads (each gets its own worker)
gt sling gt-abc gt-def gt-ghi myproject

# Assign to a specific worker
gt sling gt-abc myproject/polecats/Toast

Step 4: Monitor Progress

# See all active convoys
gt convoy list

# Check convoy status
gt convoy status hq-cv-xyz

# See active agents
gt agents

# Attach to Mayor for coordination
gt mayor attach

Step 5: Work Completes Automatically

When agents finish:

1. Bead status changes to closed
2. Convoy auto-closes when all tracked beads complete
3. You get notified (if --notify was set)

# See completed convoys
gt convoy list --all

Alternative: Using Formulas (Structured Workflows)

Instead of raw beads, use formulas for multi-step workflows with dependencies.

# List available formulas
bd formula list

# Use the "shiny" formula (design → implement → review → test → submit)
gt sling shiny --var feature="User authentication" myproject

# The formula creates beads with proper dependencies
# Each step waits for its prerequisites

Built-in formulas:

• shiny - Full feature workflow (design, implement, review, test, submit)
• code-review - Review existing code
• security-audit - Security-focused review
• design - Design-only phase

Quick Reference

Key Commands

Workspace Setup

gt install <path>              # Initialize workspace
gt rig add <name> <repo>       # Add project
gt rig list                    # List projects
gt crew add <name> --rig <rig> # Create crew workspace
gt doctor                      # Health check

Work Management (Beads)

bd create "Task title"         # Create a bead (task)
bd list                        # List all beads
bd show <bead-id>              # Show bead details
bd close <bead-id>             # Mark complete

Work Assignment

gt sling <bead> <rig>          # Assign work (spawns worker)
gt sling <bead> <rig>/<worker> # Assign to specific worker
gt sling <formula> <rig>       # Run formula workflow

Tracking & Monitoring

gt convoy create <name> [beads...]  # Group beads for tracking
gt convoy list                      # See active convoys
gt convoy status <id>               # Convoy details
gt agents                           # List active agents

Agents

gt mayor attach                # Start Mayor (coordinator)
gt prime                       # Alternative to mayor attach
gt witness attach <rig>        # Attach to rig monitor

Formulas

bd formula list                # List available formulas
gt sling <formula> --var key=val <rig>  # Run formula with variables

Dashboard

gt dashboard --port 8080
open http://localhost:8080

Shell Completions

# Bash
gt completion bash > /etc/bash_completion.d/gt

# Zsh
gt completion zsh > "${fpath[1]}/_gt"

# Fish
gt completion fish > ~/.config/fish/completions/gt.fish

Troubleshooting

Agents lose connection

gt hooks list
gt hooks repair

Convoy stuck

gt convoy refresh <convoy-id>

Mayor not responding

gt mayor detach
gt mayor attach

General issues

gt doctor --fix    # Auto-repair common problems
gt doctor --verbose  # Detailed diagnostics

Learn More

• Understanding Gas Town - Architecture deep dive
• Installation Guide - Detailed setup instructions
• Reference - Full command reference

Origins

Gas Town was created by Steve Yegge for orchestrating Claude Code agents. This fork adapts it for Cursor CLI, maintaining the same architecture while targeting the Cursor ecosystem.

License

MIT