Skip to main content

​
Overview

This guide walks you through running multiple AI agents in parallel to solve a coding task. You’ll learn how to create agents, monitor their progress, and merge the best solution back into your codebase.
Make sure you’ve completed the Installation steps before continuing.

​
Your first multi-agent workflow

1

Navigate to your project

Open a terminal and navigate to your Git repository:
cd ~/projects/my-app
Verify you’re in a Git repository:
git status
2

Create agents with a prompt

Start multiple agents with a task. This example runs 3 Claude agents and 2 Codex agents:
uzi prompt --agents claude:3,codex:2 "Create a reusable Button component with variants for primary, secondary, and outline styles. Include TypeScript types and add examples to the main page."
For each agent, Uzi:
  1. Creates a new Git worktree in ~/.local/share/uzi/worktrees/
  2. Creates a new Git branch (e.g., agent-myapp-abc123-fluffy-elephant)
  3. Spawns a tmux session for the agent
  4. Finds an available port from your configured range
  5. Starts your dev server (if configured in uzi.yaml)
  6. Launches the AI agent with your prompt
You’ll see output like:
fluffy-elephant: claude: Create a reusable Button component...
happy-giraffe: claude: Create a reusable Button component...
silly-penguin: claude: Create a reusable Button component...
brave-tiger: codex: Create a reusable Button component...
clever-dolphin: codex: Create a reusable Button component...
3

Enable auto-confirmation

Run uzi auto to automatically press Enter for tool confirmations and trust prompts:
uzi auto
This command monitors all active agents and automatically:
  • Confirms “Do you trust the files in this folder?” prompts
  • Presses Enter for “Allow command” prompts
  • Handles “Continue? (Y/n)” confirmations
Leave this running in a separate terminal window while your agents work.
4

Monitor agent progress

In another terminal, watch your agents’ progress in real-time:
uzi ls -w
The -w flag enables watch mode, refreshing every second. You’ll see:
AGENT             MODEL   STATUS     DIFF      ADDR                      PROMPT
fluffy-elephant   claude  running    +142/-8   http://localhost:3001     Create a reusable Button component...
happy-giraffe     claude  ready      +89/-3    http://localhost:3002     Create a reusable Button component...
silly-penguin     claude  running    +156/-12  http://localhost:3003     Create a reusable Button component...
brave-tiger       codex   ready      +67/-5    http://localhost:3004     Create a reusable Button component...
clever-dolphin    codex   running    +201/-15  http://localhost:3005     Create a reusable Button component...
​
AGENT
string
The randomly generated agent name (e.g., fluffy-elephant)
​
MODEL
string
The AI tool being used (e.g., claude, codex)
​
STATUS
string
Current status:
  • ready (green): Agent is idle or waiting for input
  • running (orange): Agent is actively thinking or executing
​
DIFF
string
Code changes: +insertions/-deletions
​
ADDR
string
Development server URL (if configured)
​
PROMPT
string
The task given to the agent (truncated)
Press Ctrl+C to exit watch mode.
5

Review agent work

Visit each agent’s development server to see their implementation:
# Open in your browser
open http://localhost:3001  # fluffy-elephant
open http://localhost:3002  # happy-giraffe
# etc.
Or attach to an agent’s tmux session to see what they’re doing:
tmux attach -t agent-myapp-abc123-fluffy-elephant
Press Ctrl+B then D to detach without closing the session.
6

Checkpoint the best solution

Once you’ve found an agent whose solution you like, merge it back to your main branch:
uzi checkpoint fluffy-elephant "feat: add Button component with variants"
This command:
  1. Stages all changes in the agent’s worktree
  2. Creates a commit with your message
  3. Rebases the agent’s branch onto your current branch
  4. Merges the changes into your working directory
Make sure your current branch is clean before checkpointing. Commit or stash any uncommitted changes first.
7

Clean up agents

After checkpointing, clean up the agents:
# Kill a specific agent
uzi kill fluffy-elephant

# Or kill all agents at once
uzi kill all
This removes tmux sessions and cleans up Git worktrees.

​
Advanced usage

​
Use random agent names

If you don’t care about specific tools, use random agent names: 
uzi prompt --agents random:5 "Fix all TypeScript errors in the codebase"
This creates 5 agents with random names, each using their name as the command.

​
Send additional instructions

Broadcast a message to all running agents: 
uzi broadcast "Make sure to add input validation and error handling"
This sends the message to every active agent’s tmux session.

​
Run commands across all agents

Execute a command in all agent sessions: 
# Run tests in all agents
uzi run "npm test"

# Check git status in all agents
uzi run "git status"

# Run and auto-delete the window
uzi run --delete "npm run lint"
The --delete flag removes the tmux window after the command completes.

​
List agents without watch mode

Get a one-time snapshot of agent status: 
uzi ls
Use aliases for faster commands: 
uzi l    # alias for ls
uzi p    # alias for prompt
uzi w    # alias for auto (watch)
uzi k    # alias for kill
uzi c    # alias for checkpoint
uzi b    # alias for broadcast
uzi r    # alias for run

​
Real-world example

Here’s a complete workflow for adding a new feature: 
# 1. Start agents with a complex task
uzi prompt --agents claude:2,aider:2 "Refactor the authentication system to use OAuth2. Add support for Google and GitHub providers. Include migration scripts and update the API documentation."

# 2. Auto-confirm prompts (in separate terminal)
uzi auto

# 3. Watch progress (in another terminal)
uzi ls -w

# 4. After reviewing their work, checkpoint the best solution
uzi checkpoint happy-giraffe "feat: add OAuth2 authentication with Google and GitHub"

# 5. Clean up
uzi kill all

# 6. Push to remote
git push origin main

​
Troubleshooting

​
Agents not responding

If agents appear stuck:
  1. Attach to the agent’s tmux session to see what’s happening: 
    tmux attach -t agent-myapp-abc123-agent-name
  2. Check if uzi auto is running in another terminal
  3. Manually press Enter in the agent’s session if needed

​
Port conflicts

If you see port errors:
  1. Check your uzi.yaml port range is large enough
  2. Kill any processes using ports in your range: 
    lsof -ti:3000 | xargs kill -9

​
No changes to checkpoint

If checkpoint shows no changes:
  1. Verify the agent made changes: 
    uzi ls
    Look for non-zero values in the DIFF column
  2. Check the agent’s worktree directly: 
    cd ~/.local/share/uzi/worktrees/agent-name-*
git status

​
Reset everything

If things get messy, reset all Uzi data: 
uzi reset
This deletes all worktrees, sessions, and state data in ~/.local/share/uzi/. Use with caution.

​
Next steps

Commands reference

Learn about all available Uzi commands and options

Configuration

Advanced configuration options for uzi.yaml

Best practices

Tips for getting the most out of parallel agents

Workflows

Common workflows and use cases for Uzi

Build docs developers (and LLMs) love

Get started for freeTalk to us