Support & Troubleshooting

1. Support channels

For bug reports and feature questions, the GitHub issue tracker is the primary channel — it keeps the discussion public and searchable for the next person hitting the same thing. Use advisor@zerodelta.dev for anything you would rather not file publicly.

Codex Advisor is an open-source project maintained on a best-effort basis. There is no response-time commitment.

2. Reinstall or update Advisor

Codex Advisor is distributed through the official OpenAI Plugins Directory. If Advisor is missing, outdated, or not responding, reinstall or update it from the Directory, then start a new Codex thread so the installed plugin is available to the session.

The Directory package is skills-only. Consultations use bounded packets sent through your authenticated Codex/OpenAI account; Zero Delta operates no relay, hosted service, or MCP server.

3. Configure models

Find advisor.toml in the installed plugin root. The plugin root is two directories above the directory containing skills/consultation/SKILL.md. Edit that bundled file in place; do not copy it and do not use repository commands. Changes apply to the next consultation, with independent settings for Standard and Specialist.

Automatic Standard remains Terra/high for ordinary bounded architecture, interface, data-model, and generic-advisor decisions. Automatic Specialist remains Sol/high only when targeted evidence still leaves an eligible cross-system, compatibility/concurrency, competing-diagnosis, security/trust, recovery, irreversible-migration, or data-loss decision unresolved. Project importance, security adjacency, or an ordinary architecture question alone stays Standard. advisor-astra is a separate explicit-only Astra/high role; it is never selected automatically. Invalid TOML and unsupported-model values produce an explicit error; Advisor does not silently fall back. An update or reinstall may replace edits to the bundled file. There is no GUI settings screen in the normal flow.

4. Supported platforms and scope

Supported

• Codex CLI on macOS and Linux.
• Codex desktop on macOS and Linux, with persisted sessions.

Out of scope

• Generic ChatGPT alone. With no local Codex runtime, preflight emits route: unavailable.
• Remote and hosted services. The plugin operates with no MCP server and no hosted service; neither is supported.
• Native Codex subagents as a consultation transport. They inherit parent permissions and cannot supply the required read-only isolation guarantee.

5. Prerequisites checklist

Work through this before opening a ticket. Most route: unavailable reports resolve here.

1. Codex CLI or Codex desktop is installed and operational.
2. jq is installed and on your $PATH — check with which jq.
3. You have a /bin/sh-compliant POSIX shell.
4. An active persisted Codex session rollout exists in your Codex home directory.
5. CODEX_THREAD_ID is set in the active parent execution context.
6. The installed plugin can use its declared escalated launcher permission (require_escalated).
7. Your authenticated Codex/OpenAI account has access to the models configured in advisor.toml.

6. Common scenarios

A. Preflight returns route: unavailable

Symptom. The root agent emits:

ADVISOR DECISION
route: unavailable

Cause. inspect-parent-runtime.sh could not verify the parent environment or a prerequisite.

Remedies. Confirm jq is installed and reachable. Confirm you are in an interactive, persisted Codex session — ephemeral test sessions have no persisted rollout and correctly emit route: unavailable. Reinstall or update Advisor from the official OpenAI Plugins Directory, then start a new Codex thread.

B. Model availability or authorization failure

Symptom. The consultation launcher reports a failure or an unexpected model response.

Cause. The configured model is unavailable or unauthorized for your authenticated Codex/OpenAI account.

Remedies. Check the model and effort values in the installed advisor.toml, verify account access and usage availability, and correct the file in place. An unsupported model or invalid TOML reports an error; there is no silent fallback.

For advisor-astra, also confirm that the request was explicit. Automatic Standard and Specialist routing will not select Astra.

C. Response classification retry

Symptom. Stderr shows a single retry during consultation.

Behavior. This is by design. A runtime-valid first child whose response is empty or structurally malformed gets exactly one fresh retry. If the retry also fails, the plugin records recommendation: unavailable and decision: blocked and stops. Packet, launcher, identity, runtime, wrong-model, wrong-effort, and tool-use failures are terminal and never retry.

D. Deferred handoff returns no receipt

Symptom. A long consultation appears to launch, but the enclosing call reports no validated result.

Behavior. A nonterminal shell session_id is progress, not a receipt. The caller drains that exact session with write_stdin, accumulates its output, requires terminal exit, and validates exactly one schema-v3 envelope before returning it. An outer wait or heartbeat is not terminal evidence.

Recovery. Install an available update from the official OpenAI Plugins Directory, then start a new Codex thread and repeat the explicit request. This repair does not add model fallback; Standard, Specialist, and explicit-only Astra retain their documented routing.

7. Check an installed copy

From the new Codex thread, ask Advisor for a consultation on a bounded architecture or technical decision. A working installed copy leaves an ADVISOR DECISION receipt followed, when consultation is selected, by an ADVISOR CALL and verified ADVISOR RESULT receipt.

For an unavailable or skipped request, the ADVISOR DECISION receipt is still the diagnostic result. Share the relevant receipt with support after redacting secrets and proprietary context.

8. Submitting a report

Include these three things. Without them, the first reply is going to be a request for them.

1. Codex host type (CLI or desktop) and version.
2. Operating system and shell version.
3. The relevant ADVISOR DECISION, ADVISOR CALL, or ADVISOR RESULT receipts from the conversation.