Multi-Agent System - OpenAnalyst CLI Docs

Agent Types

💬

Primary Agent

The interactive conversational agent. Always one active, connected to your TUI or REPL.

🔍

Explore Agent

Fast, read-only codebase exploration. Uses search and file reading tools only.

📋

Plan Agent

Read-only architecture and design planning. Returns step-by-step implementation plans.

⚙

General Agent

Full-tool access general-purpose agent. Can read, write, execute, and search.

Sub-Agents

The primary agent can spawn sub-agents for parallel work. Each sub-agent has its own conversation runtime, tool permissions, and token budget.

# The agent tool spawns sub-agents automatically when needed.
# For example, when exploring a large codebase:
"Search for all API endpoints in this project"

# The agent may spawn an Explore sub-agent to search in parallel
# while continuing to work on the main task.

Agent Swarm

Use /swarm to decompose a complex task into parallel sub-tasks, each handled by a separate agent:

# Spawn multiple agents for parallel task execution
/swarm refactor all API handlers to use the new error type

The swarm:

Analyzes the task and decomposes it into independent sub-tasks
Spawns a dedicated agent for each sub-task
Runs all agents in parallel
Collects and synthesizes results

Autonomous Agent

The /openanalyst command runs a fully autonomous agent loop inspired by the Karpathy agentic pattern:

/openanalyst "add comprehensive error handling to the API module" --max-turns 20

The Loop: Think → Act → Observe → Verify

Think

The agent uses extended thinking (when available) to plan the next action. It considers the goal, current state, and what it has learned so far.

Act

Executes one or more tool calls: reading files, editing code, running commands, or searching.

Observe

Processes tool results and updates its understanding of the codebase state.

Verify

Self-checks whether the goal has been achieved. If not, loops back to Think. If verification criteria are provided, runs them.

Options

--goal <text> string Optional Explicit goal statement for the agent

--criteria <cmd> string Optional Shell command to verify success (exit code 0 = done)

--max-turns <n> number Optional Maximum loop iterations before stopping

Mixture of Experts (MOE)

For complex problems, the orchestrator can dispatch to multiple specialized agents simultaneously, each using a model best suited for their task type:

Agent Role	Optimized For	Example Model
Explorer	Fast codebase search	haiku / grok-mini
Planner	Architecture design	opus / gemini-2.5-pro
Coder	Code generation	sonnet / gpt-4o
Writer	Documentation	sonnet / gemini-2.5-flash

Smart Model Routing

The ModelRouter automatically selects the best model for each action type. Configure routing with:

# View the routing table
/route

# Set routing for a category
/route explore haiku
/route code sonnet
/route plan opus

Effort Budget

Control how much "thinking" the agent invests per category:

# Set global effort
/effort high

# Set per-category effort
/effort explore low
/effort plan max
/effort code medium

Level	Description
`low`	Minimal thinking, fast responses
`medium`	Balanced thinking and speed
`high`	More thorough reasoning
`max`	Extended thinking with full reasoning chains

Agent Lifecycle Events

The TUI displays real-time agent events:

AgentSpawned — New agent created with parent-child relationship
AgentStatusChanged — Pending → Running → Completed/Failed
AgentCompleted — Agent finished with result summary
AgentFailed — Agent encountered an error