From 3672e659d57f50f2052cb2382ff79932a060dbc0 Mon Sep 17 00:00:00 2001 From: rictus Date: Thu, 1 Jan 2026 11:24:52 -0800 Subject: [PATCH] docs: Add comprehensive INSTALLING.md guide (gt-t5ga3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full setup guide covering: - Prerequisites for macOS and Linux - Step-by-step installation - Minimal vs Full Stack mode setup - Verification with gt doctor - Troubleshooting common issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/INSTALLING.md | 282 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 docs/INSTALLING.md diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md new file mode 100644 index 00000000..180c8b7e --- /dev/null +++ b/docs/INSTALLING.md @@ -0,0 +1,282 @@ +# 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](https://go.dev/doc/install) | +| **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](https://claude.ai/claude-code) | + +## Installing Prerequisites + +### macOS + +```bash +# 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) + +```bash +# 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) + +```bash +# Required +sudo dnf install -y git golang + +# Optional +sudo dnf install -y tmux +``` + +### Verify Prerequisites + +```bash +# 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 + +```bash +# 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: + +```bash +# Add to ~/.bashrc, ~/.zshrc, or equivalent +export PATH="$PATH:$HOME/go/bin" +``` + +### Step 2: Create Your Workspace + +```bash +# 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) + +```bash +# Add your first project +gt rig add myproject --remote=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 + +```bash +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. + +```bash +# Create and assign work +gt convoy create "Fix bugs" issue-123 +gt sling issue-123 myproject + +# Run Claude manually +cd ~/gt/myproject/polecats/ +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. + +```bash +# 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: + +```bash +# 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: + +```bash +go install github.com/steveyegge/beads/cmd/bd@latest +``` + +### `gt doctor` shows errors + +Run with `--fix` to auto-repair common issues: + +```bash +gt doctor --fix +``` + +For persistent issues, check specific errors: + +```bash +gt doctor --verbose +``` + +### Daemon not starting + +Check if tmux is installed and working: + +```bash +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: + +```bash +# 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: + +```bash +cd ~/gt/myproject/mayor/rig +bd sync --status # Check sync status +bd doctor # Run beads health check +``` + +## Updating + +To update Gas Town and Beads: + +```bash +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 + +```bash +# 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