Contributing to Gastown: Multi-Agent Orchestration for Claude Code

Gastown is a multi-agent orchestration layer for Claude Code. It manages multiple agents working in parallel, coordinates shared resources, and tracks work state in git-backed storage. Over two weeks of heavy usage, I contributed 5 merged PRs and have 8 open PRs addressing daemon behavior, installation flow, and configuration flexibility.

Architecture Overview

Concept	Description
Mayor	Primary AI coordinator with full workspace context
Rigs	Projects linked to git repositories
Crew	Personal workspace within a rig—can be specialized per role
Polecats	Ephemeral worker agents that spawn, execute, and terminate
Convoys	Work tracking units bundling beads for agent assignment
Beads	Git-backed issue tracking storing work state as structured data

1
2
3
gt install ~/gt --git
gt rig add myproject https://github.com/you/repo.git
gt mayor attach

Merged Contributions

PR	Type	Description
#457	fix	Prevent `gt down --all` from respawning background daemon
#465	fix	Add `--allow-stale` fallback for `--no-daemon` reads
#769	feat	Add initial prompt for deacon/witness autonomous patrol startup
#790	fix	Fresh installation improvements (14 commits)
#840	fix	Respect `GT_TOWN_ROOT` in quick-add command

Daemon Resilience (#457, #465)

Two issues with daemon operations: gt down --all would inadvertently respawn the daemon it just killed, and --no-daemon reads failed on stale state files. Fixes ensure shutdown actually stops everything and reads degrade gracefully without a running daemon.

Autonomous Patrol (#769)

Deacon and witness agents sat idle after startup—tmux session running, Claude active, but no work happening. The daemon heartbeat saw them as “running” but they weren’t patrolling. Fix passes an initial prompt triggering immediate patrol:

"I am Deacon. Start patrol: check gt hook, if empty create mol-deacon-patrol wisp and execute it."

Fresh Installation (#790)

Largest contribution: 14 commits addressing initialization failures on clean machines. Gastown assumed directories and config files existed. Fixes include:

Create missing directories with proper permissions
Generate sensible config defaults
Improve error messages for missing prerequisites
Add pre-operation validation

Environment Variable Handling (#840)

quick-add ignored GT_TOWN_ROOT, failing for non-default town locations. Fix checks the environment variable before falling back to defaults.

Open Contributions

PR	Category	Description
#770	protocol	PING/PONG protocol with backoff for agent health monitoring
#751	process	Detect and kill stray Claude processes on shutdown
#750	layout	Detect actual rig layout instead of hardcoding paths
#711	config	Per-rig refinery disable flag
#709	config	Role context overrides via settings config
#706	process	Fix daemon kill ordering to prevent respawn during `gt down`
#628	daemon	Prevent daemon autostart during cost queries
#620	config	Branch protection with per-rig overrides

Custom Branch Workflow

Running a fork with a custom branch that bundles all open PRs. This enables using improvements before upstream merge—PING/PONG protocol, refinery flags, config overrides, and process cleanup working together.

1
2
3
git remote add upstream https://github.com/steveyegge/gastown.git
git checkout custom
go build -o gt ./cmd/gt && mv gt ~/go/bin/

Rebase when upstream merges PRs to drop those commits. Extra maintenance, but necessary when using the tool heavily and needing fixes faster than the merge cycle.

Multi-Agent Patterns

Task decomposition: Structure work into focused beads. Polecats are generic workers; specialization comes from how work items are defined.

Parallel execution: Sling independent beads to multiple polecats. Define work units and dependencies via convoys; Gastown handles coordination.

Review workflows: Route one polecat’s output to another via mailboxes for feedback loops.

Installation

1
2
3
4
5
6
7
8
# Pick one
brew install gastown
npm install -g @gastown/gt
go install github.com/steveyegge/gastown/cmd/gt@latest

# Initialize
gt install ~/gt --git
gt mayor attach

Documentation available in the GitHub repository README.