Gastown: Multi-Agent Orchestration for Claude Code

Overview
System Information
Installation
- From Source (FreeBSD)
- Using Makefile Targets
Shell Completion
- Bash
- Zsh
- Fish
Initial Setup
Key Concepts
- The Mayor
- Convoys
- Agents
MEOW Workflow
Commands Reference
Dashboard
Integration with Beads
Version History
Relation to Q1 2026 Research
References

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+

System Information

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

Installation

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

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

Shell Completion

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

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

Fish

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

Initial Setup

# Initialize workspace
gt install ~/gt --git

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

Key Concepts

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

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

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

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

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

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

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

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

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).