tinytown 0.10.0

A simple, fast multi-agent orchestration system using Redis for message passing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# Core Concepts Overview

Tinytown has exactly **5 core types**. That's it. No more, no less.

```
┌─────────────────────────────────────────┐
│           Your Application              │
└──────────────┬──────────────────────────┘
               │
        ┌──────▼───────┐
        │    Town      │  ← Orchestrator
        └──────┬───────┘
               │
        ┌──────▼──────────────────┐
        │   Channel (Redis)       │  ← Message passing
        └──────┬──────────────────┘
               │
    ┌──────────┼──────────────┐
    ▼          ▼              ▼
┌────────┐ ┌────────┐    ┌────────┐
│ Agent  │ │ Agent  │ .. │ Agent  │  ← Workers
└───┬────┘ └───┬────┘    └───┬────┘
    │          │              │
    ▼          ▼              ▼
  Tasks      Tasks          Tasks      ← Work units
```

## The 5 Core Types

| Type | What It Is | Redis Key Pattern |
|------|------------|-------------------|
| **[Town](./towns.md)** | The orchestrator that manages everything | N/A (local) |
| **[Agent](./agents.md)** | A worker that executes tasks | `tt:<town>:agent:<id>` |
| **[Task](./tasks.md)** | A unit of work with lifecycle | `tt:<town>:task:<id>` |
| **[Message](./messages.md)** | Communication between agents | Transient |
| **[Channel](./channels.md)** | Redis-based message transport | `tt:<town>:inbox:<id>` |

## How They Work Together

### 1. Town Orchestrates

The **Town** is your control center. It:
- Starts and manages Redis
- Spawns and tracks agents
- Provides the API for coordination

```bash
tt init my-project
tt status
```

### 2. Agents Execute

**Agents** are workers. Each agent has:
- A unique ID
- A name (human-readable)
- A CLI (claude, auggie, codex, etc.)
- A state (starting, idle, working, stopped)

```bash
tt spawn worker-1 --cli claude
tt list
```

### 3. Tasks Represent Work

**Tasks** are what agents work on. Each task has:
- A description
- A state (pending → assigned → running → completed/failed)
- An assigned agent

```bash
tt assign worker-1 "Implement the login API"
tt tasks
```

### 4. Messages Coordinate

**Messages** are how agents communicate. They carry:
- Sender and recipient
- Message type (TaskAssign, TaskDone, StatusRequest, etc.)
- Priority (Low, Normal, High, Urgent)

```bash
tt send worker-1 "Please update the README"
tt send worker-1 --urgent "Critical bug in production!"
```

### 5. Channel Transports

The **Channel** is the Redis connection that moves messages. It provides:
- Priority queues (urgent messages go first)
- Blocking receive (agents wait efficiently)
- State persistence (survives restarts)

## Mental Model

Think of it like a small company:

| Tinytown | Company Analogy |
|----------|-----------------|
| Town | The office building |
| Agent | An employee |
| Task | A work ticket |
| Message | An email/Slack message |
| Channel | The email/Slack system |

## What's NOT in Tinytown

Deliberately excluded to keep things simple:

- ❌ **Workflow DAGs** — Just assign tasks directly
- ❌ **Recovery daemons** — Redis persistence handles crashes
- ❌ **Multi-tier databases** — One Redis instance
- ❌ **Complex agent hierarchies** — All agents are peers

If you need these, you can build them on top of Tinytown's primitives, or use a more complex system like Gastown.

## Next Steps

Deep dive into each type:
- [Towns](./towns.md)
- [Agents](./agents.md)
- [Tasks](./tasks.md)
- [Messages](./messages.md)
- [Channels](./channels.md)