🏘️ Tinytown

Redis-native multi-agent orchestration built for fast feedback, direct control, and practical coordination.

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 compact, fast multi-agent orchestration system that lets you coordinate AI agents with Redis. It started as a deliberately small alternative to larger orchestration systems, and it is still fast because Redis keeps the runtime simple and responsive.

Think of it as:

• A smaller, easier-to-inspect orchestration stack
• Temporal, but for humans 🧠
• Airflow, but actually fun to use 🎉

Tinytown is no longer a tiny prototype, and the repo should not pretend otherwise. Building real agent-to-agent coding workflows turned out to require some durable state, recovery paths, scheduling, and coordination logic. The project goal is not "no complexity"; it is keeping the necessary complexity visible, local, and understandable.

Why Tinytown?

Current repo size, as of March 27, 2026:

• ~15.4K lines of Rust code in src/
• ~18.7K lines of Rust code across src/ and tests/
• 173 tests

📦 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

🐳 Docker Quickstart

Tinytown now ships two container targets:

• Dockerfile.townhall for the always-on control plane (townhall rest, townhall mcp-http, and the mission dispatcher)
• Dockerfile.agent-worker for on-demand coding workers (tt spawn --foreground plus a coding CLI)

The images assume Redis is external. For local development, docker-compose.yml wires both containers to a disposable Redis service and leaves the worker behind an opt-in profile so the default stack stays scale-to-zero.

# Start Redis + townhall control plane
docker compose up --build redis townhall

# In another terminal, start a worker when you actually want one
OPENAI_API_KEY=... docker compose --profile worker up --build agent-worker

When the townhall container first exposes REST on a non-loopback bind, it auto-generates a development API key, switches the town config to api_key auth, and stores the raw key in ${TINYTOWN_TOWN_DIR}/.townhall-api-key (the default compose setup writes that file into your checked-out workspace).

Environment knobs used by the images:

• REDIS_URL points Tinytown at external or managed Redis
• TINYTOWN_TOWN_DIR chooses the workspace/town path inside the container
• TINYTOWN_TOWN_NAME sets the initial town name when the container bootstraps a fresh workspace
• TINYTOWN_TOWNHALL_API_KEY_PATH overrides where the auto-generated REST API key is written
• TINYTOWN_AGENT_* variables configure the worker container (NAME, ROLE, CLI, MAX_ROUNDS)

Release builds now publish both images to GHCR:

• ghcr.io/redis-field-engineering/tinytown-townhall
• ghcr.io/redis-field-engineering/tinytown-agent-worker

🏗️ 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 8080)
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 --cli auggie
tt spawn worker-3 --cli codex-mini

⚙️ 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, codex-mini, aider, gemini, copilot, cursor

Or override per-agent:

tt spawn backend              # Uses default_cli from config
tt spawn frontend --cli 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.