docs: Add comprehensive INSTALLING.md guide (gt-t5ga3)
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 <noreply@anthropic.com>
This commit is contained in:
rictus
282
docs/INSTALLING.md
Normal file
282
docs/INSTALLING.md
Normal file
@@ -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/<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.
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user