🏘️ 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"

# 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).

🏗️ Architecture

Tinytown is built on 6 core concepts:

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

🎮 CLI Commands

🤖 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.json file:

{
  "name": "my-town",
  "redis": {
    "use_socket": true,
    "socket_path": "redis.sock"
  },
  "default_model": "claude",
  "max_agents": 10
}

Setting the Default CLI

Change default_model in tinytown.json to set which AI CLI is used when spawning agents:

{
  "default_model": "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.