Agent Commands

The sf agent command group manages orchestrator agents — the AI coding agents that execute tasks, plan work, and handle merge review.

sf agent list

List all registered agents with filtering options. Usage:

sf agent list [options]

Options

--role

string

default:""

Filter by agent role: director, worker, or steward

--status

string

default:""

Filter by session status: idle, running, suspended, or terminated

--workerMode

string

default:""

Filter by worker mode: ephemeral or persistent

--focus

string

default:""

Filter by steward focus: merge, docs, recovery, or custom

--reportsTo

string

default:""

Filter by manager entity ID

--hasSession

boolean

default:"false"

Show only agents with active sessions

Examples

# List all agents
sf agent list

# List only worker agents
sf agent list --role worker

# List ephemeral workers
sf agent list --role worker --workerMode ephemeral

# List running agents
sf agent list --status running

# List merge stewards
sf agent list --role steward --focus merge

# List agents with active sessions
sf agent list --hasSession

Output

ID            NAME         ROLE      STATUS   SESSION
el-abc123     MyWorker     worker    idle     -
el-def456     MainDir      director  running  a1b2c3d4
el-ghi789     MergeSt      steward   idle     -

3 agent(s)

sf agent show

Show detailed information about a specific agent. Usage:

sf agent show <id>

Arguments

string

required

Agent identifier (e.g., el-abc123)

Examples

sf agent show el-abc123

Output

ID:       el-abc123
Name:     MyWorker
Role:     worker
Status:   idle
Session:  -
Channel:  -
Created:  2026-03-01T10:00:00Z
Mode:     ephemeral

sf agent register

sf agent register <name> --role <role> [options]

Arguments

name

string

required

Human-readable name for the agent

Options

--role

string

required

Agent role: director, worker, or steward

--mode

string

default:"ephemeral"

Worker mode: ephemeral or persistent (worker agents only)

--focus

string

default:"merge"

Steward focus: merge, docs, recovery, or custom (steward agents only)

--maxTasks

number

default:"1"

Maximum concurrent tasks the agent can handle

--tags

string

default:""

Comma-separated tags (e.g., frontend,urgent)

--reportsTo

string

default:""

Manager entity ID (for workers and stewards)

--roleDef

string

default:""

Role definition document ID for custom instructions

--trigger

string

default:""

Steward cron trigger (e.g., "0 2 * * *" for 2am daily)

--provider

string

default:"claude-code"

Agent provider: claude-code, opencode, or openai-codex

--model

string

default:""

LLM model to use (e.g., claude-sonnet-4-5-20250929)

Examples

# Register an ephemeral worker
sf agent register MyWorker --role worker --mode ephemeral

# Register a director
sf agent register MainDirector --role director

# Register a merge steward
sf agent register MergeSteward --role steward --focus merge

# Register with tags
sf agent register FrontendWorker --role worker --tags "frontend,ui"

# Register with manager
sf agent register TeamWorker --role worker --reportsTo el-director123

# Register a scheduled docs steward
sf agent register DocsSteward --role steward --focus docs --trigger "0 9 * * *"

# Register with OpenCode provider
sf agent register OcWorker --role worker --provider opencode

# Register with specific model
sf agent register MyWorker --role worker --model claude-opus-4-6

Output

Registered worker agent: el-abc123

sf agent start

Start (spawn) an agent process. Usage:

sf agent start <id> [options]

Arguments

string

required

Agent identifier

Options

--prompt

string

default:""

Initial prompt to send to the agent

--mode

string

default:""

Spawn mode: headless or interactive

--resume

string

default:""

Provider session ID to resume

--workdir

string

default:"."

Working directory for the agent

--cols

number

default:"120"

Terminal columns for interactive mode

--rows

number

default:"30"

Terminal rows for interactive mode

--timeout

number

default:"120000"

Timeout in milliseconds

--env

string

default:""

Environment variable to set (format: KEY=VALUE, can be repeated)

--taskId

string

default:""

Task ID to assign to this agent session

--stream

boolean

default:"false"

Stream agent output after spawning (blocks until session ends)

--provider

string

default:""

Override agent provider for this session

--model

string

default:""

Override model for this session (e.g., claude-opus-4-6)

Examples

# Start an agent
sf agent start el-abc123

# Start in interactive mode
sf agent start el-abc123 --mode interactive

# Start with custom terminal size
sf agent start el-abc123 --mode interactive --cols 160 --rows 40

# Start with initial prompt
sf agent start el-abc123 --prompt "Start working on your assigned tasks"

# Resume a previous session
sf agent start el-abc123 --resume prev-session-id

# Set environment variable
sf agent start el-abc123 --env MY_VAR=value

# Assign a task to the agent
sf agent start el-abc123 --taskId el-task456

# Stream output
sf agent start el-abc123 --stream

# Use OpenCode provider
sf agent start el-abc123 --provider opencode

# Override model
sf agent start el-abc123 --model claude-opus-4-6

Output

Spawned agent el-abc123
  Session ID:  sess-abc123
  Provider ID: claude-session-xyz
  Status:      running
  Mode:        headless
  PID:         12345
  Task ID:     el-task456

sf agent stop

Stop an agent session. Usage:

sf agent stop <id> [options]

Arguments

string

required

Agent identifier

Options

--graceful

boolean

default:"true"

Graceful shutdown (default)

--no-graceful

boolean

default:"false"

Force immediate shutdown

--reason

string

default:""

Reason for stopping the agent

Examples

# Stop an agent (gracefully)
sf agent stop el-abc123

# Stop with reason
sf agent stop el-abc123 --reason "Task completed"

# Force stop
sf agent stop el-abc123 --no-graceful

Output

Stopped agent el-abc123

sf agent stream

Get the channel ID for an agent to stream messages. Usage:

sf agent stream <id>

Arguments

string

required

Agent identifier

Examples

sf agent stream el-abc123

Output

Agent el-abc123 channel: ch-xyz789
Use "sf channel stream ch-xyz789" to watch messages

Common Patterns

Register and Start a Worker

# Register
WORKER_ID=$(sf agent register MyWorker --role worker --mode ephemeral --quiet)

# Start with streaming
sf agent start $WORKER_ID --stream

List Active Sessions

sf agent list --hasSession

Stop All Running Agents

for id in $(sf agent list --status running --quiet); do
  sf agent stop $id
done

Task Commands

Manage tasks that agents work on

Daemon Commands

Control automatic task dispatch to agents

Commands

​Agent Commands

​sf agent list

​Options

​Examples

​Output

​sf agent show

​Arguments

​Examples

​Output

​sf agent register

​Arguments

​Options

​Examples

​Output

​sf agent start

​Arguments

​Options

​Examples

​Output

​sf agent stop

​Arguments

​Options

​Examples

​Output

​sf agent stream

​Arguments

​Examples

​Output

​Common Patterns

​Register and Start a Worker

​List Active Sessions

​Stop All Running Agents

​Related Commands

Task Commands

Daemon Commands

Build docs developers (and LLMs) love

Agent Commands

sf agent list

Options

Examples

Output

sf agent show

Arguments

Examples

Output

sf agent register

Arguments

Options

Examples

Output

sf agent start

Arguments

Options

Examples

Output

sf agent stop

Arguments

Options

Examples

Output

sf agent stream

Arguments

Examples

Output

Common Patterns

Register and Start a Worker

List Active Sessions

Stop All Running Agents

Related Commands