Diverter

Diverter

English | 简体中文

You turn on Ultra for a complex task—then research, testing, and other independent work start consuming the same premium capacity. Does every step really need Ultra?

💡 Why Diverter

⚡ Diverter distills Ultra's delegation strategy into non-Ultra Codex sessions: call the right specialist when work can split, keep the main thread moving, and let simple tasks stay simple.

• Ultra-inspired delegation without Ultra. Bring task splitting, specialist routing, and result integration to non-Ultra Codex sessions.
• No manual agent choreography. Diverter decides when specialist help is useful and which role fits.
• Keep the main thread moving. Specialists handle independent work while simple tasks stay simple.

✨ See Diverter in action

A release audit splits across specialists, then returns through the same guardrails.

🚀 Quick Start

Diverter requires Codex CLI 0.145.0 or later for native subagents and Root-only turn hooks.

1. Tell Codex:

   Fetch and follow instructions from https://raw.githubusercontent.com/GML-MMGroup/Diverter/refs/heads/main/.codex/INSTALL.md
   

2. After installation, open /hooks, review and trust Diverter's SessionStart and UserPromptSubmit Hooks, then start or reopen a task.

3. During installation, choose auto (recommended) for proactive dispatch or ask for approval-first dispatch. Inspect or change the user-level policy with:

   $diverter-mode status
   $diverter-mode auto
   $diverter-mode ask
   

🎯 How Diverter helps

Diverter looks for work that benefits from a specialist, then keeps the main task moving while that specialist handles an independent deliverable.

• Your selected skill keeps control of its workflow and gets focused help only when it adds value.
• Clear write boundaries keep independent changes moving and serialize overlapping work.
• The main thread checks and integrates specialist results into one coherent answer.

When Codex already owns native proactive delegation, Diverter silently steps aside. See OpenAI's subagent documentation.

Verified with 60+ automated tests and real native subagent lifecycle runs.

🧭 Choose your delegation policy

  Policy
  Behavior

  <code>ask</code>
  Proposes one lineup and waits for approval before dispatching


  <code>auto</code>
  Announces one lineup and dispatches it immediately for any Work Mode

Policy changes apply at the next SessionStart; restarting or reopening the task is the predictable way to apply one. auto changes dispatch authorization, not Codex permissions, sandboxing, or handoff write boundaries.

🎭 Roles

Diverter includes ten Bundled Subagents. The installer offers the recommended set (code-mapper, docs-researcher, reviewer, security-auditor, test-engineer, and test-automator), all roles, or a custom selection.

Role	GPT-5.6 model	Reasoning effort	What it does
code-mapper	gpt-5.6-terra	high	Traces code paths, symbols, and ownership boundaries
search-specialist	gpt-5.6-luna	medium	Gathers focused repository or external evidence
docs-researcher	gpt-5.6-luna	high	Verifies official APIs, versions, and guarantees
knowledge-synthesizer	gpt-5.6-luna	high	Reconciles long or conflicting findings
task-distributor	gpt-5.6-sol	medium	Splits broad goals into bounded work packages
reviewer	gpt-5.6-sol	medium	Reviews correctness, regressions, and maintainability
security-auditor	gpt-5.6-sol	high	Audits trust boundaries, secrets, and agent-tool safety
test-engineer	gpt-5.6-luna	xhigh	Designs minimal test coverage for behavior and risk
test-automator	gpt-5.6-terra	xhigh	Adds bounded regression tests after behavior is clear
web-performance-auditor	gpt-5.6-luna	xhigh	Audits Web performance evidence and Core Web Vitals risks

Diverter selects capabilities first, then maps them to the native roles installed in your Codex environment. Custom role sets can adapt role-lineups.md.

🔄 Work Modes

Work Mode	Boundary
read-only	Inspect and report; never write files
mixed	Investigate first, then perform bounded writes with explicit artifact ownership
write-capable	Edit only within the explicit handoff and sandbox

Diverter always names one Work Mode before dispatch.

⚙️ How It Works

1. The SessionStart Hook loads the user-level Delegation Policy and full Session Contract, restoring both after compaction.
2. Before each Root turn, UserPromptSubmit adds one short Turn Reminder; child turns are filtered deterministically through agent_id and receive no reminder.
3. Preflight privately evaluates strong positive task-shape signals, clear exclusions, and read-heavy versus write-heavy tie-breakers. Every ROOT_ONLY decision stays silent; eligible work loads Diverter before task work and uses its policy-specific dispatch message as the receipt.
4. Diverter selects the bounded Child Contribution, Smallest Sufficient Lineup, and Work Mode. Read-heavy exploration, code-plus-docs verification, independent evidence, specialist review, and Root Context Preservation lean toward delegation without requiring a separate concurrent Root deliverable. When another active skill requires a subagent, Diverter absorbs that child task as one required, deduplicated route while the focused skill keeps its core workflow. ask waits for approval; auto announces and dispatches immediately.
5. Root may continue useful work or wait for a needed Child result, while every child remains a leaf. Root then judges, proportionally verifies, integrates, and returns the