This chapter covers how to run multiple PVYai agents together against a shared plan — from simple parallel delegation to full swarm orchestration with worktree isolation.
| Scenario | Single agent | Multi-agent |
|---|---|---|
| Quick edit (1 file) | ✓ | — |
| Multi-step task with clear plan | ✓ (with update_plan) |
— |
| Feature with 3+ independent subtasks | — | ✓ |
| Need exploration + implementation + review | — | ✓ |
| Parallel work on different parts of a codebase | — | ✓ |
| Large refactor requiring isolation | — | ✓ (worktrees) |
| Long-running tasks while you continue coding | — | ✓ (background) |
Best for: Large refactors with clear scope, compliance trails
This is the simplest pattern — a single agent, guided by an approved spec.
Step 1: /spec "Implement the authentication module with JWT tokens"
↓
Agent drafts spec (read-only)
↓
Step 2: Review spec → approve
↓
Step 3: Agent implements the spec
↓
Uses update_plan to track progress
↓
Step 4: Verify with tests
# In the TUI:
/spec Add a rate-limiting middleware to the API server
# Agent explores the codebase (read-only) and writes a spec
# Review the spec:
# [a] approve [r] reject [e] edit [esc] cancel
# After approval, the agent implements it with full tool access
# Watch the plan panel fill in as it works
# When done, verify:
/bash go test ./internal/middleware/...
| Pro | Con |
|---|---|
| Scope control | Sequential — no parallelism |
| Review checkpoint | One model, one pace |
| Spec as documentation | Overhead for small tasks |
Best for: Independent subtasks, exploration + implementation + review
Spawn multiple specialists in parallel, each handling a focused subtask.
@explorer map the auth module and list all files
@explorer find all API endpoints without rate limiting
@code-review review the last 5 commits for security issues
@worker implement rate limiting middleware in internal/middleware/rate_limit.go
User: "Add rate limiting to the API. I need:
1. Exploration of current middleware setup
2. Implementation of the rate limiter
3. Code review of the implementation"
Agent:
# Phase 1: Explore in parallel
Task(name="explorer", prompt="Map the current middleware setup and list all API routes")
Task(name="explorer", prompt="Find existing rate limiting or throttling code")
# Phase 2: Implement (after exploration)
Task(name="worker", prompt="Implement a token bucket rate limiter in internal/middleware/rate_limit.go based on the exploration findings")
# Phase 3: Review
Task(name="code-review", prompt="Review the rate limiting implementation for correctness, performance, and security")
# Synthesize all results
→ Report: implementation complete, review passed with 2 minor notes
| Pro | Con |
|---|---|
| Parallelism for independent tasks | No inter-agent communication |
| Read-only exploration auto-approved | Sequential when tasks depend on each other |
| Specialized tools per agent | Context overhead (each agent starts fresh) |
Best for: Multi-member teams, tasks requiring communication, pipeline workflows
Use swarm tools when you need agents to communicate with each other via mailboxes, hand off tasks between agent types, or run a pipeline.
User: "Implement a new user onboarding flow — backend API + frontend page"
Agent (orchestrator):
# Spawn backend and frontend teams in parallel
swarm_spawn(team="backend", agent_type="worker",
task="Implement POST /api/users/onboarding endpoint")
swarm_spawn(team="frontend", agent_type="worker",
task="Build the onboarding page UI")
# Frontend needs the API schema before it can proceed
# Backend sends the schema via mailbox when ready
swarm_send(to="frontend-worker", team="frontend",
subject="API schema ready",
body="POST /api/users/onboarding expects {userId, step} and returns {nextStep, formData}")
# Wait for both teams to finish
backend_results = swarm_collect(team="backend")
frontend_results = swarm_collect(team="frontend")
# Hand off to code review
swarm_handoff(task_id=backend_results[0].id,
to_agent_type="code-review",
note="Review the onboarding API for security and validation")
review = swarm_collect(team="backend")
→ Report: backend + frontend + review complete
Agent:
swarm_schedule(agent_type="worker",
task="Run go test ./... and report any failures with the test name and error message",
team="ci",
every="30m")
| Pro | Con |
|---|---|
| Inter-agent communication via mailboxes | More complex to set up |
| Team management with bounded slots | Orchestrator consumes context coordinating |
| Handoffs between agent types | Mailbox overhead (disk I/O) |
| Scheduled recurring swarms | Not for simple tasks |
Best for: Parallel work without interference, multi-branch experiments
Each agent runs in its own git worktree — a detached HEAD copy of the repo. Agents can make changes without affecting each other or your working tree.
# Terminal 1: Refactor the auth module
cd /path/to/repo
pvyai exec -w refactor-auth "Refactor internal/auth/ to use interfaces instead of concrete types"
# Terminal 2: Add tests to the database layer (concurrent)
cd /path/to/repo
pvyai exec -w add-db-tests "Add comprehensive integration tests for internal/db/"
# Terminal 3: Continue working on your feature (unaffected)
cd /path/to/repo
pvyai
Each worktree is at ~/.local/state/pvyai/worktrees/pvyai-worktree-<repo>/<name>/:
# Check on the auth refactoring
cd ~/.local/state/pvyai/worktrees/pvyai-worktree-myrepo/refactor-auth
git log --oneline -5
go test ./internal/auth/...
# Merge the results back
cd /path/to/repo
git cherry-pick <commits from worktree>
| Pro | Con |
|---|---|
| Zero interference between agents | Manual merge required |
| Each agent has full repo context | Disk space for each worktree |
| Can run truly concurrent | No inter-agent communication |
1. /spec "Implement the new API layer"
→ Agent drafts spec, you approve
2. Implementation agent spawns parallel specialists:
Task(name="worker", prompt="Implement the routes")
Task(name="worker", prompt="Implement the handlers")
Task(name="explorer", prompt="Find all places that need updating")
3. Code review specialist reviews the result
Task(name="code-review", prompt="Review the implementation against the spec")
# Create an isolated worktree for the swarm
pvyai worktrees prepare --name feature-team
# Run the swarm in the worktree
cd ~/.local/state/pvyai/worktrees/pvyai-worktree-<repo>/feature-team
pvyai
# Inside the TUI, the agent spawns swarm members that all work in this worktree
# Schedule a nightly eval run
pvyai cron add "0 2 * * *" --prompt "Run pvyai eval bench --suite evals/regression.json --agent-command 'pvyai exec --cwd {workspace} {prompt}' --report-dir /tmp/nightly-evals and report any failures"
| Surface | What it shows |
|---|---|
| Sidebar → SPECIALISTS | Running agents with spinners and live progress |
| Specialist cards (transcript) | Status, tool calls, tokens, elapsed time |
| Summary line | Total/running/completed/error counts + total tokens |
/ps |
List all running tasks |
/context |
Token usage breakdown |
Click a specialist card (or press Enter) to open the member’s child session. You can see its full conversation, tool calls, and results.
# List all sessions (including specialist child sessions)
pvyai sessions
# Search for specialist sessions
pvyai search "specialist"
# Resume a specialist session
pvyai exec --resume <session-id> "continue"
Every spawned agent (specialist or swarm member) inherits the orchestrator’s permission mode, clamped to never exceed it:
| Orchestrator mode | Agent autonomy |
|---|---|
ask |
auto low (read-only auto-approve, prompts for writes) |
auto |
auto low (same) |
unsafe |
auto high (full auto-approve) |
This means: if you’re in ask mode and spawn a @worker (which has edit + execute tools), the worker will still prompt for write/exec approval — it doesn’t inherit your auto escalation.
Specialists with only read-only tools are auto-approved — no permission prompt. This is ideal for exploration and review:
@explorer find the auth logic ← no prompt, just runs
@code-review review last 3 commits ← no prompt, just runs
@worker implement the feature ← prompts for write/exec
Each specialist/swarm member has its own token budget. The orchestrator’s context budget doesn’t include member tokens — but the summary line shows the total:
3 specialists · 2 running · 1 completed · 12.5k tokens total
| Setting | Default | How to change |
|---|---|---|
maxTurns (orchestrator) |
50 | config.json or --max-turns or /turns |
maxTurns (specialist) |
Inherits from parent | Set in specialist manifest |
Swarm maxTeamSize |
8 | config.json → swarm.maxTeamSize |
# In the TUI
/context # Current context budget
/ps # Running agents + their token counts
# From the CLI
pvyai exec --model claude-haiku-4.5 "quick fix" # Use a cheaper model for simple tasks
| Practice | Why |
|---|---|
Start with /spec for large tasks |
Scope control before delegation |
Use update_plan for tracking |
The plan panel shows live progress |
| Break tasks into independent units | Enables parallel delegation |
| Keep tasks self-contained | Each agent starts with zero context |
| Practice | Why |
|---|---|
Use @explorer for read-only exploration |
Auto-approved, no prompts, parallel |
Use @code-review after implementation |
Clean separation of concerns |
Run @worker in background for long tasks |
You continue coding while it runs |
Use swarm_collect instead of polling |
One call, no retry loops |
| Limit team size based on model cost | More members = more concurrent cost |
| Practice | Why |
|---|---|
| Use worktrees for parallel work | Zero interference between agents |
Use swarm for communicating teams |
Mailbox-based communication |
Use /spec for scope isolation |
Read-only draft phase prevents premature edits |
| Practice | Why |
|---|---|
| Watch the sidebar for specialist status | Live progress at a glance |
Check /ps for running tasks |
See all active agents |
| Drill into specialist cards | See what each agent is doing |
| Review session lineage after the run | Audit trail of all agent actions |
| If your task… | Use this pattern |
|---|---|
| Is small and single-file | Single agent (no delegation) |
| Has a clear multi-step plan | Single agent with update_plan |
| Needs review before implementation | /spec → approve → implement |
| Has 2-3 independent subtasks | Parallel specialists (@explorer, @worker, @code-review) |
| Requires inter-agent communication | Swarm with mailboxes |
| Needs scheduled recurring work | Swarm swarm_schedule or cron loops |
| Has multiple agents on the same repo | Worktree isolation |
| Is a pipeline (implement → review → deploy) | Swarm with handoffs |
| Needs to run while you continue coding | Background specialists |
| Is experimental and might be discarded | Worktree isolation |
Here’s a complete workflow combining spec mode, parallel specialists, and code review:
# Step 1: Draft a spec
/spec Implement a new notification system with:
- Email notifications via SMTP
- In-app notifications via WebSocket
- A notification preferences page
- Admin controls for bulk sending
# Step 2: Review and approve the spec
# [a] approve
# Step 3: The implementation agent spawns parallel work
# (The agent does this autonomously based on the spec)
# Explore the existing codebase
Task(name="explorer", prompt="Map the existing email and WebSocket infrastructure")
Task(name="explorer", prompt="Find the user preferences system and its database schema")
# Implement in parallel
Task(name="worker", prompt="Implement the email notification service in internal/notify/email.go")
Task(name="worker", prompt="Implement the WebSocket notification service in internal/notify/ws.go")
Task(name="worker", prompt="Build the preferences page UI in web/settings/notifications.html")
# Wait for implementation
# (agent collects results)
# Review
Task(name="code-review", prompt="Review the notification implementation for:
1. Security (SMTP injection, XSS in WebSocket messages)
2. Performance (connection pooling, batching)
3. Error handling (retry logic, dead letter queue)
4. Test coverage")
# Agent synthesizes all results and reports
→ "Implementation complete. 3 services implemented, 1 review with 2 minor notes."
# Step 4: Verify
/bash go test ./internal/notify/...
# Step 5: Check the plan
/plan
# Shows all steps as completed
/spec and update_plan