tt spawn

Create and start a new agent.

Synopsis

tt spawn <NAME> [OPTIONS]

Description

Spawns a new worker agent in the town. This actually starts an AI process!

The agent:

Registers in Redis with state Starting
Starts a background process (or foreground with --foreground)
Runs in a loop, checking inbox for tasks
Executes the AI model (claude, auggie, etc.) for each task
Stops after --max-rounds iterations

Arguments

Argument	Description
`<NAME>`	Human-readable agent name (e.g., `worker-1`, `backend`, `reviewer`)

Options

Option	Short	Description
`--model <MODEL>`	`-m`	AI CLI to use (default: from `tinytown.toml`)
`--max-rounds <N>`		Maximum iterations before stopping (default: 10)
`--foreground`		Run in foreground instead of background
`--town <PATH>`	`-t`	Town directory (default: `.`)
`--verbose`	`-v`	Enable verbose logging

Setting the Default CLI

Edit tinytown.toml to change which AI CLI is used by default:

name = "my-town"
default_cli = "auggie"

Then all tt spawn commands use that CLI:

tt spawn backend              # Uses auggie (from config)
tt spawn frontend --model codex   # Override to use codex

Built-in Agent CLIs

CLI	Command (non-interactive)
`claude`	`claude --print --dangerously-skip-permissions`
`auggie`	`auggie --print`
`codex`	`codex exec --dangerously-bypass-approvals-and-sandbox`
`aider`	`aider --yes --no-auto-commits --message`
`gemini`	`gemini`
`copilot`	`gh copilot`
`cursor`	`cursor`

These are the CLI tools that run AI coding agents, not the underlying models.

Examples

Spawn in Background (Default)

tt spawn worker-1
# Agent runs in background, logs to logs/worker-1.log

Spawn in Foreground (See Output)

tt spawn worker-1 --foreground
# Agent runs in this terminal, you see all output

Limit Iterations

tt spawn worker-1 --max-rounds 5
# Agent stops after 5 rounds (default is 10)

Spawn Multiple Agents (Parallel!)

tt spawn backend &
tt spawn frontend &
tt spawn tester &
# All three run in parallel

Output

🤖 Spawned agent 'backend' using model 'auggie'
   ID: 550e8400-e29b-41d4-a716-446655440000
🔄 Starting agent loop in background (max 10 rounds)...
   Logs: ./logs/backend.log
   Agent running in background. Check status with 'tt status'

What Happens

Agent registered in Redis (tt:<town>:agent:<id>)
Background process started running tt agent-loop
Agent loop:
- Checks inbox for messages
- If messages: builds prompt, runs AI model
- Model output logged to logs/<name>_round_<n>.log
- Repeats until --max-rounds reached
Agent stops with state Stopped

Agent Naming

Choose descriptive names:

Good Names	Why
`backend`	Describes the work area
`worker-1`	Simple numbered workers
`reviewer`	Describes the role
`alice`	Personality names work too

Avoid	Why
`agent`	Too generic
`a`	Not descriptive
Spaces	Use hyphens instead

Agent State After Spawn

New agents start in Starting state, then transition to Idle:

Starting → Idle (ready for work)

Check state with:

tt list

Errors

Town Not Initialized

Error: Town not initialized at . Run 'tt init' first.

Solution: Run tt init or specify --town path.

Agent Already Exists

Agents are tracked by name. Spawning the same name creates a new agent with a new ID.

Tinytown