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 selected AI CLI (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
`--cli <CLI>`	`-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
`--role <ROLE>`		Explicit role ID for routing (e.g., `worker`, `reviewer`, `researcher`)
`--nickname <NAME>`		Human-facing display name (separate from canonical name)
`--parent <AGENT>`		Parent agent name or ID (for delegated subtasks)
`--town <PATH>`	`-t`	Town directory (default: `.`)
`--verbose`	`-v`	Enable verbose logging

Role-Based Routing

When you set --role, the mission scheduler uses it for matching work items to agents instead of inferring roles from the agent name. This is more reliable:

# Without --role: scheduler guesses from name "backend" → probably a worker
tt spawn backend

# With --role: scheduler knows this is explicitly a reviewer
tt spawn backend --role reviewer

Built-in roles: worker, reviewer, researcher, runner.

Agents are displayed in the format Nickname [role] (e.g., “Fred [reviewer]”, “Martha [backend]”). Nicknames are auto-assigned from a curated list if not explicitly set.

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 --cli codex-mini   # Override to use codex-mini

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`
`codex-mini`	`codex exec --dangerously-bypass-approvals-and-sandbox -m gpt-5.4-mini -c model_reasoning_effort="medium"`
`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 with Role and Nickname

tt spawn backend --role worker --nickname "API Developer"
tt spawn qa --role reviewer --nickname "Quality Gate"

Spawn with Parent (Delegated Subtasks)

tt spawn subtask-1 --role worker --parent backend
# Creates a child agent linked to 'backend' in the agent hierarchy

Spawn Multiple Agents (Parallel!)

tt spawn backend --role worker &
tt spawn frontend --role worker &
tt spawn tester --role tester &
tt spawn reviewer --role reviewer &
# All four run in parallel with explicit roles

Output

🤖 Spawned agent 'backend' using CLI '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 the selected CLI
- CLI output logged to logs/<name>_round_<n>.log
- Repeats until --max-rounds reached
Agent stops with state Stopped

Agent Naming

Choose descriptive names. With --role, names no longer need to describe the role:

Good Names	Why
`backend`	Describes the work area
`worker-1`	Simple numbered workers
`alice`	Personality names work — use `--role` for routing

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

Tip: Use --nickname for human-friendly display names (e.g., --nickname "Quality Gate") while keeping canonical names short for CLI usage.

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