Migration Guide: From Gastown to Tinytown

If Gastown feels heavier than what you need right now, Tinytown is the smaller Redis-based alternative. This guide shows how the mental model maps over.

Why You’re Here

Gastown is powerful but complex:

• 50+ concepts to understand
• Multiple agent types (Mayor, Deacon, Witness, Polecats, etc.)
• Two-level database architecture (Town beads + Rig beads)
• Daemon processes, patrols, and recovery mechanisms
• Hours to set up, days to understand

Tinytown started as a quicker, smaller alternative. It has grown since then, but it still aims to keep the coordination model more direct and the runtime lighter.

Quick Comparison

Concept Mapping

Gastown → Tinytown

What Tinytown Doesn’t Have

Still intentionally lighter:

Migration Steps

Step 1: Install Tinytown

git clone https://github.com/redis-field-engineering/tinytown.git
cd tinytown
cargo install --path .

Step 2: Initialize Your Project

Gastown:

# Multiple steps, daemon processes, config files...
gt boot
gt daemon start
# Configure rig, beads, etc.

Tinytown:

mkdir my-project && cd my-project
tt init --name my-project
# Done!

Step 3: Create Agents

Gastown:

# Configure polecat pools, spawn through Mayor...
gt mayor attach
# "Create a polecat for backend work"

Tinytown:

tt spawn backend --cli claude
tt spawn frontend --cli auggie
tt spawn reviewer --cli codex-mini

Step 4: Assign Work

Gastown:

# Create beads, slinging, convoys...
bd create --type task --title "Build API"
gt sling gt-abc12 gastown/polecats/Toast
gt convoy create "Feature X" gt-abc12

Tinytown:

tt assign backend "Build the REST API"
tt assign frontend "Build the UI"

Step 5: Monitor Progress

Gastown:

gt convoy list
gt convoy status hq-cv-abc
gt feed
gt dashboard  # requires tmux

Tinytown:

tt status
tt list

Code Migration

Gastown Pattern: Tell the Mayor

# Gastown: Complex orchestration
# You tell Mayor what you want, Mayor figures out the rest
gt mayor attach
> Build a user authentication system with login, signup, and password reset
# Mayor creates convoy, assigns polecats, tracks progress...

Tinytown Pattern: Direct Control

#![allow(unused)]
fn main() {
// Tinytown: You're in control
let town = Town::connect(".").await?;

// Create your team
let designer = town.spawn_agent("designer", "claude").await?;
let backend = town.spawn_agent("backend", "auggie").await?;
let frontend = town.spawn_agent("frontend", "codex").await?;

// Assign work explicitly
designer.assign(Task::new("Design auth API schema")).await?;
wait_for_idle(&designer).await?;

backend.assign(Task::new("Implement auth endpoints")).await?;
frontend.assign(Task::new("Build login/signup UI")).await?;

// Wait for both
tokio::join!(
    wait_for_idle(&backend),
    wait_for_idle(&frontend)
);
}

When to Use Tinytown vs Gastown

Use Tinytown When:

✅ You want to understand the system
✅ You need something working in 30 seconds
✅ You’re coordinating 1-5 agents
✅ You want to write your own orchestration logic
✅ You want a more direct coordination model

Use Gastown When:

✅ You need 20+ concurrent agents
✅ You need git-backed work history
✅ You need automatic crash recovery
✅ You need cross-project coordination
✅ You have time to learn the system

Common Questions

Q: Can I use both? A: Yes. Start with whichever matches the amount of machinery you actually need today.

Q: Is Tinytown production-ready? A: For small teams and projects, yes. For enterprise scale, consider Gastown.

Q: Can I migrate Tinytown work to Gastown? A: Tasks are JSON. You could write a converter to Beads format.

Q: Does Tinytown support everything Gastown does? A: No. Tinytown and Gastown make different tradeoffs, and Tinytown does not try to replace every part of a larger orchestration stack.