Quick Start

Let’s get a multi-agent workflow running in under 5 minutes.

First time? Make sure you’ve installed Tinytown first.

Step 1: Initialize a Town

A Town is your orchestration workspace. It manages Redis, agents, and message passing.

# Create a project directory
mkdir my-project && cd my-project

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

You’ll see:

✨ Initialized town 'my-project' at .
📡 Redis running with Unix socket for fast message passing
🚀 Run 'tt spawn <name>' to create agents

This creates:

tinytown.toml — Configuration file
agents/ — Agent working directories
logs/ — Activity logs
tasks/ — Task storage
redis.sock — Unix socket for fast Redis communication

Step 2: Spawn an Agent

Agents are workers that execute tasks. Spawn one:

tt spawn worker-1

Output:

🤖 Spawned agent 'worker-1' using model 'claude'
   ID: 550e8400-e29b-41d4-a716-446655440000

The agent uses default_model from your config. Spawn more:

tt spawn worker-2
tt spawn reviewer

Or override with --model:

tt spawn specialist --model codex

Step 3: Assign Tasks

Give your agents something to do:

tt assign worker-1 "Implement the user login API endpoint"
tt assign worker-2 "Write tests for the login API"
tt assign reviewer "Review the login implementation when ready"

Step 4: Check Status

See what’s happening in your town:

tt status

Output:

🏘️  Town: my-project
📂 Root: /path/to/my-project
📡 Redis: unix:///path/to/my-project/redis.sock
🤖 Agents: 3
   worker-1 (Working) - 0 messages pending
   worker-2 (Idle) - 1 messages pending
   reviewer (Idle) - 1 messages pending

List all agents:

tt list

Step 5: Keep It Running

To keep a town connection open during development:

tt start

Press Ctrl+C to stop gracefully.

What Just Happened?

You created a Town with three Agents. Each agent received a Task via a Message sent through a Redis Channel.

That’s the entire Tinytown model:

Town → spawns → Agents
       ↓
     Channel (Redis)
       ↓
     Messages → contain → Tasks

Bonus: Planning with tasks.toml

For larger projects, define tasks in a file instead of CLI commands:

# Initialize a task plan
tt plan --init

Edit tasks.toml:

[[tasks]]
id = "login-api"
description = "Implement the user login API endpoint"
agent = "worker-1"
status = "pending"

[[tasks]]
id = "login-tests"
description = "Write tests for the login API"
agent = "worker-2"
status = "pending"
parent = "login-api"

Sync to Redis:

tt sync push

Now your tasks are version-controlled and can be reviewed in PRs. See tt plan for more.

Next Steps

Your First Town — Deeper dive into town setup
Core Concepts — Understand the 5 core types
Single Agent Workflow — Complete tutorial

Keyboard shortcuts

Tinytown