Skip to main content

​
Synopsis

uzi run [OPTIONS] <command>
Alias: r

​
Description

The run command executes a shell command in all active agent sessions for the current repository. Unlike broadcast which sends messages to agents, run executes actual shell commands and captures their output. Each command runs in a new tmux window within the agent’s session, preserving the agent’s working directory context.

​
Options

​
--delete
boolean
default:"false"
Delete the tmux window after capturing the command output. This keeps sessions clean by removing temporary windows.
​
--config
string
default:"uzi.yaml"
Path to the configuration file (defaults to uzi.yaml in current directory).

​
Arguments

​
command
string
required
The shell command to execute in all agent sessions. All arguments are joined with spaces to form the complete command.

​
How It Works

1

Get Active Sessions

Retrieves all active sessions for the current repository from state
2

For Each Session

  1. Creates a new tmux window with an auto-incremented index
  2. Sends the command to that window
  3. Presses Enter to execute
  4. Captures the pane output
  5. Displays the output
  6. Optionally deletes the window (if --delete flag is set)

​
Examples

​
Check Git Status

# See git status in all agent worktrees
uzi run git status

​
Run Tests

# Execute test suite in all agents
uzi run npm test

​
List Modified Files

# See what files each agent has modified
uzi run git diff --name-only

​
With Auto-Cleanup

# Run command and delete the window afterward
uzi run --delete git log --oneline -5

​
Check Environment

# Verify environment variables or configuration
uzi run env | grep NODE_ENV

​
Multi-word Commands

# No quotes needed - args are joined
uzi run git log --oneline --graph -10

# Equivalent to:
uzi run "git log --oneline --graph -10"

​
Output Format

For each session, the command displays:
  1. Session name header: === session-name ===
  2. Captured command output
  3. Blank line separator
Example: 
Running command 'git status' in 2 agent sessions:

=== agent-myproject-a3f2b1c-thoughtful-tesla ===
On branch thoughtful-tesla-myproject-a3f2b1c-1234567890
Changes not staged for commit:
  modified:   src/auth.js

=== agent-myproject-a3f2b1c-clever-curie ===  
On branch clever-curie-myproject-a3f2b1c-1234567891
nothing to commit, working tree clean

​
Use Cases

Run linters or formatters across all agents:
uzi run npm run lint
uzi run --delete prettier --check .
Check if agents’ code compiles:
uzi run npm run build
uzi run --delete tsc --noEmit
Perform git commands across all worktrees:
uzi run git log --oneline -5
uzi run git diff --stat
uzi run --delete git branch -v
Debug or verify agent environments:
uzi run pwd
uzi run node --version
uzi run --delete ls -la
Run tests in all agent contexts:
uzi run npm test -- --coverage
uzi run pytest tests/

​
Window Management

​
Default Behavior

By default, run creates a new window for each command execution:
  • Windows are numbered sequentially (0, 1, 2, …)
  • Window remains open after command completes
  • You can attach to the session later and see the window

​
With --delete Flag

When using --delete:
  • Window is created and command runs
  • Output is captured
  • Window is immediately killed
  • Keeps sessions clean with only the :agent window
Example: 
# Without --delete: creates persistent windows
uzi run git status
# Result: Each agent session now has an extra window

# With --delete: temporary windows
uzi run --delete git status  
# Result: Agent sessions remain with just the :agent window

​
Working Directory

Commands execute in the agent’s worktree directory, ensuring:
  • Git commands operate on the agent’s isolated branch
  • File paths are relative to the agent’s working copy
  • Environment is identical to what the agent sees

​
Error Handling

  • If no command is provided: no command provided
  • If no active sessions: no active agent sessions found
  • If window creation fails: Logs error and continues to next session
  • If command fails: Output is still captured and displayed

​
Comparison with broadcast

Featurerunbroadcast
PurposeExecute shell commandsSend messages to agents
TargetNew tmux windowAgent window
OutputCaptured and displayedNot captured
CleanupOptional with --deleteN/A
Use CaseSystem commands, scriptsAgent instructions
Examples: 
# Use run for shell commands
uzi run git status
uzi run npm test

# Use broadcast for agent communication
uzi broadcast "fix the failing tests"
uzi broadcast "commit your changes"

​
Advanced Examples

​
Parallel Testing

# Run different test suites in parallel
uzi prompt --agents=random:3 "ready"
uzi broadcast "run your assigned test suite"
uzi run --delete npm test

​
Conditional Execution

# Only run if tests pass
uzi run "npm test && npm run build"

​
Complex Commands

# Use shell features like pipes and redirection
uzi run "git log --oneline | head -10 > /tmp/recent-commits.txt"
uzi run cat /tmp/recent-commits.txt

​
Chain Multiple Commands

# Execute multiple commands sequentially
uzi run "npm install && npm test && npm run lint"
  • broadcast - Send messages to agents (not shell commands)
  • prompt - Create agents to run commands in
  • ls - See which agents will execute the command
  • checkpoint - Merge results after running commands

​
Notes

Use --delete flag when running read-only commands to keep sessions clean:
uzi run --delete git status
uzi run --delete npm run lint
Commands run in parallel across all agents. Be cautious with commands that modify shared resources or have side effects.
The command inherits the agent’s environment and working directory, so file paths and environment variables are scoped to each agent’s worktree.

Build docs developers (and LLMs) love

Get started for freeTalk to us