> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convoy Commands

> Multi-agent parallel orchestration commands

export const ThemedImage = ({light, dark, alt = ""}) => <>
    <img src={light} alt={alt} className="block dark:hidden" />
    <img src={dark ?? light} alt={alt} className="hidden dark:block" />
  </>;

# Convoy Commands

Orchestrate multiple agents working in parallel on related tasks.

## Overview

Convoys enable running multiple AI agents in parallel, combining their specialized expertise to tackle complex tasks more effectively. See the [Convoys feature guide](/features/convoys) for conceptual overview.

When several convoys (and ordinary work agents) run at once, the dashboard's **God View** gives you a single aggregate, cross-project picture of every active agent — so the conversations and the workflow stay observable side by side.

<ThemedImage light="/images/dashboard/god-view-light.png" dark="/images/dashboard/god-view-dark.png" alt="God View: aggregate cross-project view of all running agents and their live activity" />

<Tip>
  Use `pan convoy status` and `pan convoy list` for a per-convoy CLI view; reach for God View in the dashboard when you want to watch every parallel agent across all projects at a glance.
</Tip>

## pan convoy start

Start a new convoy with a specific template:

```bash theme={null}
# Run a parallel code review
pan convoy start code-review --files "src/**/*.ts"

# Use with pull request
pan convoy start code-review --pr-url https://github.com/org/repo/pull/123

# Target specific issue
pan convoy start code-review --issue-id MIN-123

# Specify project path
pan convoy start code-review --files "src/**/*.ts" --project-path /path/to/project
```

**Options:**

* `--files <pattern>` - File pattern to analyze (e.g., "src/\*\*/\*.ts")
* `--pr-url <url>` - Pull request URL to review
* `--issue-id <id>` - Issue ID to associate with convoy
* `--project-path <path>` - Project path (defaults to current directory)

## pan convoy status

Check the status of a running convoy:

```bash theme={null}
# Show most recent convoy status
pan convoy status

# Check specific convoy
pan convoy status <convoy-id>
```

The status command shows:

* Overall convoy state (running, completed, failed)
* Individual agent progress
* Phase completion (e.g., parallel review phase vs synthesis phase)
* Output files generated

## pan convoy list

List all convoys (running and completed):

```bash theme={null}
# List all convoys
pan convoy list

# Filter by status
pan convoy list --status running
pan convoy list --status completed
pan convoy list --status failed
```

## pan convoy stop

Stop a running convoy:

```bash theme={null}
pan convoy stop <convoy-id>
```

This will:

1. Kill all running agents in the convoy
2. Mark the convoy as failed
3. Preserve any output generated so far

## Built-in Convoy Templates

| Template         | Agents                                        | Use Case                          |
| ---------------- | --------------------------------------------- | --------------------------------- |
| `code-review`    | correctness, security, performance, synthesis | Comprehensive code review         |
| `planning`       | planner                                       | Codebase exploration and planning |
| `triage`         | (dynamic)                                     | Parallel issue triage             |
| `health-monitor` | monitor                                       | Check health of running agents    |

### code-review Template

The code-review convoy uses specialized agents for parallel review:

**Phase 1 - Specialized Reviews (Parallel)**

* **Correctness** (Haiku) - Logic errors, edge cases, type safety
* **Security** (Sonnet) - OWASP Top 10, injection, XSS, auth issues
* **Performance** (Haiku) - N+1 queries, blocking ops, memory leaks

**Phase 2 - Synthesis (Sequential)**

* Reads all three review files
* Removes duplicates (same issue found by multiple reviewers)
* Prioritizes findings (blocker → critical → high → medium → low)
* Generates unified report with action items

**Output files:**

* `.claude/reviews/<timestamp>-correctness.md`
* `.claude/reviews/<timestamp>-security.md`
* `.claude/reviews/<timestamp>-performance.md`
* `.claude/reviews/<timestamp>-synthesis.md`

## Custom Convoy Templates

Create custom templates in `~/.overdeck/convoy-templates/`:

```json theme={null}
{
  "name": "lightweight-review",
  "description": "Quick security-only review",
  "agents": [
    {
      "role": "security",
      "subagent": "code-review-security",
      "parallel": false
    }
  ],
  "config": {
    "outputDir": ".claude/reviews",
    "timeout": 600000
  }
}
```

Then use with:

```bash theme={null}
pan convoy start lightweight-review --files "src/**/*.ts"
```

## Convoy Execution Flow

```
pan convoy start code-review --files "src/**/*.ts"
    │
    ├─→ Phase 1 (Parallel): 3 specialized reviewers run simultaneously
    │     ├─→ Correctness (Haiku) → correctness.md
    │     ├─→ Security (Sonnet)    → security.md
    │     └─→ Performance (Haiku)  → performance.md
    │
    └─→ Phase 2 (Sequential): Synthesis agent runs after Phase 1 completes
          └─→ Synthesis reads all 3 reviews → synthesis.md
```

## Related Commands

* [pan work issue](/cli/agent-commands#pan-work-issue) - Spawn single work agent
* [pan cloister start](/cli/core-commands#pan-cloister-start) - Start AI lifecycle manager