🏘️ Tinytown

Simple multi-agent orchestration using Redis — All the power of complex systems, none of the complexity.

Named after Tinytown, Colorado — a miniature village with big charm.

📚 Read the Documentation | 🚀 Getting Started Guide | 🔄 Coming from Gastown?

What is Tinytown?

Tinytown is a minimal, blazing-fast multi-agent orchestration system that lets you coordinate AI agents with Redis. It's designed for developers who want agent orchestration without the bloat.

Think of it as:

• Gastown, but 100x simpler ✨
• Temporal, but for humans 🧠
• Airflow, but actually fun to use 🎉

Why Tinytown?

📦 Install

cargo install tinytown

Prerequisites: Rust 1.85+ and Redis 8.0+ (or use tt bootstrap below).

🚀 Quick Start

# 0. Bootstrap Redis (one-time setup, uses AI to download & build)
tt bootstrap
export PATH="$HOME/.tt/bin:$PATH"

# 1. Initialize a new town (auto-names from git repo+branch)
tt init
# Creates town "my-repo-feature-branch"

# 2. Spawn an agent (uses default CLI from config)
tt spawn worker-1

# 3. Assign a task
tt assign worker-1 "Fix the bug in auth.rs"

# 3b. Add unassigned work to backlog (optional)
tt backlog add "Review auth error messages" --tags backend,review
tt backlog list

# 4. Or use the conductor - an AI that orchestrates for you
tt conductor
# Conductor: "I'll spawn agents and assign tasks. What do you want to build?"

That's it! Your agents are now coordinating via Redis.

Note: tt bootstrap delegates to an AI agent to download Redis from GitHub and compile it for your machine. Alternatively: brew install redis (macOS) or apt install redis-server (Ubuntu).

🎯 Mission Mode

Start an autonomous mission that handles multiple GitHub issues with dependency-aware scheduling:

# Start a mission spanning multiple issues
tt mission start --issue 23 --issue 24 --issue 25

# Check mission status and work items
tt mission status --work

# List all missions
tt mission list

Mission mode provides:

• Durable scheduling — State persisted in Redis, survives restarts
• Dependency tracking — Work items execute in DAG order
• PR/CI monitoring — Automatic watch loops for CI status, Bugbot, reviews
• Agent routing — Work assigned to best-fit agents by role

🌐 Programmatic Interfaces

Tinytown also ships a townhall control plane binary with both REST and MCP interfaces.

# REST API (default: 127.0.0.1:8080)
townhall rest

# MCP over stdio
townhall mcp-stdio

# MCP over HTTP/SSE (default: REST port + 1)
townhall mcp-http

REST OpenAPI spec: docs/openapi/townhall-v1.yaml

🏗️ Architecture

Tinytown is built on 7 core concepts:

        ┌─────────────────┐
        │   Conductor 🚂  │  (You talk to this)
        └────────┬────────┘
                 │ spawns, assigns, coordinates
        ┌────────▼────────┐
        │    Town 🏘️     │
        └────────┬────────┘
                 │
        ┌────────▼────────────────┐
        │   Redis (Unix Socket)   │  <1ms latency
        └────────┬────────────────┘
                 │
    ┌────────────┼────────────┐
    ▼            ▼            ▼
┌────────┐  ┌────────┐   ┌────────┐
│ Agent1 │  │ Agent2 │ … │ AgentN │
└────────┘  └────────┘   └────────┘

🎮 CLI Commands

🏛️ Townhall (HTTP Control Plane)

Townhall exposes Tinytown operations via REST API and MCP (Model Context Protocol):

# Start REST API server (default port 8787)
townhall

# Start MCP server for Claude Desktop integration
townhall mcp-stdio

See Townhall Documentation for API reference and authentication options.

🤖 Supported Agent CLIs

Built-in presets for popular AI coding agents (with correct non-interactive flags):

# Spawn uses default CLI from config (or override)
tt spawn worker-1
tt spawn worker-2 --model auggie
tt spawn worker-3 --model codex

⚙️ Configuration

Single tinytown.toml file:

name = "my-town"
default_cli = "claude"
max_agents = 10

[redis]
use_socket = true
socket_path = "redis.sock"

Setting the Default CLI

Change default_cli in tinytown.toml to set which AI CLI is used when spawning agents:

default_cli = "auggie"

Available options: claude, auggie, codex, aider, gemini, copilot, cursor

Or override per-agent:

tt spawn backend              # Uses default_model from config
tt spawn frontend --model auggie   # Override for this agent

🎯 Design Philosophy

Simplicity over features. We include only what you need:

✅ Agent spawning & lifecycle
✅ Task assignment & tracking
✅ Redis message passing
✅ Priority queues
❌ No workflow DAGs
❌ No distributed transactions
❌ No complex scheduling

If you need more, add it yourself in 10 lines.

🔧 Redis Installation

Redis 8.0+ is required. Tinytown will check your Redis version on startup.

🔧 Development

cargo build          # Build
cargo test           # Run tests
cargo clippy         # Lint

📄 License

MIT License - see LICENSE for details.

Made with ❤️ by Jeremy Plichta

Tinytown: Simple multi-agent orchestration for humans.