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