Skip to main content
Glama

sol-luna-orchestrator

npm npm downloads M8ven Verified Node License: MIT

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 doctor

Start 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 --watch

Use 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 action

The 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

Contributing

Bug reports and pull requests are welcome. Start with Contributing.

License

MIT, see LICENSE.

Available Tools

5 tools
continue_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

    A4.3/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers