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

# tt migrate

Migrate Redis keys from old format to town-isolated format.

## Synopsis

```bash
tt migrate [OPTIONS]
```

## Description

The `migrate` command handles backward compatibility when upgrading to a version of Tinytown that uses town-isolated Redis keys. Older versions stored keys in the format `tt:type:id`, while newer versions use `tt:<town_name>:type:id` to support multiple towns sharing the same Redis instance.

This migration is:
- **Safe**: Preview with `--dry-run` before committing
- **Idempotent**: Running multiple times has no effect after initial migration
- **Atomic**: Each key is renamed atomically

## Options

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview migration without making changes |
| `--force` | Skip confirmation prompt |

## Key Formats

### Old Format (pre-isolation)
```
tt:agent:<uuid>
tt:inbox:<uuid>
tt:urgent:<uuid>
tt:task:<uuid>
tt:activity:<uuid>
tt:stop:<uuid>
tt:backlog
```

### New Format (town-isolated)
```
tt:<town_name>:agent:<uuid>
tt:<town_name>:inbox:<uuid>
tt:<town_name>:urgent:<uuid>
tt:<town_name>:task:<uuid>
tt:<town_name>:activity:<uuid>
tt:<town_name>:stop:<uuid>
tt:<town_name>:backlog
```

## Examples

### Preview Migration (Dry Run)

```bash
tt migrate --dry-run
```

Output:
```
🔍 Migration Preview (dry run)
   Town: my-project

   Keys to migrate:
   tt:agent:abc123 → tt:my-project:agent:abc123
   tt:inbox:abc123 → tt:my-project:inbox:abc123
   tt:task:def456 → tt:my-project:task:def456

   Total: 3 key(s) would be migrated

   Run 'tt migrate' (without --dry-run) to perform migration.
```

### Perform Migration (Interactive)

```bash
tt migrate
```

Prompts for confirmation before proceeding.

### Perform Migration (Force)

```bash
tt migrate --force
```

Skips the confirmation prompt. Useful for automation/CI.

## When to Use

You need to run migration if:

1. **Upgrading from an older version**: If you're upgrading from a version that didn't have town isolation, your existing keys need migration.

2. **Seeing "no migration needed" message**: If the command reports no migration needed, your keys are already in the new format.

3. **Sharing Redis between towns**: Town isolation allows multiple Tinytown projects to use the same Redis instance without key conflicts.

## Recovery

If migration fails partway through:

1. Check which keys failed in the output
2. Investigate the specific errors
3. Run `tt migrate` again (idempotent - already-migrated keys won't be re-migrated)

## See Also

- [tt init](./init.md) - Initialize a new town
- [tt reset](./reset.md) - Reset all town state
- [Towns concept](../concepts/towns.md) - Understanding towns