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

# tt reclaim

Recover orphaned tasks from dead agents.

## Synopsis

```bash
tt reclaim [OPTIONS]
```

## Description

Finds tasks assigned to agents in terminal states (Stopped/Error) and moves them elsewhere. This prevents work from being lost when agents crash.

Without destination flags, lists orphaned tasks. With flags, moves them.

## Options

| Option | Description |
|--------|-------------|
| `--to-backlog` | Move orphaned tasks to the global backlog |
| `--to <AGENT>` | Move orphaned tasks to a specific agent |
| `--from <AGENT>` | Reclaim only from a specific dead agent |
| `--town <PATH>` | Town directory (default: `.`) |
| `--verbose` | Enable verbose logging |

## Examples

### Preview Orphaned Tasks

```bash
tt reclaim
```

Output:
```
🔄 Reclaiming orphaned tasks...
   worker-1 (Stopped): 3 message(s)
      task: 550e8400-e29b-41d4-a716-446655440000
      task: Fix authentication bug in login endpoint
      task: Update database schema

📋 Found 3 orphaned task(s)
   Use --to-backlog or --to <agent> to reclaim them
```

### Move Tasks to Backlog

```bash
tt reclaim --to-backlog
```

Output:
```
🔄 Reclaiming orphaned tasks...
   worker-1 (Stopped): 3 message(s)
      → backlog: 550e8400-e29b-41d4-a716-446655440000
      → backlog: 660e9500-e29b-41d4-a716-446655440111
      → backlog: 770f0600-e29b-41d4-a716-446655440222

✅ Moved 3 task(s) to backlog
```

### Reassign to Another Agent

```bash
tt reclaim --to worker-2
```

Output:
```
🔄 Reclaiming orphaned tasks...
   worker-1 (Stopped): 3 message(s)
      → worker-2: 550e8400-e29b-41d4-a716-446655440000
      → worker-2: Fix authentication bug in login endpoint
      → worker-2: Update database schema

✅ Moved 3 task(s) to 'worker-2'
```

### Reclaim from Specific Agent

```bash
tt reclaim --from worker-1 --to-backlog
```

## Common Workflow

After a crash:

```bash
# 1. Recover orphaned agents first
tt recover

# 2. Reclaim their tasks to backlog
tt reclaim --to-backlog

# 3. Clean up stopped agents
tt prune

# 4. Restart or spawn new agents
tt restart worker-1
# or
tt spawn worker-3

# 5. Let agents claim from backlog
```

## See Also

- [tt recover](./recover.md) — Mark orphaned agents as stopped
- [tt prune](./prune.md) — Remove stopped agents
- [tt backlog](./backlog.md) — Manage the backlog
- [Error Handling & Recovery](../tutorials/recovery.md) — Recovery tutorial