Plain-English guide to Sol Advisor

Get started

Two things to install: the plugin (both lanes need it) and, for the native lane only, the companion agent roles. The Luna lane needs no companion install — just an explicit opt-in.

Requirements

What you need first

Both modes

A current Codex CLI or ChatGPT desktop app with plugins enabled
Access to GPT-5.6 Sol / High for the primary task

Native lane (only)

Native subagents and custom-agent support enabled
Access to GPT-5.6 Terra / High
jq (used by the companion-install lookup)

Luna lane (only)

Explicit authorization in your current request (e.g. "use the Luna task lane")
Access to GPT-5.6 Luna / Max and the Codex app-task tools

Step 1

Install the plugin

Required for both lanes. Add the GitHub repo as a Codex marketplace, then install.

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

Step 2 · native lane

Install the companion agents

Mandatory for the native lane. The installer only adds missing templates and verifies them byte-for-byte — it never overwrites a different local role.

# Locate the installed plugin
plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"
test -n "$plugin_dir"; test -d "$plugin_dir"

# Install the companion roles, then verify
sh "$plugin_dir/scripts/install-agents.sh"
sh "$plugin_dir/scripts/install-agents.sh" --check

After --check passes, start a new Codex task (native agent types are discovered at task creation) and select GPT-5.6 Sol with High reasoning. Then ask for implementation work, or invoke the orchestration skill directly:

Use $sol-advisor:orchestration to build this feature, verify it, and obtain the final Sol review before reporting done.

Step 2 · Luna lane

Opt in to Luna instead

No companion install needed. Just authorize the lane explicitly in your request — a general "implement this" is not enough.

Use the Luna task lane for this feature.

The primary Sol task then creates a user-visible GPT-5.6 Luna / Max task, monitors it, reads the actual diff, sends corrections, and accepts before any PR is authorized.

Troubleshooting

When something stops

Companion check fails

--check is non-mutating and fails until both current role files match exactly and Luna is absent. Re-run the install, then --check again. It refuses modified or symlinked destinations.

Routing can't be observed

If the spawn metadata doesn't show the expected role/model/effort, the lane stops. Use the read-only runtime inspector as a fallback for omitted fields.

Existing task can't see roles

Native agent types are discovered when a task is created. Start a fresh task after a successful install/update.

Luna not available

The Luna lane stops without fallback if GPT-5.6 Luna, Max reasoning, or any required app-task tool is missing. Fall back to the native lane.

Note: commands are summarized from the MIT-licensed README. Always confirm against the official repository, which is the authoritative source.