tt assign

Assign a task to an agent.

Synopsis

tt assign <AGENT> <TASK>

Description

Creates a new task record and sends it to the specified agent’s inbox as a semantic task message.

tt assign sends a semantic task message and is the right command for actionable work. Use tt send for non-task communication such as queries, informational updates, or confirmations.

Arguments

Argument	Description
`<AGENT>`	Agent name to assign to
`<TASK>`	Task description (quoted string)

Options

Option	Short	Description
`--town <PATH>`	`-t`	Town directory (default: `.`)
`--verbose`	`-v`	Enable verbose logging

Examples

Basic Assignment

tt assign worker-1 "Implement the login API"

Multi-line Task

tt assign backend "Create a REST API endpoint POST /users that:
- Accepts {email, password, name}
- Validates email format
- Hashes password with bcrypt
- Returns {id, email, name, created_at}"

Assign to Multiple Agents

tt assign frontend "Build the login form"
tt assign backend "Build the auth API"
tt assign tester "Write integration tests"

Output

📋 Assigned task 550e8400-e29b-41d4-a716-446655440000 to agent 'worker-1'

What Happens

Task created with state Pending
Task stored in Redis at tt:<town>:task:<id>
Message sent to agent’s inbox at tt:<town>:inbox:<agent-id>
Task state updated to Assigned

Task Lifecycle After Assignment

Pending → Assigned → Running → Completed
                           └─→ Failed
                           └─→ Cancelled

Viewing Assigned Tasks

Check what’s in an agent’s inbox:

# Using redis-cli (replace <town> with your town name)
redis-cli -s ./redis.sock LLEN tt:<town>:inbox:<agent-id>
redis-cli -s ./redis.sock LRANGE tt:<town>:inbox:<agent-id> 0 -1

Or check status:

tt status

Errors

Agent Not Found

Error: Agent not found: nonexistent

Solution: Spawn the agent first with tt spawn.

Town Not Initialized

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

Task Description Tips

Good task descriptions:

Be specific about what to build
Include acceptance criteria
Mention relevant files/paths
Specify output format if needed

# ✅ Good
tt assign backend "Create POST /api/users endpoint in src/routes/users.rs. 
Accept JSON body {email, password}. Return 201 with {id, email}."

# ❌ Too vague
tt assign backend "Build API"

Use tt assign when the recipient should do concrete work, not just acknowledge or discuss.

Tinytown