gastown/docs/INSTALLING.md

Installing Gas Town

Complete setup guide for Gas Town multi-agent orchestrator.

Prerequisites

Required

Tool	Version	Check	Install
Go	1.24+	go version	See golang.org
Git	2.20+	git --version	See below
Beads	latest	bd version	go install github.com/steveyegge/beads/cmd/bd@latest

Optional (for Full Stack Mode)

Tool	Version	Check	Install
tmux	3.0+	tmux -V	See below
Claude Code	latest	claude --version	See claude.ai/claude-code

Installing Prerequisites

macOS

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Required
brew install go git

# Optional (for full stack mode)
brew install tmux

Linux (Debian/Ubuntu)

# Required
sudo apt update
sudo apt install -y git

# Install Go (apt version may be outdated, use official installer)
wget https://go.dev/dl/go1.24.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

# Optional (for full stack mode)
sudo apt install -y tmux

Linux (Fedora/RHEL)

# Required
sudo dnf install -y git golang

# Optional
sudo dnf install -y tmux

Verify Prerequisites

# Check all prerequisites
go version        # Should show go1.24 or higher
git --version     # Should show 2.20 or higher
tmux -V           # (Optional) Should show 3.0 or higher

Installing Gas Town

Step 1: Install the Binaries

# Install Gas Town CLI
go install github.com/steveyegge/gastown/cmd/gt@latest

# Install Beads (issue tracker)
go install github.com/steveyegge/beads/cmd/bd@latest

# Verify installation
gt version
bd version

If gt is not found, ensure $GOPATH/bin (usually ~/go/bin) is in your PATH:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="$PATH:$HOME/go/bin"

Step 2: Create Your Workspace

# Create a Gas Town workspace (HQ)
gt install ~/gt

# This creates:
#   ~/gt/
#   ├── CLAUDE.md          # Mayor role context
#   ├── mayor/             # Mayor config and state
#   ├── rigs/              # Project containers (initially empty)
#   └── .beads/            # Town-level issue tracking

Step 3: Add a Project (Rig)

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

# This clones the repo and sets up:
#   ~/gt/myproject/
#   ├── .beads/            # Project issue tracking
#   ├── mayor/rig/         # Mayor's clone (canonical)
#   ├── refinery/rig/      # Merge queue processor
#   ├── witness/           # Worker monitor
#   └── polecats/          # Worker clones (created on demand)

Step 4: Verify Installation

cd ~/gt
gt doctor              # Run health checks
gt status              # Show workspace status

Minimal Mode vs Full Stack Mode

Gas Town supports two operational modes:

Minimal Mode (No Daemon)

Run individual Claude Code instances manually. Gas Town only tracks state.

# Create and assign work
gt convoy create "Fix bugs" issue-123
gt sling issue-123 myproject

# Run Claude manually
cd ~/gt/myproject/polecats/<worker>
claude --resume

# Check progress
gt convoy list

When to use: Testing, simple workflows, or when you prefer manual control.

Full Stack Mode (With Daemon)

Agents run in tmux sessions. Daemon manages lifecycle automatically.

# Start the daemon
gt daemon start

# Create and assign work (workers spawn automatically)
gt convoy create "Feature X" issue-123 issue-456
gt sling issue-123 myproject
gt sling issue-456 myproject

# Monitor on dashboard
gt convoy list

# Attach to any agent session
gt mayor attach
gt witness attach myproject

When to use: Production workflows with multiple concurrent agents.

Choosing Roles

Gas Town is modular. Enable only what you need:

Configuration	Roles	Use Case
Polecats only	Workers	Manual spawning, no monitoring
+ Witness	+ Monitor	Automatic lifecycle, stuck detection
+ Refinery	+ Merge queue	PR review, code integration
+ Mayor	+ Coordinator	Cross-project coordination

Troubleshooting

gt: command not found

Your Go bin directory is not in PATH:

# Add to your shell config (~/.bashrc, ~/.zshrc)
export PATH="$PATH:$HOME/go/bin"
source ~/.bashrc  # or restart terminal

bd: command not found

Beads CLI not installed:

go install github.com/steveyegge/beads/cmd/bd@latest

gt doctor shows errors

Run with --fix to auto-repair common issues:

gt doctor --fix

For persistent issues, check specific errors:

gt doctor --verbose

Daemon not starting

Check if tmux is installed and working:

tmux -V                    # Should show version
tmux new-session -d -s test && tmux kill-session -t test  # Quick test

Git authentication issues

Ensure SSH keys or credentials are configured:

# Test SSH access
ssh -T git@github.com

# Or configure credential helper
git config --global credential.helper cache

Beads sync issues

If beads aren't syncing across clones:

cd ~/gt/myproject/mayor/rig
bd sync --status           # Check sync status
bd doctor                  # Run beads health check

Updating

To update Gas Town and Beads:

go install github.com/steveyegge/gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest
gt doctor --fix            # Fix any post-update issues

Uninstalling

# Remove binaries
rm $(which gt) $(which bd)

# Remove workspace (CAUTION: deletes all work)
rm -rf ~/gt

Next Steps

After installation:

1. Read the README - Core concepts and workflows
2. Try a simple workflow - gt convoy create "Test" test-issue
3. Explore docs - docs/reference.md for command reference
4. Run doctor regularly - gt doctor catches problems early