How to Set Up Gas Town Multi-Agent Workspace on macOS 2025

If you're juggling multiple AI coding agents—Claude Code, GitHub Copilot, and others—across different projects, you've likely hit a familiar wall: agents lose context when they restart, work state vanishes, and coordinating 5+ agents manually becomes chaotic. Gas Town solves this by providing a persistent workspace manager that keeps agent context alive through git-backed hooks and structured work tracking.

This guide walks you through installing and configuring Gas Town on macOS, setting up your first rig (project container), and spawning worker agents that maintain state across sessions.

Prerequisites

Before starting, ensure you have:

• macOS 12.0 or later (Intel or Apple Silicon)
• Git 2.28+ installed (verify with git --version)
• Node.js 18+ or Python 3.9+ (depending on your agent runtime)
• Claude Code or GitHub Copilot installed and authenticated
• A GitHub account with at least one repository (for rig setup)
• Homebrew installed (optional but recommended for dependency management)

Step 1: Install Gas Town Locally

Gas Town is distributed as a command-line tool. Install it via npm or clone from source:

Option A: Install via npm (Recommended)

npm install -g gastown

Verify installation:

gt --version
gt help

You should see version information and a list of available commands like rig, sling, convoy, and witness.

Option B: Install from Source

If you prefer bleeding-edge features or want to contribute:

git clone https://github.com/gastownhall/gastown.git
cd gastown
npm install
npm run build
npm link  # Makes 'gt' command globally available

Step 2: Initialize Your Town Workspace

Your "Town" is the root directory where Gas Town manages all projects and agents. By default, this lives at ~/gt/, but you can customize it.

gt init ~/gt
cd ~/gt

This creates the following structure:

~/gt/
├── .gastown/
│   ├── config.toml        # Global configuration
│   ├── agents.toml        # Agent definitions
│   └── mayor.state        # Mayor coordinator state
├── rigs/                  # Project containers
└── .git/                  # Version control for workspace state

Step 3: Configure Your Mayor (Primary AI Coordinator)

The Mayor is your main Claude Code instance that coordinates all other agents. Configure it in ~/.gastown/config.toml:

[mayor]
name = "The Mayor"
model = "claude-3-5-sonnet"  # or claude-3-opus for heavier tasks
api_key = "${ANTHROPIC_API_KEY}"  # Uses env var
max_retries = 3
thinking_budget = 8000

[workspace]
town_path = "~/gt"
max_concurrent_rigs = 5
max_agents_per_rig = 10

[persistence]
backend = "git"  # git-backed hooks for state persistence
sync_interval = 300  # Sync every 5 minutes

Export your Anthropic API key:

export ANTHROPIC_API_KEY="sk-ant-..."

Step 4: Create Your First Rig (Project Container)

A "rig" wraps a git repository and manages its agents. Create one for an existing project:

gt rig create my-project \
  --repo https://github.com/yourusername/my-project.git \
  --branch main \
  --max-agents 5

Gas Town clones the repo and sets up:

~/gt/rigs/my-project/
├── .git/                      # Cloned repository
├── .crew/                      # Your personal workspace
├── .hooks/                     # Persistent agent storage
├── .polecats/                  # Worker agent definitions
└── rig.toml                    # Rig-specific config

Verify the rig:

gt rig list

Step 5: Define and Spawn Worker Agents (Polecats)

Polecats are ephemeral worker agents with persistent identity. Define them in ~/gt/rigs/my-project/rig.toml:

[[polecats]]
name = "backend-agent"
model = "claude-3-5-sonnet"
role = "API and database development"
scope = "backend/"

[[polecats]]
name = "frontend-agent"
model = "claude-3-5-sonnet"
role = "React component development"
scope = "src/components/"

[[polecats]]
name = "test-agent"
model = "claude-3-opus"  # More powerful for reasoning
role = "Test suite and quality assurance"
scope = "tests/"

Spawn agents for a task:

gt convoy create "Add user authentication"
gt sling backend-agent,test-agent --convoy "Add user authentication"

The Mayor coordinates these agents, they execute in parallel, and all work persists in .hooks/ (git worktrees) even if sessions crash.

Step 6: Monitor Agent Health with Witness

Gas Town includes three-tier monitoring: Witness (per-rig), Deacon (global supervisor), and Dogs (infrastructure workers).

Start Witness for your rig:

gt witness start my-project

This monitors polecats, detects stuck agents, and triggers recovery. Watch the patrol cycles:

gt witness status my-project

Output shows:

Rig: my-project
Deacon Status: running (cycle 42)
Active Polecats: 3/5
  backend-agent: healthy (session 87m)
  frontend-agent: healthy (session 45m)
  test-agent: idle (last activity 3m ago)
Incidents: 1 recovered (timeout at 10:35 AM)

Step 7: Track Work with Beads (Issues)

Beads are git-backed work items with IDs like gt-abc12 or hq-x7k2m. Create and assign work:

gt bead create "Implement OAuth2 flow" \
  --rig my-project \
  --scope backend/ \
  --priority high

Assign to an agent:

gt sling backend-agent --bead gt-abc12

List all work:

gt beads list

Troubleshooting Common Setup Issues

"git worktree" errors

If you see worktree creation failures, ensure your local git has no uncommitted changes:

cd ~/gt/rigs/my-project && git status
git add . && git commit -m "Initial setup"

API key not found

Verify your Anthropic API key is exported:

echo $ANTHROPIC_API_KEY

If blank, add to ~/.zshrc or ~/.bash_profile:

export ANTHROPIC_API_KEY="sk-ant-..."
source ~/.zshrc

Witness crashes on startup

Check that the deacon background service is running:

gt deacon start
gt deacon status

Next Steps

Now that Gas Town is set up:

1. Define Molecules (workflow templates) in TOML for complex multi-step tasks
2. Scale to 10+ agents across multiple rigs using the Mayor's full orchestration capabilities
3. Enable mountain-mode convoys for autonomous stall detection on long-running tasks
4. Integrate GitHub Actions to trigger agent work from CI/CD pipelines

Gas Town persists everything in git, so your multi-agent workflows survive crashes, restarts, and context windows—solving the coordination chaos that traditional agent setups create.