sol-luna-orchestrator
This MCP server lets a Codex parent delegate bounded work to Luna workers, with scheduling, verification, recovery, and read-only exploration.
Delegate a single bounded task (implementation, tests, bugfix, refactor, investigation, chore) with scope, acceptance criteria, verification commands, and compute policy.
Delegate batches of up to 12 tasks: sequential for dependencies/shared state, parallel for independent disjoint scopes using isolated worktrees.
Continue an eligible task once via an opaque continuation reference and one bounded instruction, keeping the original contract immutable.
Run routing preflight for advisory guidance on solo, single, sequential, or parallel execution.
Explore a repository, API, or documentation scope read-only for provenance-marked claims, facts, inferences, and unknowns.
Enforce declared scopes, rerun verification, reconcile observed edits, allow bounded repair/recovery, and return verified handoffs or evidence.
Workers cannot delegate or recurse; the parent retains architecture, sequencing, and final judgment.
Provides tools for orchestrating OpenAI Codex agents, allowing a supervising agent to delegate bounded implementation tasks to isolated worker threads with enforced file scopes, parallel worktrees, and verification of results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sol-luna-orchestrator Delegate fixing the failing tests in auth, payments, and search in parallel."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sol-luna-orchestrator
Give Codex a team of workers for substantial tasks, with clear scopes and independently checked results.
Sol plans the work and reviews the outcome. Luna workers handle bounded tasks, with parallel work isolated in separate Git worktrees. The orchestrator checks what actually changed, reruns verification, and returns evidence for the parent to review. Workers cannot delegate further.
Use one worker for a focused task, sequential workers for dependent steps, or parallel workers for independent work. Codex can also stay solo when delegation would add more overhead than value.
Quick start
You need Node.js 22.12 or newer and a logged-in OpenAI Codex CLI.
npm install -g sol-luna-orchestrator
sol-luna-orchestrator init
sol-luna-orchestrator doctorStart a fresh Codex session and work normally. Codex can discover the orchestrator and choose when to delegate; you do not need to select workers or call MCP tools yourself.
Watch task progress in another terminal:
sol-luna-orchestrator activity --watchUse status to inspect setup and doctor to diagnose problems. For clone
installs, model settings, and advanced options, see
Configuration.
Related MCP server: Codex Gemini Delegator V2
How it works
Codex parent
|
+--> stay solo
+--> optional read-only explore or routing preflight
+--> bounded contract: scope + intent + acceptance + verification
|
+--> one Luna worker
+--> sequential workers sharing workspace state
+--> parallel workers in isolated worktrees
|
v
observed edits + authoritative verification
|
v
thin verified handoff, evidence, or next actionThe parent chooses the execution shape. A user-owned compute policy bounds the worker model, effort, count, and concurrency; adaptive routing may recommend solo, single, sequential, or parallel execution but never widens that policy. The orchestrator reconciles worker claims with observed changes and reruns the declared checks, including a final deduplicated batch check after integration. See discovery and adaptive routing for the fresh-session setup and routing guidance.
Any compatible parent model may supervise. You can pin a worker model or opt into automatic Luna selection, which freezes the chosen model for each server session. See model selection for defaults, configuration, and availability limits.
Features
Capability | What it provides |
Adaptive orchestration | Choose solo, single, sequential, or parallel work within your model, effort, and concurrency limits. |
Isolated parallel execution | Give independent workers separate worktrees, then check scopes and conflicts before integration. |
Authoritative verification | Check observed edits and rerun declared checks, including final batch verification after integration. |
Bounded repair and recovery | Allow an eligible repair or recovery attempt without uncontrolled retry chains. |
Continuations and next actions | Resume eligible work under its original contract and single-use execution authority. |
Context lifecycle management | Keep routine handoffs compact while preserving evidence and execution history for review. |
Read-only exploration and portable context | Investigate an admitted scope and carry informational history across sessions. |
Observability and diagnostics | Inspect progress, results, and setup without exposing task prompts in the activity stream. |
MCP surface
The normal parent process registers exactly five MCP tools:
delegate_task- run one bounded task.delegate_tasks- run sequential or parallel task batches.continue_task- resume an eligible task with an explicit follow-up.routing_preflight- after cheap bounded structural inspection, classify concrete candidate leaves and ask for advisory routing guidance.explore- investigate an admitted scope without changing it.
Worker processes register no MCP tools and cannot recurse into delegation. The workflow coordinator and cross-session handoff helpers are programmatic APIs, not additional MCP tools. Cross-session handoff data is informational: it does not grant authority, retry permission, continuation rights, or a wider compute policy.
Safety
Delegated work runs under server-enforced compute policy and declared-scope controls; parallel workers use isolated worktrees, and the runtime detects and reports scope or integration conflicts. These are guardrails, not an absolute sandbox: workers write real files, and some execution runs with the operator's permissions. Read Security for the threat model and limitations.
Documentation
Configuration - requirements, setup, policies, and platform details.
Security - threat model and trust boundaries.
Observability - activity, result surfaces, and privacy semantics.
Troubleshooting - diagnosis and recovery.
Supervisor rules - delegation, effort, contracts, and review policy.
Roadmap - future priorities and constraints.
Changelog - release notes from the 0.13.0 baseline forward.
Contributing - development and release workflow.
Contributing
Bug reports and pull requests are welcome. Start with Contributing.
License
MIT, see LICENSE.
Available Tools
5 toolscontinue_taskContinue an eligible Luna taskA
Continue ONE eligible task once in the same Luna Codex thread with an opaque single-use continuationReference and one bounded instruction. The original objective, allowedFiles, forbiddenFiles, changeIntent, acceptance, and verification contract remain immutable; no widening fields exist. Luna cannot delegate, and continuation never starts automatic repair. Verification, scope checks, and evidence reconciliation run again. handoff is default; compact/full are compatibility modes. While pending with no meaningful new state, remain silent; do not narrate waiting or polling. Report only a result, error, cancellation, timeout, or actionable state change.
Inputs: instruction (required), continuationReference (required), resultDetail.
delegate_taskDelegate a bounded task to a Luna workerA
Delegate ONE substantial, bounded executable seam to gpt-5.6-luna; no second seam is required. Keep small, simple, or tightly coupled work solo. Tasks may be implementation, tests, bug fixing, refactoring, investigation, or chores. The parent owns architecture, decomposition, unresolved design, sequencing, interfaces, scope, acceptance, and final judgement. Luna owns scoped exploration, implementation, verification, and bounded repair; it cannot see the conversation or delegate.
Provide a self-contained objective, effortReason, acceptanceCriteria, verificationCommands, changeIntent, and honest scopes; add a concise activityLabel when safe and only repository-unavailable context. automaticRepair permits at most one conservative same-thread repair. Results include one evidence-derived failureDecision; parent owns nonautomatic actions. resultDetail=handoff is the default.
The runtime reruns declared checks and reconciles observed edits. A clean PASS returns a text-only VERIFIED_COMPLETE handoff: finish without rereading worker-owned files or rerunning passed checks unless a listed risk changes architecture. FAILED/BLOCKED, untrustworthy, discrepant, scope-violating, refused/skipped, or runtime-error results expand with evidence. Worker claims are not authoritative.
Delegate only when ownership, isolation, context, verification, latency, coordination risk, quality, and current parent-conditional credit economics beat fixed overhead; raw tokens are not credit cost and no saving is guaranteed. While pending with no meaningful new state, remain silent; do not narrate waiting or polling. Report only a result, error, cancellation, timeout, or actionable state change.
Inputs: objective (required), effortReason (required), acceptanceCriteria (required), effort, +16 more.
delegate_tasksDelegate several tasks to Luna workersA
Delegate a batch intended for two or more owned seams to gpt-5.6-luna; one task remains accepted for compatibility, but prefer delegate_task when no scheduling is needed. Use sequential for dependencies/shared workspace state and parallel only for genuinely independent disjoint declared scopes. Do not create artificial seams. At most 12 tasks are accepted and at most 3 run concurrently; the rest queue. Each task needs a self-contained contract and a concise activityLabel when a safe label exists. The parent owns architecture/interfaces and exceptional judgement; Luna owns exploration, implementation, verification, and repair. automaticRepair is one bounded task-local turn.
Parallel same-file edits prevent automatic integration. allowOverlappingScopes:true only accepts the declared overlap; it is not a write sandbox and does not permit same-file integration. integrate=false skips copying and retention follows operator policy. Partial outcomes remain visible. automaticRecovery defaults true: at most one evidence-eligible timeout continuation or exact process-exit retry; a counter alone never authorizes retry. Repair precedes recovery and neither nests. Successes, cancellation, scope/security/evidence failures, refused checks, discrepancies, and conflicts are never retried. Successful streams survive sibling failure.
After integration, deterministic code reruns the deduplicated union of declared checks in the final workspace. completionState=verified-complete means all seams, integration, and final checks passed; the default text-only handoff then tells the parent to finish without rereading files or rerunning checks. Any failure/refusal/conflict returns rich evidence for targeted diagnosis. resultDetail is one batch-level compatibility choice. More workers are not automatically cheaper; raw tokens are not credit cost and savings depend on the parent and task mix. While pending with no meaningful new state, remain silent; do not narrate waiting or polling. Report only a result, error, cancellation, timeout, or actionable state change.
Inputs: mode (required), tasks (required), integrate, resultDetail, +5 more.
exploreExplore repository, API, or documentation with LunaA
Explicitly explore an admitted repository, API, or documentation scope with gpt-5.6-luna; fixed read-only disposable execution returns provenance-marked worker claims, runtime facts, inferences, and unknowns. Implements nothing, cannot delegate, and is never automatic.
Inputs: scope (required), target (required), effortReason (required), effort, +9 more.
routing_preflightCheck cheaply whether delegating is worth itA
Cheap deterministic check of whether delegating is worthwhile. First use cheap, bounded repository/test inspection to identify candidate delegated leaves; describe those leaves, not the whole objective, and defer broad exploration. The parent may retain shared contracts and final integration. "unknown" biases advice solo but never refuses. Creates no worker, batch, worktree, or thread, refuses nothing, and returns route (solo | either | delegation-plausible), matched rule, explicit/defaulted provenance, signals, and structural parallel eligibility. Advisory only and never required: the parent owns sequential vs parallel, worker count, effort, and final decision; choosing zero workers is normal. either means fixed delegation overhead needs explicit justification, otherwise stay solo.
Inputs: seams (required), seamSize, coreOverlap, integration, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct orchestration stage: cheap advisory routing_preflight, single-seam delegate_task, multi-seam delegate_tasks, same-thread continue_task, and read-only explore. The only real overlap is delegate_task vs delegate_tasks, which the descriptions resolve explicitly ('prefer delegate_task when no scheduling is needed'), so an agent can select correctly.
Four tools follow a readable snake_case verb_noun pattern (continue_task, routing_preflight, delegate_task, delegate_tasks), though delegate_task/delegate_tasks differ only by pluralization. 'explore' breaks the pattern as a bare verb, and 'routing_preflight' is noun-flavored, but the set is still predictable.
Five tools is well-scoped for a delegation orchestration server: one advisory check, two delegation paths, a continuation, and a read-only exploration mode. No tool looks redundant or bolted on.
The surface covers the core lifecycle: preflight gating, single and batch delegation, continuation, and exploration, with rich result/recovery semantics described. Gaps are minor — there is no explicit cancel or status/poll tool, and the descriptions assume agents remain silent while pending, so a parent cannot actively query in-flight work.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseAqualityCmaintenanceA local MCP server that lets Claude delegate scoped work to Codex with structured results and guardrails, supporting planning, code review, build, reverse engineering, and long-running background tasks.1144 PyPIMIT
- AlicenseAqualityDmaintenanceAn MCP server that lets OpenAI Codex delegate tasks to Google Gemini agents as isolated background workers, with Git worktree isolation, loop detection, and security boundary enforcement.72MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that lets Codex supervise Claude Code or DeepSeek Harness as workers in isolated Git worktrees, with a bridge_run/bridge_respond/bridge_apply workflow for task delegation and safe cherry-pick integration.14 npmApache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that splits coding work between ChatGPT web (planning, review) and Codex CLI (implementation), enabling agentic workflows over a local repo with risk-gated execution and safety rails.23MIT