pragmatic-orchestration is a field-tested system for orchestrating coding agents across vendors. Its cross-agent skill turns any skill-capable harness into an orchestrator: Codex, Claude Code, Cursor, OpenCode, and others can call external agents through the porch CLI.
Click the demo to watch the MP4. Illustrative workflow: Codex spots a deviation and redirects Devin while the task is running.
In field use, frontier models such as Astra and Fable cover roughly 2–10× more work with practically no loss of quality when they orchestrate and cheaper executors implement. The best fit is autonomous work lasting hours or days, producing tens to hundreds of thousands of lines of code.
The repo ships four skills in the Agent Skills layout: pragmatic-orchestration, coordinator-mode, stale-data-cleanup and remote-agents. porch provides five modes:
- review — independent opinions or multi-depth code review from several model families at once (read-only).
- delegate — hand a task to one exact agent: steerable by default, detachable, with
wait/watch/events/listto supervise long-running work (full-access runtime). - sessions — search and navigate local coding-agent session histories. Its format research draws on Agent Sessions; see the supported formats and evidence.
- media — transcribe and describe audio/video (Antigravity) and generate, edit, combine, animate (GIF) or describe images (Codex, Antigravity; description also Claude Code), read-only, with results collected into your output directory.
- quota — read remaining Codex / Grok subscription quota.
Supported worker harnesses: Codex CLI, Claude Code, OpenCode, Grok Build, Devin CLI, Antigravity CLI (agy), and Gemini CLI (review only).
The repo also ships remote-agents: a companion skill for operating dedicated remote Linux/Windows hosts that run these agents — secure VM/OS provisioning, SSH-over-SSM access with no public ingress, the WireGuard/SMB work bridge, porch on the remote host, a headless Windows desktop, bounded visual QA, durable worker daemons, and Codex Remote threads. See skills/remote-agents/SKILL.md.
Full documentation: skills/pragmatic-orchestration/README.md and SKILL.md.
For an optional live view of existing delegates, see Porch UI.
After its one-time build, porch ui --desktop opens an Electron window with run
discovery, filters, streaming output, and saved final answers. Closing it leaves
agents running. porch ui instead prints a local URL without opening a browser.
These combinations come from field use.
| Priority | Orchestrator → executor | Tradeoff |
|---|---|---|
| Best quality | Astra Light or Fable Low → Sol low or Opus low | Very high quality. Quotas still get consumed, but several times slower than using frontier models end-to-end. Opus low lasts longest as executor. |
| Quality/quota balance | Sol medium → Devin SWE 2.0, with Astra as planner | Devin SWE 2.0 is free on the $20 subscription until October 15, 2026. |
For planning, use Astra medium+ or Fable, guided by the code-that-fits-in-your-head skill (~/.claude/skills/code-that-fits-in-your-head/SKILL.md). Having the orchestrator and planner consult each other works well.
coordinator-mode turns a session into a long-lived coordinator: a frontier model that plans, derives invariants, designs verification, hands implementation to cheaper executors and accepts their results on evidence. It is built to stay in that role for days or weeks.
- Two roles. The coordinator owns the engineering quality of the codebase; an executor owns one assignment.
porch delegatetells every worker so, which keeps "you own this codebase" passages inAGENTS.mdfrom widening a worker's scope. - Judgment, not prohibitions. Delegation is the default because of cost and focus. Nothing is forbidden: the coordinator steps in itself when that is plainly better for the project.
- A journal. Goal, decisions, verification plan, workers and the next action live in one Markdown file outside the project, or inside the plan file when you ask for that.
- Compaction-proof. After every context compaction the coordinator rereads the skill and the journal. An optional hook puts the reminder back automatically.
- Verification by design. The coordinator decides which scenarios are checked, at which level (unit, integration, contract, end-to-end) and what counts as evidence. Executors write and run the tests.
Turn it on explicitly: /coordinator-mode in Claude Code, $coordinator-mode in Codex. See skills/coordinator-mode/SKILL.md.
stale-data-cleanup is Coordinator Mode applied to a full disk. On a machine where many agents work, the space is rarely old junk: it is finished workspaces nobody closed, caches, and a remainder only the owner can judge. The skill tells the three apart by evidence and returns verdicts, not a checklist.
- Verdicts, not checkboxes. Every candidate ends as removed, kept with a one-line reason, or asked. Questions are rare, batched, and put through the harness's interactive question tool with a recommendation.
- Evidence, not age. Work may go when it is preserved elsewhere, its task is closed, it is idle and nobody is in it. Data may go when it is regenerable or a proven duplicate. The evidence comes from the filesystem, processes, git and jj, task records, project documents and agent session histories (
porch sessions). - A strong coordinator, cheap researchers. One scan per volume is shared by parallel read-only researchers; narrower passes run until every sizeable candidate is clear. Executors then act on written verdict rules, one track per exclusive path prefix.
- A gate for removals. Plain paths go only through
apply_removals.py, which re-checks containment, version-control state, recency and live processes, and writes a manifest. A second scan must reconcile with the manifests. - A playbook for conflicts and for finishing: what to do when signals, rules, numbers or workers disagree; when to stop; the report; the cause of the growth and the fix.
- An observer between cleanups. A read-only run every couple of days:
disk_map.py trendshows which stocks (workspaces, caches, session history, data awaiting a decision) grow, how soon the volume is full and who can empty each. It removes nothing.observe.pyruns it from the machine's scheduler for several machines, with no model: a report per machine, and a message only when free space is under the target, under the floor, or the scan keeps failing.
Start it with /stale-data-cleanup in Claude Code or $stale-data-cleanup in Codex, or just say the disk is full. See skills/stale-data-cleanup/SKILL.md.
references/delegate.md collects the practices that address common subagent delegation failures:
- Write a precise task contract: purpose, exact working root, scope, compatibility constraints, anticipated pitfalls, acceptance criteria, and required checks.
- Every delegated worker is an executor.
porch delegateprefixes each new task with a short contract: the assignment sets the scope, out-of-scope findings go into the report, and checks are not weakened. - Check every worker within its first minute. Inspect actual actions and findings, then adapt supervision to risk and progress; 5–15 minutes is the suggested follow-up interval.
- Require a deviation journal when delegating to a less capable model. Record unexpected findings, evidence, actions, and unresolved risks. Read-only workers return it in their final answer.
- Do not retry blindly. Inspect events and partial work, send only new guidance, and confirm a writer has stopped before assigning overlapping work to a replacement.
- The parent owns verification. Inspect the diff and surrounding code, verify the checks, then reconcile the entire deviation journal. A worker's summary or successful exit is not enough.
- For long work, turn on
coordinator-mode: the orchestrator keeps its plan and progress in a journal, so context compaction cannot erase them. - In Codex, use a cron reminder every 15–30 minutes.
goalconsumes quota quickly. - Periodically ask whether enough work is running in parallel. Put that question in the cron description or install a hook to prompt it.
- With Claude Code as orchestrator, cap context at about 300k tokens with
/autocompact 300000to limit context rot. Keep updating the progress file. - Use Jujutsu (
jj) for parallel work. Its flexible conflict, rebase, and commit-moving semantics let conflicts accumulate for the orchestrator to resolve later in one pass. - Regularly have a strong model analyze session transcripts to assess subagent effectiveness and the orchestration flow.
- If workers spend hours without progress and the orchestrator cannot redirect them, stop all work and intervene. Continuing the same loop makes it worse.
npx skills add CodeAlive-AI/pragmatic-orchestration@pragmatic-orchestration
npx skills add CodeAlive-AI/pragmatic-orchestration@coordinator-mode
npx skills add CodeAlive-AI/pragmatic-orchestration@stale-data-cleanup
claude plugin marketplace add CodeAlive-AI/pragmatic-orchestration && claude plugin install pragmatic-orchestration@pragmatic-orchestrationThe system is fully field-tested on macOS. Linux and Windows 11 support is experimental: both are covered by CI but have less field use. CI runs on Ubuntu, macOS, and Windows.
Windows 11 requires Git Bash/MSYS2 and native Python 3.11+. porch.cmd runs sessions and quota natively; review and delegate run from Git Bash.
MIT — see LICENSE.
