---

Lead. Delegate. Dominate.

Praetor is a Go CLI for agent orchestration with a strict Plan-and-Execute runtime. It orchestrates 9 AI agent providers through a single execution surface with dependency-aware plans, isolated worktrees, independent review gates, snapshot-based recovery, and structured observability.

Documentation • Releases • Quick Start

Why Praetor

• One CLI surface for planning, execution, review, and recovery.
• Unified provider abstraction across 9 CLI and REST agents.
• Explicit finite-state orchestration with transition guard rails.
• Worktree-first isolation to protect the main branch during task execution.
• Automatic fallback with error-classified failover to alternate agents.
• Middleware pipeline with composable logging and metrics.
• Structured observability via JSONL event stream and diagnostics.
• Local transactional snapshots with checksum validation and explicit resume.

Core Capabilities

• Plan execution — run JSON plans with dependencies via praetor plan run.
• Plan templates — bootstrap plans from project, global, or builtin templates with praetor plan create --from-template, then package them with praetor plan export.
• Agents — 9 built-in providers: claude, codex, copilot, gemini, kimi, lmstudio, opencode, openrouter, and ollama.
• Plan-and-Execute — optional planner phase (--objective) followed by execute/review gates.
• FSM runtime — loop modeled as explicit states with max-iterations and max-transitions guard rails.
• Runner modes — tmux, direct, and pty under a unified runtime contract.
• Fallback engine — error-classified failover: per-agent mapping, transient, and auth fallback modes.
• Stall detection — sliding-window similarity detection with escalation (fallback agent → budget reduction → fail).
• Prompt budget — character-level prompt truncation for executor and reviewer phases.
• Cost governance — plan/task USD budgets with warnings, summaries, and optional hard enforcement.
• Parallel waves — dependency-aware concurrent task execution (default: 5 parallel) with deterministic merge ordering and conflict requeue.
• Intelligent routing — live health-probe-based auto-selection when the preferred agent is unavailable.
• Quality gates — required and optional gate enforcement in plan execution.
• Host-executed gates — tests, lint, standards run locally with structured results and diagnostics.
• Operational evals — local flow analysis via praetor plan eval (plan level) and praetor eval (project level).
• Workspace context — automatic manifest discovery from praetor.yaml / praetor.md.
• Prompt templates — 8 embedded templates with project-level overlay via .praetor/prompts/.
• Structured feedback — reviewer and gate feedback persisted as JSONL and reinjected into retry prompts.
• Post-task hooks — arbitrary script execution after executor, before reviewer (--hook).
• Recovery — automatic snapshot inspection plus manual praetor plan resume.
• Retention — local runtime pruning with --keep-last-runs.
• Observability — JSONL event stream, performance diagnostics, checkpoint history, cost ledger, actor summaries, and per-task logs.
• Health checks — praetor doctor returns structured checks, binary/endpoint paths, parsed versions, and remediation hints.
• Configuration — persistent config with praetor config (show, set, path, edit, init).

Providers

Provider	Transport	TTY	Structured Output
Claude	CLI	yes	yes
Codex	CLI	no	yes
Copilot	CLI	no	no
Gemini	CLI	yes	no
Kimi	CLI	yes	no
OpenCode	CLI	no	no
OpenRouter	REST	no	yes
LM Studio	REST	no	yes
Ollama	REST	no	no

Requirements

• Linux or macOS.
• Go 1.26+.
• git available in PATH.
• For --runner tmux: tmux installed.
• CLI agent binaries as needed: codex, claude, copilot, gemini, kimi, opencode.
• For OpenRouter: OPENROUTER_API_KEY env var set.
• For LM Studio: reachable REST endpoint (default http://localhost:1234).
• For Ollama: reachable REST endpoint (default http://127.0.0.1:11434).

Quick Start

Install

go install github.com/opus-domini/praetor/cmd/praetor@latest

Or build locally

make build
./build/praetor --help

Install praetor into your project

# Interactive agent selector in TTY, auto-detect otherwise
praetor init

Check agent availability

praetor doctor

Create and run a plan

# Create a plan from a brief (agent-assisted by default)
praetor plan create "Implement JWT auth with tests and docs"

# Or use the interactive wizard in a TTY to probe available providers and choose planner/executor/reviewer first
praetor plan create

# Or render a reusable template from project/global/builtin registry
praetor plan create --from-template feature \
  --var Name=auth \
  --var Summary="Implement JWT auth"

# Run plan (default runner: tmux)
praetor plan run implement-jwt-auth-with-tests-and-docs

Run with cost guard rails

praetor plan run my-plan \
  --runner direct \
  --executor codex \
  --reviewer claude \
  --plan-cost-budget-usd 5 \
  --task-cost-budget-usd 1 \
  --max-retries 3 \
  --max-transitions 200

Run with fallback

praetor plan run my-plan \
  --fallback-on-transient ollama \
  --fallback-on-auth openrouter

Check status and resume

praetor plan status my-plan --verbose
praetor plan status my-plan
praetor plan list
praetor plan resume my-plan

Export a plan bundle

praetor plan export my-plan
praetor plan export my-plan --output ./.praetor/exports/my-plan --force

Diagnose a run

praetor plan diagnose my-plan
praetor plan diagnose my-plan --query errors --format json
praetor plan diagnose my-plan --query summary

Evaluate quality (local)

praetor plan eval my-plan
praetor plan eval my-plan --run-id <run-id> --format json
praetor eval
praetor eval --window 168h --format json
make eval-plan PLAN_SLUG=my-plan
make eval

Single prompt mode

praetor exec "Reply with OK"
praetor exec --provider claude "Summarize this diff"
praetor exec --provider ollama --model llama3 "Explain this module"
praetor exec --provider openrouter --model anthropic/claude-sonnet-4 "Review this code"

Command Overview

Command	Description
praetor plan run <slug>	Execute orchestration pipeline
praetor plan create [brief]	Create a plan from text/markdown input
praetor plan export <slug>	Export plan, state, summary, and reusable template
praetor plan status <slug>	Inspect state and progress
praetor plan list	List tracked plans for current project
praetor plan show <slug>	Print plan JSON to stdout
praetor plan path <slug>	Print absolute plan file path
praetor plan edit <slug>	Open a plan in $EDITOR
praetor plan reset <slug>	Clear runtime state for one plan
praetor plan resume <slug>	Restore latest valid local snapshot
praetor plan diagnose <slug>	Inspect structured diagnostics
praetor plan eval <slug>	Evaluate one local plan run (acceptance, gates, parse errors, stalls, retries, cost)
praetor eval	Aggregate latest local plan evaluations at project level
praetor exec [prompt]	Run a single prompt against one provider
praetor doctor	Check agent availability and health
praetor config show	Show effective config with source annotations
praetor config set <key> <value>	Persist a configuration key
praetor config path	Print resolved config file path
praetor config edit	Open config in $EDITOR
praetor config init	Create a commented template config file
praetor init	Install praetor into the current project
praetor mcp	Start MCP server over stdio

Configuration and State

• Config file: $PRAETOR_CONFIG > <praetor-home>/config.toml (TOML format).
• Config cascade: built-in defaults < global config < project section < plan settings < CLI flags.
• Home directory: $PRAETOR_HOME > $XDG_CONFIG_HOME/praetor > ~/.praetor.
• All state is isolated per git project under <home>/projects/<project-key>/.
• Plans are identified by slug and stored in <project>/plans/<slug>.json.
• Plan templates are resolved from <project-root>/.praetor/templates/, <praetor-home>/templates/, then builtin templates.
• Builtin templates are software-engineering oriented: feature, bug-fix, refactor, discovery, implementation, validation, and release.
• Plan briefs are persisted under <project>/briefs/ before agent generation (never lost on failure).
• Structured feedback and runtime artifacts live under <project>/feedback/<slug>/ and <project>/runtime/<run-id>/.
• Manifest discovery order: praetor.yaml > praetor.yml > praetor.md.

Documentation

• Documentation Home
• Architecture
• Pipeline Orchestration
• Configuration
• MCP Server
• Shared Agent Commands
• Operations Runbook
• Providers Overview
• Claude Provider
• Codex Provider
• Copilot Provider
• Gemini Provider
• Kimi Provider
• LM Studio Provider
• OpenCode Provider
• OpenRouter Provider
• Ollama Provider

Development

make fmt              # Format code
make lint             # Lint code
make test             # Run tests
make test-coverage    # Run tests with race detection + coverage
make benchmark        # Run benchmarks
make security         # Run govulncheck
make ci               # Full CI pipeline (fmt + lint + test + coverage + benchmark + security)

Stargazers over time ⭐