Multi-Agent Workflows

Overview

profClaw supports spawning multiple agent sessions that work in parallel, each with their own context, tools, and objectives. This enables complex workflows like researching multiple topics simultaneously, running parallel code reviews, or coordinating development tasks.

Spawning Sessions

Use the sessions-spawn tool to create parallel agent sessions:

profclaw agent spawn \
  --count 3 \
  --task "Review the authentication module for security issues" \
  --task "Check test coverage for the API routes" \
  --task "Audit environment variable usage"

Session Architecture

Each spawned session:

Gets its own execution context and tool access
Runs independently and in parallel
Can use all available tools (subject to security policy)
Reports results back to the parent session
Has configurable timeout via POOL_TIMEOUT_MS

Parent Session
├── Child Session 1 (security review)
├── Child Session 2 (test coverage)
└── Child Session 3 (env var audit)

API Usage

Spawn sessions via the REST API:

curl -X POST http://localhost:3000/api/agents/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [
      {
        "task": "Review auth module for vulnerabilities",
        "provider": "anthropic",
        "model": "claude-sonnet-4-6",
        "tools": ["read_file", "grep", "glob"]
      },
      {
        "task": "Check test coverage",
        "provider": "anthropic",
        "tools": ["read_file", "test_run", "glob"]
      }
    ],
    "timeout": 300000
  }'

Concurrency Limits

Mode	Max Concurrent Sessions
Pico	2
Mini	10
Pro	50+

Configure via:

export POOL_MAX_CONCURRENT=25

Patterns

Fan-Out / Fan-In

Distribute work across multiple agents, then aggregate results:

Parent receives complex task
Decomposes into subtasks
Spawns N child sessions (fan-out)
Children work in parallel
Parent collects all results (fan-in)
Parent synthesizes final answer

Pipeline

Chain agents where each builds on the previous result:

Agent 1: Research → Agent 2: Plan → Agent 3: Implement → Agent 4: Review

Specialist Teams

Different agents with different provider/model configurations:

# Fast agent for search and exploration
- provider: groq
  model: llama-3.3-70b
  task: "Find all API endpoints"

# Powerful agent for analysis
- provider: anthropic
  model: claude-sonnet-4-6
  task: "Analyze the codebase architecture"

Resource Management

Each session consumes API tokens from the configured provider. Monitor costs with profclaw cost when running many parallel sessions.

# Check active sessions
profclaw agent sessions

# View cost breakdown
profclaw cost --today

​Overview

​Spawning Sessions

​Session Architecture

​API Usage

​Concurrency Limits

​Patterns

​Fan-Out / Fan-In

​Pipeline

​Specialist Teams

​Resource Management

Overview

Spawning Sessions

Session Architecture

API Usage

Concurrency Limits

Patterns

Fan-Out / Fan-In

Pipeline

Specialist Teams

Resource Management