Codex Advisor

A Codex adapter for @juicesharp/rpiv-advisor. It adds one MCP tool, advisor, with an optional closed review mode. The zero-argument form remains supported. The server reads the current Codex JSONL session, keeps completed Advisor results as review context, removes only the current in-flight Advisor call, and asks a configured reviewer through an ephemeral read-only codex exec process. Codex compaction records replace the older effective history before the reviewer prompt is built.

Install

Install this directory as a local Codex plugin, then restart Codex. For this npm checkout:

bash /root/.codex/plugins/local/codex-advisor/scripts/install.sh

Install through npm

Codex does not currently accept an npm package directly as a plugin source. This package bridges that gap: npm distributes the complete plugin directory, and a global npm install registers that directory as a local Codex marketplace. The bundled manager can then clean the Codex state and ask npm to remove the owning global package in one command.

After publishing this package, install it globally with:

npm install -g @iidamie/codex-advisor

The package's postinstall registers the plugin when codex is available and starts the interactive initialization wizard when npm has a TTY. The wizard asks for the reviewer model, reasoning effort, and whether to enable the automatic policy. If npm has no interactive TTY, installation remains non-blocking and prints a prompt to run codex-advisor init later. If Codex is not installed yet, npm installation still succeeds; install Codex and run:

codex-advisor install

Run codex-advisor init at any time to configure or reconfigure interactively. Existing configuration is never overwritten without confirmation.

If the same codex-advisor-local marketplace is already registered from an older Advisor source, the installer migrates it only after verifying that the old source contains the same Advisor manifest; unrelated sources are left untouched and cause an actionable error.

Use the bundled command for a complete one-step uninstall:

codex-advisor uninstall

It interactively asks whether to retain advisor.json (the default is yes), then removes the Codex registration, managed AGENTS.md policy, npm package, and npm global commands. Add --remove-config to remove the persisted configuration without prompting:

codex-advisor uninstall --remove-config

Use codex-advisor uninstall --keep-config or --yes to retain the configuration without prompting, and --keep-package when only the Codex state should be removed. Do not rely on npm uninstall alone: npm 7 and later do not run package uninstall lifecycle scripts. If codex is unavailable, codex-advisor uninstall fails before changing state or invoking npm, so a stale marketplace registration is not silently left behind. If npm removal itself fails, the command exits nonzero after reporting that Codex state was cleaned but the npm package remains. npm lifecycle hooks are active only for global installs, so a normal local npm install does not modify Codex configuration. Reinstalling/updating globally runs the postinstall registration again, preserves the existing reviewer configuration and automatic policy, and skips the initialization wizard when configuration already exists; run codex-advisor init to reconfigure explicitly.

The plugin is inactive until a reviewer model is configured:

advisor-config models
advisor-config set cpa/gpt-6-astra high

The configuration file is ~/.config/codex-advisor/advisor.json, or $XDG_CONFIG_HOME/codex-advisor/advisor.json when $XDG_CONFIG_HOME is absolute. Run advisor-config off to disable the reviewer and remove the optional managed automatic-review policy from AGENTS.md.

advisor-config models reads Codex's cached catalog. When a default model_provider is configured, it prints that provider's model keys; with several providers and no default it prints bare model IDs rather than claiming every provider supports every model. advisor-config set accepts either provider/model or a model ID.

Automatic Advisor policy

Codex 0.153.4 does not expose Pi's developer-level extension policy directly. This plugin can install an explicit managed policy block in ~/.codex/AGENTS.md:

advisor-config auto on
advisor-config auto status
advisor-config auto off

When enabled, the policy asks Codex to:

• call advisor({ mode: "plan" }) before the first substantive change;
• call advisor({ mode: "blocked" }) when it is stuck, sees conflicting evidence, or repeats a failure;
• make the deliverable durable, then call advisor({ mode: "completion" }) before the final response;
• call advisor() when the correct mode is unclear.

This is the strongest supported Codex-side equivalent of Pi's strategy guidance, but it remains model-followed policy rather than an absolute runtime guarantee. If guidance.promptSnippet or guidance.promptGuidelines is present in advisor.json, auto on includes the normalized values in the managed policy block. The command is idempotent and preserves unrelated AGENTS.md content and permissions.

Advisor modes

The MCP tool accepts only these optional modes:

advisor()
advisor({ mode: "plan" })
advisor({ mode: "blocked" })
advisor({ mode: "completion" })
advisor({ mode: "" }) // automatic selection

A missing or empty mode lets the reviewer infer the most useful lens from the transcript. No arbitrary executor-provided prose is inserted into the reviewer prompt.

• plan: interpretation, constraints, risks, and approach before substantive work.
• blocked: conflicting evidence, repeated failures, and the safest next path.
• completion: correctness, safety, tests, and remaining gaps before the final response.

The visible branch, including developer/user/assistant messages, tool calls, tool results, and compaction summaries, is forwarded to the reviewer up to the configured character cap. When truncation is needed, the formatter keeps the head and tail and marks the omitted middle. Encrypted reasoning and raw chain-of-thought are excluded. The session thread and current turn IDs are verified; a turn that has not reached disk is retried briefly and then reported explicitly.

The exact feature mapping and current host limitations are documented in Pi/Codex parity.

The reviewer runs with --ephemeral --sandbox read-only --ignore-rules --json in an empty temporary workspace and isolated CODEX_HOME; only the selected provider table is copied. User/project plugins, MCP servers, rules, skills, and instructions are not inherited. The prompt and developer_instructions forbid tools, web search, filesystem access, and external actions. CODEX_ADVISOR_DEPTH blocks recursive Advisor calls.

Configuration example

{
  "modelKey": "cpa/gpt-6-astra",
  "effort": "high",
  "disabledForModels": [
    "cpa/gpt-6-astra",
    { "model": "cpa/gpt-5.5", "minEffort": "high" }
  ]
}

The bundled .mcp.json uses Codex's env_vars allowlist for CPA_API_KEY, CC_API_KEY, IDAMIE_API_KEY, OPENAI_API_KEY, and CODEX_API_KEY. If a custom provider uses another env_key or env_http_headers variable, add that exact name to the list before installing. The reviewer receives the selected provider credential and explicitly referenced header variables, not the rest of the executor environment.

maxTranscriptChars may reduce the forwarded context and is capped at 900,000 characters so the reviewer prompt stays below Codex's 1,048,576-character input limit. codexBin can override the Codex executable used for the reviewer subprocess.

Codex 0.153.4 does not register plugin-defined slash commands, and this adapter cannot change the executor's active MCP tool set at runtime. Configure the reviewer with advisor-config; the blocklist is enforced at call time, and the bundled Skill supplies the automatic review strategy. The reviewer subprocess runs with an empty workspace, isolated CODEX_HOME, disabled web search, no inherited MCP/apps/instructions, and post-launch detection for prohibited tool events. No documented no-tools execution flag is used by this adapter, so the review-only prompt and post-launch guard are the available host-side enforcement.

Uninstall

bash /root/.codex/plugins/local/codex-advisor/scripts/uninstall.sh

The uninstall script first removes only the managed automatic-review block from AGENTS.md, then removes this local marketplace, plugin registration, and the plugin-owned advisor-config launcher. It preserves unrelated AGENTS.md content and keeps advisor.json by default so a later reinstall can reuse the selection. Set CODEX_ADVISOR_REMOVE_CONFIG=1 to also remove the persisted reviewer configuration, including a path supplied through CODEX_ADVISOR_CONFIG. Repeated install or uninstall is safe; if the managed markers are incomplete, uninstall stops before deleting registration or files so the instruction file can be repaired safely.

codex plugin disable is controlled by the Codex host and currently has no plugin lifecycle hook, so it cannot automatically remove files outside the plugin. Use advisor-config off (which also removes the managed policy) or run the uninstall script when you want cleanup. advisor-config auto off remains available when you want to remove only the policy block while keeping the reviewer configured.

Testing

cd /root/.codex/plugins/local/codex-advisor
npm test
python3 /root/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .

Overrides for tests

• CODEX_ADVISOR_CONFIG
• CODEX_ADVISOR_SESSION_FILE (supports %THREAD_ID%)
• CODEX_ADVISOR_SESSION_ROOT
• CODEX_ADVISOR_SESSION_INDEX
• CODEX_ADVISOR_CODEX_BIN
• CODEX_ADVISOR_DEPTH
• CODEX_ADVISOR_CODEX_CLI (installation/uninstallation CLI override)