Tinytown

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

Welcome to Tinytown! 🏘️

Tinytown is a compact, fast multi-agent orchestration system. It lets you coordinate AI coding agents (Claude, Augment, Codex, and more) using Redis for message passing.

Why Tinytown?

Tinytown started as a quick, intentionally small alternative to larger orchestration systems. It is still fast because Redis keeps the core runtime lightweight, but real multi-agent coding workflows have required some scheduling, recovery, and state-management complexity.

Core Philosophy

Simplicity is still a feature, but this project is no longer pretending orchestration is trivial.

Tinytown still tries to keep the core model tight. We include the pieces that have proven necessary in practice:

✅ Spawn and manage agents
✅ Assign tasks and track state
✅ Keep unassigned work in a shared backlog
✅ Pass messages between agents
✅ Persist work in Redis

And we still avoid a lot of heavier machinery:

❌ Complex workflow DAGs
❌ Distributed transactions
❌ Recovery daemons
❌ Multi-layer databases

Today the repo is roughly 15K lines of production Rust, about 19K including tests, with 173 tests. That is no longer “tiny,” but it is still small enough for one team to understand end to end.

Quick Example

# Initialize a town
tt init --name my-project

# Spawn agents (uses the default CLI, or specify with --cli)
tt spawn frontend
tt spawn backend
tt spawn reviewer

# Assign tasks
tt assign frontend "Build the login page"
tt assign backend "Create the auth API"
tt assign reviewer "Review PRs when ready"

# Or park unassigned tasks for role-based claiming
tt backlog add "Harden auth error handling" --tags backend,security
tt backlog list

# Check status
tt status

# Or let the conductor orchestrate for you!
tt conductor
# "Build a user authentication system"
# Conductor spawns agents, breaks down tasks, and coordinates...

That’s it. Your agents are now coordinating via Redis.

Plan Work with tasks.toml

For complex workflows, define tasks in a file:

tt plan --init   # Creates tasks.toml

Edit tasks.toml to define your pipeline:

[[tasks]]
id = "auth-api"
description = "Build the auth API"
agent = "backend"
status = "pending"

[[tasks]]
id = "auth-tests"
description = "Write auth tests"
agent = "tester"
parent = "auth-api"
status = "pending"

Then sync to Redis and let agents work:

tt sync push
tt conductor

See tt plan for the full task DSL.

What’s Next?

• Installation — Get Tinytown running in 30 seconds
• Quick Start — Your first multi-agent workflow
• Core Concepts — Understand Towns, Agents, Tasks, Messages, and Channels
• Townhall REST API — HTTP control plane for automation
• Townhall MCP Server — MCP tools/resources/prompts for LLM clients
• Coming from Gastown? — Migration guide for Gastown users

Named After

Tiny Town, Colorado — a miniature village with big charm, just like this project! 🏔️