wal.sh
home > research > gastown · Jan 06, 2026

Gastown: Multi-Agent Orchestration for Claude Code

gastownclaude codemulti-agentworkspace managercontext persistencegit hookorchestration

Gastown: Multi-Agent Orchestration for Claude Code

Table of Contents

1. Overview

Gastown (gt) is a workspace manager for coordinating multiple Claude Code agents. It solves context loss when agents restart by persisting work state in git-backed hooks.

Property Value
Repository steveyegge/gastown
Installed v0.2.1-68-g7edd750
Binary ~/bin/gt
Stars 2.3k
Requirements Go 1.23+, Git 2.25+, tmux 3.0+

2. System Information

FreeBSD nexus 14.3-RELEASE FreeBSD 14.3-RELEASE releng/14.3-n271432-8c9ce319fef7 GENERIC amd64
Shell: /usr/local/bin/bash

3. Installation

3.1. From Source (FreeBSD)

# Install Go if needed
pkg install go

# Clone with ghq (recommended)
ghq get steveyegge/gastown

# Or clone directly
git clone https://github.com/steveyegge/gastown.git

# Build and install to ~/bin/
cd $(ghq root)/github.com/steveyegge/gastown
gmake install

# Verify
which gt        # ~/bin/gt
gt --version    # v0.2.1-68-g7edd750

3.2. Using Makefile Targets

gmake build     # Build only (creates ./gt)
gmake install   # Build and copy to ~/bin/gt
gmake test      # Run tests
gmake clean     # Remove binary

4. Shell Completion

4.1. Bash

# User-local (recommended)
mkdir -p ~/.local/share/bash-completion/completions
gt completion bash > ~/.local/share/bash-completion/completions/gt

# Or system-wide (requires root)
gt completion bash | sudo tee /usr/local/etc/bash_completion.d/gt

# Add to ~/.bashrc if not auto-loaded
source ~/.local/share/bash-completion/completions/gt

4.2. Zsh

# Generate completion
gt completion zsh > "${fpath[1]}/_gt"

# Or to custom location
gt completion zsh > ~/.zsh/completions/_gt

# Ensure in fpath (add to ~/.zshrc)
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

4.3. Fish

# Generate completion
gt completion fish > ~/.config/fish/completions/gt.fish

5. Initial Setup

# Initialize workspace
gt install ~/gt --git

# This creates:
# ~/gt/
# ├── .git/
# ├── .beads/          # Issue tracking
# ├── agents/          # Agent workspaces
# └── convoys/         # Work bundles

6. Key Concepts

6.1. The Mayor

The Mayor is an AI coordinator that manages agents: 

# Attach to Mayor (primary interface)
gt mayor attach

# The Mayor can:
# - Analyze requirements and create convoys
# - Spawn and manage worker agents
# - Track progress and summarize results

6.2. Convoys

Convoys bundle related issues/tasks for coordinated work: 

# Create a convoy
gt convoy create "Implement authentication" --issues=auth-1,auth-2,auth-3

# Check convoy status
gt convoy status

# List all convoys
gt convoy list

6.3. Agents

Worker agents execute tasks within convoys: 

# List active agents
gt agents

# Spawn a new agent
gt spawn --convoy=auth

# Sling an issue to an agent
gt sling auth-1 --agent=worker-1

7. MEOW Workflow

The recommended workflow (Mayor-Executed Orchestrated Work): 

1. Tell the Mayor what to build
   └─▶ gt mayor attach
       "I need a REST API with auth"

2. Mayor analyzes and creates convoy
   └─▶ Breaks down into issues
       Creates convoy with dependencies

3. Issues distributed to spawned agents
   └─▶ Worker agents claim and execute

4. Progress tracked via convoy status
   └─▶ gt convoy status

5. Results summarized by Mayor
   └─▶ Code merged, documentation updated

8. Commands Reference

Command Description
gt install <dir> Initialize workspace
gt mayor attach Start Mayor coordinator
gt convoy create Bundle issues into convoy
gt convoy status Check convoy progress
gt agents List active agents
gt spawn Create new worker agent
gt sling <issue> Assign issue to agent
gt dashboard Open web dashboard
gt completion <shell> Generate shell completion

9. Dashboard

Web-based monitoring for real-time visibility: 

# Start dashboard
gt dashboard

# Opens http://localhost:8080 with:
# - Agent status (active/idle/stopped)
# - Convoy progress bars
# - Issue assignment matrix
# - Token usage metrics

10. Integration with Beads

Gastown uses Beads (bd) for issue tracking: 

# Issues flow: beads → convoy → agent
bd create --title="Add login endpoint" --type=task
gt convoy add <issue-id>
gt sling <issue-id> --agent=worker-1

11. Version History

Version Date Highlights
v0.2.1 2026-01-05 Bug fixes, stability
v0.2.0 2026-01-04 Convoy Dashboard, Two-Level Beads, Multi-Agent
v0.1.1 2026-01-02 Initial release

12. Relation to Q1 2026 Research

Gastown complements our Q1 2026 Agentic Systems Research:

Our Component Gastown Equivalent
Issue tracker (beads) Built-in beads integration
Queue adapter Convoy system
Agent handoff Sling command
Token economics Usage metrics in dashboard

Gastown provides a production-ready orchestration layer while our research focuses on the underlying infrastructure (queues, recovery, formal specs).

13. References