Grinding with Beads and Gas Town: Multi-Agent AI Coding at Scale

grinding-with-beads-and-gastown.md

Grinding with Beads and Gas Town: Multi-Agent AI Coding at Scale

A practical guide to orchestrating AI coding agents for real projects

Introduction

If you've been following the evolution of AI-assisted coding, you know that 2025 was the year that coding agents became genuinely useful. But managing multiple agents working on a real codebase? That's where things get interesting—and chaotic.

Enter Beads and Gas Town, Steve Yegge's tools for taming the multi-agent coding experience. After setting them up on a real project (a Wave Protocol client for Emacs), I wanted to share what I learned.

The Problem: Context and Coordination

When you're working with AI coding agents, two problems dominate:

1. Context Loss: Agents lose track of what they were doing when sessions end
2. Coordination Chaos: Managing more than 3-4 agents manually becomes overwhelming

I experienced this firsthand trying to build out a comprehensive test suite and TUI dashboard for my Wave client project. Each feature needed exploration, planning, implementation, and testing—perfect work for parallel agents, but impossible to coordinate manually.

The Solution Stack

Beads: AI-Native Issue Tracking

Beads is issue tracking that lives in your repo. No web UI, no context switching—just CLI commands that AI agents can use as naturally as humans.

# Create issues
bd create --title="Extended REST API tests" --type=task --priority=2

# Check what's ready to work on
bd ready

# Track dependencies
bd dep add child-task parent-epic

# Get project health
bd stats

Key insight: Beads uses JSONL files stored in .beads/ that sync with git. This means:

• Issues travel with your code
• Agents can read/write issues directly
• No API tokens or external services needed

Here's what my project looks like after a planning session:

📊 Issue Database Status

Summary:
  Total Issues:           20
  Open:                   17
  In Progress:            0
  Blocked:                9
  Closed:                 3
  Ready to Work:          8

Extended:
  Avg Lead Time:          4.6 hours

Gas Town: Multi-Agent Orchestration

Gas Town is the orchestrator that makes parallel agent work possible. Think of it as Kubernetes for AI coding agents.

Core concepts:

Concept	Description
Town	Your workspace directory
Rig	A project container (can have multiple per town)
Mayor	The AI coordinator agent
Deacon	Watchdog process for agents
Witness	Monitors polecat activity
Refinery	Merge queue processor
Polecats	Ephemeral worker agents
Hooks	Git worktree persistent storage
Convoys	Batches of related work

# Check your town status
gt info

# List available work
bd ready

# Assign work to an agent
gt sling <issue-id> <rig>

# Create a convoy of related work
gt convoy create "integration-tests" issue-1 issue-2 issue-3

Real-World Setup: Wave Client Project

Here's my actual Gas Town configuration for the Wave Protocol client:

Town: wave-client-for-emacs
/home/jwalsh/ghq/github.com/aygp-dr/wave-client-for-emacs

👤 Overseer: Aidan Pace <apace@defrecord.com>

🎩 Mayor
   hq-mayor running
     hook: (none)

🐺 Deacon
   hq-deacon running [dead]
     hook: (none)

─── wave/ ───────────────────────────────────────────

🦉 Witness
   wa-wave-witness running
     hook: (none)

🏭 Refinery
   wa-wave-refinery running
     hook: (none)

The rig configuration in wave/config.json:

{
  "type": "rig",
  "version": 1,
  "name": "wave",
  "git_url": ".",
  "default_branch": "main",
  "beads": {
    "prefix": "wa"
  }
}

Structuring Work for Agents

The key to effective multi-agent work is proper issue structure. I organize work into:

Epics (High-level goals)

bd create --title="Full Integration Test Suite" --type=epic --priority=1
bd create --title="TUI Dashboard Demo" --type=epic --priority=1

Tasks (Concrete work items)

bd create --title="Extended REST API tests" --type=task --priority=2 \
  --description="Add 15+ REST tests covering wave lifecycle, wavelet ops"

bd create --title="Add WebSocket monitor mode to TUI" --type=task --priority=2

Dependencies (Work ordering)

# Tasks depend on (are blocked by) epics
bd dep add wave-client-for-emacs-3uh wave-client-for-emacs-4ez

This creates a clear work queue:

📋 Ready work (5 issues with no blockers):

1. [P1] [epic] wave-client-for-emacs-4ez: Full Integration Test Suite
2. [P1] [epic] wave-client-for-emacs-75v: TUI Dashboard Demo
3. [P0] [epic] wave-client-for-emacs-by8: Get Wave running end-to-end
4. [P2] [task] wave-client-for-emacs-x1z: Test WebSocket real-time updates
5. [P2] [task] wave-client-for-emacs-802: Seed database with test waves

And blocked work waiting for epics:

🚫 Blocked issues (9):

[P1] wave-client-for-emacs-l1h: Record basic TUI demo
  Blocked by 1 open dependencies: [wave-client-for-emacs-75v]

[P2] wave-client-for-emacs-3uh: Extended REST API tests
  Blocked by 1 open dependencies: [wave-client-for-emacs-4ez]
...

Molecules: Repeatable Workflows

Beads also supports "molecules"—predefined workflow patterns that agents can follow:

bd list --type=molecule

wave-client-for-emacs-vhm [P2] [molecule] open - Refinery Patrol
wave-client-for-emacs-dgu [P2] [molecule] open - Witness Patrol
wave-client-for-emacs-jbo [P2] [molecule] open - Deacon Patrol

These patrol molecules define recurring maintenance tasks that agents execute automatically.

The Grinding Session Workflow

A typical multi-agent coding session looks like:

1. Survey the landscape

bd stats           # Project health
bd ready           # Available work
gt info            # Agent status

2. Create convoys for related work

gt convoy create "test-suite" \
  wave-client-for-emacs-3uh \
  wave-client-for-emacs-c3s \
  wave-client-for-emacs-p70

3. Sling work to agents

gt sling wave-client-for-emacs-3uh wave    # REST tests
gt sling wave-client-for-emacs-c3s wave    # WebSocket tests
gt sling wave-client-for-emacs-p70 wave    # Multi-client tests

4. Monitor progress

gt agents          # Check agent status
bd list --status=in_progress

5. Close completed work

bd close wave-client-for-emacs-3uh wave-client-for-emacs-c3s
bd sync

System Requirements

My grinding setup:

Component	Version	Notes
FreeBSD	14.3-RELEASE	Also works on Linux/macOS
Python	3.11.13	For the Wave server
Emacs	30.1	For the Elisp client
Go	1.23+	For Gas Town
Beads	0.43.0+	Issue tracking
Gas Town	0.2.1+	Agent orchestration
Claude Code	Latest	The actual agents

Lessons Learned

1. Structure matters more than speed

Taking time to properly organize epics, tasks, and dependencies pays off exponentially when agents can work in parallel.

2. Beads sync is essential

Always run bd sync before and after major work sessions. The git-backed nature of beads means your issue state is as recoverable as your code.

3. Start small, scale up

Don't try to manage 20 agents on day one. Start with 2-3, learn the patterns, then scale.

4. The Mayor is your friend

Gas Town's Mayor agent can help coordinate work. Use gt mayor attach to get an AI coordinator helping manage the other agents.

5. Convoys prevent chaos

Grouping related issues into convoys keeps work organized and makes it easier to track progress on larger features.

What's Next

With this setup in place, my Wave client project has:

• 20 tracked issues
• 8 ready for immediate work
• Clear dependency chains
• Agents ready to grind

The future of coding is parallel, AI-assisted, and structured. Beads and Gas Town are the tools that make it manageable.

---

Tested on FreeBSD 14.3-RELEASE with Beads 0.43.0 and Gas Town 0.2.1

Resources

• Beads GitHub
• Gas Town GitHub
• Steve Yegge's "Welcome to Gas Town"
• Beads Viewer - Visual tool for beads data