Sol Advisor

Sol Advisor is an open-source Codex plugin built by Daniel McAteer (DannyMac180) that implements a capability-routed software delivery workflow for the Codex CLI and ChatGPT desktop app. It keeps architecture, decomposition, verification, and acceptance in a primary Sol session while delegating bounded implementation work to either native Terra subagents or user-visible Luna app tasks. The project is licensed under MIT and hosted on GitHub.

What It Is

Sol Advisor is a Codex-native architect workflow plugin — a structured orchestration layer that sits on top of OpenAI's Codex platform to enforce separation of concerns between high-level architecture and hands-on implementation. The primary session (GPT-5.6 Sol / High reasoning) owns requirements, specs, verification, and final acceptance. Implementation is routed to either a native Terra subagent (default) or an explicit Luna app task, depending on what the user authorizes. The result is a disciplined, role-pinned delivery pipeline rather than a single monolithic coding session.

Two Routing Lanes

Sol Advisor exposes two distinct implementation lanes, each with strict activation rules:

• Native subagent lane (default): Uses the installed sol_advisor_terra_implementer custom-agent role (GPT-5.6 Terra / High), followed by a fresh sol_advisor_sol_reviewer (GPT-5.6 Sol / High) for context-independent review. The primary Sol session cannot report completion until the reviewer returns a "ship" verdict.
• Luna task lane (explicit opt-in): Creates a user-visible Codex app task using create_thread with model=gpt-5.6-luna and thinking=max. The primary Sol task monitors the Luna task via wait_threads and read_thread, inspects the actual diff and verification evidence, sends corrections via send_message_to_thread, and authorizes PR creation only after accepting the work. This lane never activates automatically — the user must explicitly request it in the current message.

Neither lane has a silent fallback. A missing role file, unavailable model, or unobservable routing metadata stops the affected lane with an actionable error.

Installation and Setup

Sol Advisor installs via the Codex plugin marketplace using two shell commands:

codex plugin marketplace add DannyMac180/sol-advisor --ref main
codex plugin add sol-advisor@sol-advisor

Native mode additionally requires running the companion installer script (install-agents.sh) to place the Terra and Sol reviewer TOML role files in the user's Codex agents directory. The installer is intentionally non-overwriting: it refuses to replace modified, symlinked, or nonregular files, and a --check flag performs a byte-for-byte verification without mutation. Luna-only users can skip companion installation entirely.

A repository verifier (verify.sh) validates JSON and TOML, role pins, installer behavior, migration logic, runtime-inspector fixtures, and lane contracts without touching Codex configuration.

Update: Version 0.4.0

The repository reached version 0.4.0 shortly after its August 2026 creation. This release retains byte-exact migration support for the historical v0.2.0 companion files (sol-advisor-luna-implementer.toml and sol-advisor-terra-implementer.toml), updates the native routing to use Terra / High exclusively, and removes the legacy Luna implementer TOML from native mode. The routing update was motivated by Eric Provencher's post on X. The repository accumulated over 1,000 stars and 73 forks within days of creation, according to GitHub metadata.

Architecture and Safety Model

The orchestration design enforces several hard constraints:

• Role pinning: Native per-spawn calls cannot override the installed role pins. Model and effort must match exactly or the lane stops.
• Read-only reviewer sandboxing: The Sol reviewer TOML requests read-only sandboxing. If the host broadens the sandbox and hard isolation is required, the review lane stops rather than proceeding with weakened guarantees.
• Concurrent task safety: Independent stacks may run concurrently only with separate tasks and non-overlapping file ownership. Shared-file or dependent stacks are always serial.
• PR authorization gate: A Luna task must not create or push a PR before the primary Sol task explicitly authorizes it after reviewing the diff and checks.

The runtime inspector script (inspect-agent-runtime.sh) provides a read-only fallback for routing evidence when the Desktop app omits model or effort metadata, emitting only allowlisted routing fields and refusing to print prompts, tokens, or configuration contents.