{"id":46784222,"url":"https://github.com/opus-domini/praetor","last_synced_at":"2026-03-10T01:07:55.233Z","repository":{"id":341205429,"uuid":"1166804820","full_name":"opus-domini/praetor","owner":"opus-domini","description":"One CLI to plan, execute, and review! AI agents with FSM-driven orchestration.","archived":false,"fork":false,"pushed_at":"2026-03-09T12:59:44.000Z","size":1021,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T17:41:50.503Z","etag":null,"topics":["ai-agents","automation","cli","code-generation","devtools","fsm","golang","multi-agent","orchestration","plan-and-execute"],"latest_commit_sha":null,"homepage":"https://opus-domini.github.io/praetor/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opus-domini.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"hugo-andrade"}},"created_at":"2026-02-25T16:18:00.000Z","updated_at":"2026-03-09T12:59:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/opus-domini/praetor","commit_stats":null,"previous_names":["opus-domini/praetor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/opus-domini/praetor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opus-domini%2Fpraetor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opus-domini%2Fpraetor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opus-domini%2Fpraetor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opus-domini%2Fpraetor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opus-domini","download_url":"https://codeload.github.com/opus-domini/praetor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opus-domini%2Fpraetor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30320536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","cli","code-generation","devtools","fsm","golang","multi-agent","orchestration","plan-and-execute"],"created_at":"2026-03-10T01:07:54.703Z","updated_at":"2026-03-10T01:07:55.211Z","avatar_url":"https://github.com/opus-domini.png","language":"Go","funding_links":["https://github.com/sponsors/hugo-andrade"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"docs/assets/images/logo.svg\" alt=\"Praetor logo\" width=\"500\"/\u003e\n    \u003chr /\u003e\n    \u003cp\u003e\u003cstrong\u003eLead. Delegate. Dominate.\u003c/strong\u003e\u003c/p\u003e\n    \u003cp\u003e\n        \u003ca href=\"https://goreportcard.com/report/github.com/opus-domini/praetor\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/opus-domini/praetor\" alt=\"Go Report Badge\"\u003e\u003c/a\u003e\n        \u003ca href=\"https://pkg.go.dev/github.com/opus-domini/praetor\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/opus-domini/praetor.svg\" alt=\"Go Package Docs Badge\"\u003e\u003c/a\u003e\n        \u003ca href=\"https://github.com/opus-domini/praetor/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/opus-domini/praetor/actions/workflows/ci.yml/badge.svg\" alt=\"CI Badge\"\u003e\u003c/a\u003e\n        \u003ca href=\"https://github.com/opus-domini/praetor/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/opus-domini/praetor\" alt=\"Release Badge\"\u003e\u003c/a\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\nPraetor is a Go CLI for agent orchestration with a strict Plan-and-Execute runtime.\nIt 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.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opus-domini.github.io/praetor/\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"https://github.com/opus-domini/praetor/releases\"\u003eReleases\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\n\u003c/p\u003e\n\n## Why Praetor\n\n- One CLI surface for planning, execution, review, and recovery.\n- Unified provider abstraction across 9 CLI and REST agents.\n- Explicit finite-state orchestration with transition guard rails.\n- Worktree-first isolation to protect the main branch during task execution.\n- Automatic fallback with error-classified failover to alternate agents.\n- Middleware pipeline with composable logging and metrics.\n- Structured observability via JSONL event stream and diagnostics.\n- Local transactional snapshots with checksum validation and explicit resume.\n\n## Core Capabilities\n\n- **Plan execution** — run JSON plans with dependencies via `praetor plan run`.\n- **Plan templates** — bootstrap plans from project, global, or builtin templates with `praetor plan create --from-template`, then package them with `praetor plan export`.\n- **Agents** — 9 built-in providers: `claude`, `codex`, `copilot`, `gemini`, `kimi`, `lmstudio`, `opencode`, `openrouter`, and `ollama`.\n- **Plan-and-Execute** — optional planner phase (`--objective`) followed by execute/review gates.\n- **FSM runtime** — loop modeled as explicit states with `max-iterations` and `max-transitions` guard rails.\n- **Runner modes** — `tmux`, `direct`, and `pty` under a unified runtime contract.\n- **Fallback engine** — error-classified failover: per-agent mapping, transient, and auth fallback modes.\n- **Stall detection** — sliding-window similarity detection with escalation (fallback agent → budget reduction → fail).\n- **Prompt budget** — character-level prompt truncation for executor and reviewer phases.\n- **Cost governance** — plan/task USD budgets with warnings, summaries, and optional hard enforcement.\n- **Parallel waves** — dependency-aware concurrent task execution (default: 5 parallel) with deterministic merge ordering and conflict requeue.\n- **Intelligent routing** — live health-probe-based auto-selection when the preferred agent is unavailable.\n- **Quality gates** — required and optional gate enforcement in plan execution.\n- **Host-executed gates** — `tests`, `lint`, `standards` run locally with structured results and diagnostics.\n- **Operational evals** — local flow analysis via `praetor plan eval` (plan level) and `praetor eval` (project level).\n- **Workspace context** — automatic manifest discovery from `praetor.yaml` / `praetor.md`.\n- **Prompt templates** — 8 embedded templates with project-level overlay via `.praetor/prompts/`.\n- **Structured feedback** — reviewer and gate feedback persisted as JSONL and reinjected into retry prompts.\n- **Post-task hooks** — arbitrary script execution after executor, before reviewer (`--hook`).\n- **Recovery** — automatic snapshot inspection plus manual `praetor plan resume`.\n- **Retention** — local runtime pruning with `--keep-last-runs`.\n- **Observability** — JSONL event stream, performance diagnostics, checkpoint history, cost ledger, actor summaries, and per-task logs.\n- **Health checks** — `praetor doctor` returns structured checks, binary/endpoint paths, parsed versions, and remediation hints.\n- **Configuration** — persistent config with `praetor config` (show, set, path, edit, init).\n\n## Providers\n\n| Provider | Transport | TTY | Structured Output |\n|---|---|---|---|\n| Claude | CLI | yes | yes |\n| Codex | CLI | no | yes |\n| Copilot | CLI | no | no |\n| Gemini | CLI | yes | no |\n| Kimi | CLI | yes | no |\n| OpenCode | CLI | no | no |\n| OpenRouter | REST | no | yes |\n| LM Studio | REST | no | yes |\n| Ollama | REST | no | no |\n\n## Requirements\n\n- Linux or macOS.\n- Go 1.26+.\n- `git` available in `PATH`.\n- For `--runner tmux`: `tmux` installed.\n- CLI agent binaries as needed: `codex`, `claude`, `copilot`, `gemini`, `kimi`, `opencode`.\n- For OpenRouter: `OPENROUTER_API_KEY` env var set.\n- For LM Studio: reachable REST endpoint (default `http://localhost:1234`).\n- For Ollama: reachable REST endpoint (default `http://127.0.0.1:11434`).\n\n## Quick Start\n\n### Install\n\n```bash\ngo install github.com/opus-domini/praetor/cmd/praetor@latest\n```\n\n### Or build locally\n\n```bash\nmake build\n./build/praetor --help\n```\n\n### Install praetor into your project\n\n```bash\n# Interactive agent selector in TTY, auto-detect otherwise\npraetor init\n```\n\n### Check agent availability\n\n```bash\npraetor doctor\n```\n\n### Create and run a plan\n\n```bash\n# Create a plan from a brief (agent-assisted by default)\npraetor plan create \"Implement JWT auth with tests and docs\"\n\n# Or use the interactive wizard in a TTY to probe available providers and choose planner/executor/reviewer first\npraetor plan create\n\n# Or render a reusable template from project/global/builtin registry\npraetor plan create --from-template feature \\\n  --var Name=auth \\\n  --var Summary=\"Implement JWT auth\"\n\n# Run plan (default runner: tmux)\npraetor plan run implement-jwt-auth-with-tests-and-docs\n```\n\n### Run with cost guard rails\n\n```bash\npraetor plan run my-plan \\\n  --runner direct \\\n  --executor codex \\\n  --reviewer claude \\\n  --plan-cost-budget-usd 5 \\\n  --task-cost-budget-usd 1 \\\n  --max-retries 3 \\\n  --max-transitions 200\n```\n\n### Run with fallback\n\n```bash\npraetor plan run my-plan \\\n  --fallback-on-transient ollama \\\n  --fallback-on-auth openrouter\n```\n\n### Check status and resume\n\n```bash\npraetor plan status my-plan --verbose\npraetor plan status my-plan\npraetor plan list\npraetor plan resume my-plan\n```\n\n### Export a plan bundle\n\n```bash\npraetor plan export my-plan\npraetor plan export my-plan --output ./.praetor/exports/my-plan --force\n```\n\n### Diagnose a run\n\n```bash\npraetor plan diagnose my-plan\npraetor plan diagnose my-plan --query errors --format json\npraetor plan diagnose my-plan --query summary\n```\n\n### Evaluate quality (local)\n\n```bash\npraetor plan eval my-plan\npraetor plan eval my-plan --run-id \u003crun-id\u003e --format json\npraetor eval\npraetor eval --window 168h --format json\nmake eval-plan PLAN_SLUG=my-plan\nmake eval\n```\n\n### Single prompt mode\n\n```bash\npraetor exec \"Reply with OK\"\npraetor exec --provider claude \"Summarize this diff\"\npraetor exec --provider ollama --model llama3 \"Explain this module\"\npraetor exec --provider openrouter --model anthropic/claude-sonnet-4 \"Review this code\"\n```\n\n## Command Overview\n\n| Command | Description |\n|---|---|\n| `praetor plan run \u003cslug\u003e` | Execute orchestration pipeline |\n| `praetor plan create [brief]` | Create a plan from text/markdown input |\n| `praetor plan export \u003cslug\u003e` | Export plan, state, summary, and reusable template |\n| `praetor plan status \u003cslug\u003e` | Inspect state and progress |\n| `praetor plan list` | List tracked plans for current project |\n| `praetor plan show \u003cslug\u003e` | Print plan JSON to stdout |\n| `praetor plan path \u003cslug\u003e` | Print absolute plan file path |\n| `praetor plan edit \u003cslug\u003e` | Open a plan in `$EDITOR` |\n| `praetor plan reset \u003cslug\u003e` | Clear runtime state for one plan |\n| `praetor plan resume \u003cslug\u003e` | Restore latest valid local snapshot |\n| `praetor plan diagnose \u003cslug\u003e` | Inspect structured diagnostics |\n| `praetor plan eval \u003cslug\u003e` | Evaluate one local plan run (acceptance, gates, parse errors, stalls, retries, cost) |\n| `praetor eval` | Aggregate latest local plan evaluations at project level |\n| `praetor exec [prompt]` | Run a single prompt against one provider |\n| `praetor doctor` | Check agent availability and health |\n| `praetor config show` | Show effective config with source annotations |\n| `praetor config set \u003ckey\u003e \u003cvalue\u003e` | Persist a configuration key |\n| `praetor config path` | Print resolved config file path |\n| `praetor config edit` | Open config in `$EDITOR` |\n| `praetor config init` | Create a commented template config file |\n| `praetor init` | Install praetor into the current project |\n| `praetor mcp` | Start MCP server over stdio |\n\n## Configuration and State\n\n- Config file: `$PRAETOR_CONFIG` \u003e `\u003cpraetor-home\u003e/config.toml` (TOML format).\n- Config cascade: built-in defaults \u003c global config \u003c project section \u003c plan settings \u003c CLI flags.\n- Home directory: `$PRAETOR_HOME` \u003e `$XDG_CONFIG_HOME/praetor` \u003e `~/.config/praetor`.\n- All state is isolated per git project under `\u003chome\u003e/projects/\u003cproject-key\u003e/`.\n- Plans are identified by slug and stored in `\u003cproject\u003e/plans/\u003cslug\u003e.json`.\n- Plan templates are resolved from `\u003cproject-root\u003e/.praetor/templates/`, `\u003cpraetor-home\u003e/templates/`, then builtin templates.\n- Builtin templates are software-engineering oriented: `feature`, `bug-fix`, `refactor`, `discovery`, `implementation`, `validation`, and `release`.\n- Plan briefs are persisted under `\u003cproject\u003e/briefs/` before agent generation (never lost on failure).\n- Structured feedback and runtime artifacts live under `\u003cproject\u003e/feedback/\u003cslug\u003e/` and `\u003cproject\u003e/runtime/\u003crun-id\u003e/`.\n- Manifest discovery order: `praetor.yaml` \u003e `praetor.yml` \u003e `praetor.md`.\n\n## Documentation\n\n- [Documentation Home](https://opus-domini.github.io/praetor/#/)\n- [Architecture](https://opus-domini.github.io/praetor/#/architecture)\n- [Pipeline Orchestration](https://opus-domini.github.io/praetor/#/orchestration)\n- [Configuration](https://opus-domini.github.io/praetor/#/configuration)\n- [MCP Server](https://opus-domini.github.io/praetor/#/mcp)\n- [Shared Agent Commands](https://opus-domini.github.io/praetor/#/commands)\n- [Operations Runbook](https://opus-domini.github.io/praetor/#/operations-runbook)\n- [Providers Overview](https://opus-domini.github.io/praetor/#/providers/README)\n- [Claude Provider](https://opus-domini.github.io/praetor/#/providers/claude)\n- [Codex Provider](https://opus-domini.github.io/praetor/#/providers/codex)\n- [Copilot Provider](https://opus-domini.github.io/praetor/#/providers/copilot)\n- [Gemini Provider](https://opus-domini.github.io/praetor/#/providers/gemini)\n- [Kimi Provider](https://opus-domini.github.io/praetor/#/providers/kimi)\n- [LM Studio Provider](https://opus-domini.github.io/praetor/#/providers/lmstudio)\n- [OpenCode Provider](https://opus-domini.github.io/praetor/#/providers/opencode)\n- [OpenRouter Provider](https://opus-domini.github.io/praetor/#/providers/openrouter)\n- [Ollama Provider](https://opus-domini.github.io/praetor/#/providers/ollama)\n\n## Development\n\n```bash\nmake fmt              # Format code\nmake lint             # Lint code\nmake test             # Run tests\nmake test-coverage    # Run tests with race detection + coverage\nmake benchmark        # Run benchmarks\nmake security         # Run govulncheck\nmake ci               # Full CI pipeline (fmt + lint + test + coverage + benchmark + security)\n```\n\n## Stargazers over time ⭐\n\n[![Stargazers over time](https://starchart.cc/opus-domini/praetor.svg?variant=adaptive)](https://starchart.cc/opus-domini/praetor)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopus-domini%2Fpraetor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopus-domini%2Fpraetor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopus-domini%2Fpraetor/lists"}