Agent Options

Complete reference for SRBN agent configuration.

Basic Usage

perspt agent [OPTIONS] <TASK>

Required Arguments

<TASK>

Task description or path to task file

Model Selection

Option

Description

--model <MODEL>

Override ALL model tiers

--architect-model <MODEL>

Model for task decomposition (deep reasoning)

--actuator-model <MODEL>

Model for code generation

--verifier-model <MODEL>

Model for stability checking

--speculator-model <MODEL>

Model for fast lookahead

Example:

perspt agent \
  --architect-model gpt-5.2 \
  --actuator-model claude-opus-4.5 \
  "Build REST API"

Execution Control

Option

Description

-w, --workdir <DIR>

Working directory (default: current)

-y, --yes

Auto-approve all actions

--auto-approve-safe

Auto-approve read-only operations only

-k, --complexity <K>

Max tasks before approval prompt (default: 5)

--mode <MODE>

Execution mode: cautious, balanced, yolo

Modes:

cautious

Prompt for every change

balanced

Prompt when complexity > K (default)

yolo

Auto-approve everything (⚠️ dangerous)

SRBN Parameters

Option

Description

--energy-weights <α,β,γ>

Lyapunov weights (default: 1.0,0.5,2.0)

--stability-threshold <ε>

Convergence threshold (default: 0.1)

Energy Formula: V(x) = α·V_syn + β·V_str + γ·V_log

Tuning Examples:

# Prioritize tests (raise γ)
perspt agent --energy-weights "1.0,0.5,3.0" "Add tests"

# Prioritize type safety (raise α)
perspt agent --energy-weights "2.0,0.5,1.0" "Add type hints"

# More lenient (raise ε)
perspt agent --stability-threshold 0.5 "Quick prototype"

Limits

Option

Description

--max-cost <USD>

Maximum cost in dollars (0 = unlimited)

--max-steps <N>

Maximum iterations (0 = unlimited)

Example:

perspt agent --max-cost 5.0 --max-steps 20 "Large refactor"

Logging and Debugging

Option

Description

--log-llm

Log all LLM requests/responses to database

--defer-tests

Defer tests until sheaf validation (faster iteration)

Example:

# Debug with full LLM logging
perspt agent --log-llm "Debug task"

# View logs after run
perspt logs --tui

Session Management

# Check current status
perspt status

# Cancel current session
perspt abort
perspt abort --force  # No confirmation

# Resume interrupted session
perspt resume
perspt resume <session_id>

Ledger Operations

# View recent changes
perspt ledger --recent

# Rollback to commit
perspt ledger --rollback <hash>

# Statistics
perspt ledger --stats

Full Examples

Conservative approach:

perspt agent \
  --mode cautious \
  -k 1 \
  --max-cost 1.0 \
  --max-steps 10 \
  -w ./project \
  "Add input validation"

Fast prototyping:

perspt agent -y \
  --model gemini-3-flash \
  --stability-threshold 0.5 \
  "Create boilerplate"

Production-grade:

perspt agent \
  --architect-model gpt-5.2 \
  --actuator-model claude-opus-4.5 \
  --verifier-model gemini-3-pro \
  --energy-weights "2.0,1.0,3.0" \
  --stability-threshold 0.05 \
  --max-cost 10.0 \
  -w ./project \
  "Implement authentication system"

See Also