How to Customize the Behavior of the Codex Plugin: Configuration and Extension Points

Yes, you can customize the Codex plugin extensively through JSON state files, TOML configuration, runtime slash commands, and custom skills that modify everything from the default AI model to the optional stop-review gate.

The openai/codex-plugin-cc repository separates core command handling from user-provided settings, allowing you to customize the behavior of the Codex plugin without modifying internal logic. By leveraging persistent state management in plugins/codex/scripts/lib/state.mjs, project-level configuration files, and the skills architecture, you can tailor the plugin to match specific workflow requirements.

Configuring the Stop-Review Gate

The stop-review gate is a hook that runs a Codex review before a Claude session ends. This feature is controlled by the stopReviewGate boolean flag stored in the plugin's persistent state.

Toggling the Gate via Commands

You can enable or disable the review gate at runtime using built-in slash commands:

/codex:setup --enable-review-gate   # turn the gate on

/codex:setup --disable-review-gate  # turn it off

These commands call setConfig in plugins/codex/scripts/lib/state.mjs to persist the change. When the plugin starts, loadState merges user overrides and makes the configuration available via getConfig according to the source code.

Programmatic Configuration

To enable the review gate from a script, import the state management utilities:

import { setConfig } from "./plugins/codex/scripts/lib/state.mjs";

const cwd = process.cwd();               // repository root
await setConfig(cwd, "stopReviewGate", true);
console.log("Review gate enabled");

The hook implementation in plugins/codex/scripts/stop-review-gate-hook.mjs reads the current config at the top of main() and, if stopReviewGate is true, launches a background Codex review via runStopReview.

Adjusting Model and Reasoning Settings

The plugin respects standard Codex CLI configuration, allowing you to customize the default model and reasoning effort without modifying plugin code.

Project-Level Configuration

Create a .codex/config.toml file in your repository root or in ~/.codex/config.toml to override defaults:

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

According to the README, the plugin applies the same configuration that the Codex CLI uses. The codex.mjs library reads this config via client.request("config/read") and exposes it to the rest of the plugin.

Runtime Overrides

For single runs, pass flags directly to review commands:

/codex:review --model gpt-5.4-mini --effort high

The companion script in plugins/codex/scripts/codex-companion.mjs forwards these arguments to the Codex app server, which respects the provided values.

Extending Commands with Custom Flags

Each slash command parses arguments using the generic parser in plugins/codex/scripts/lib/args.mjs. The parseArgs function accepts a config argument that defines allowed flags, meaning you can introduce new boolean or value options by editing the command's configuration.

For example, to add a --dry-run flag to the rescue command:

// In plugins/codex/scripts/lib/args.mjs
const rescueConfig = {
  booleanOptions: ["dry-run"],   // new flag
};
export const parseRescueArgs = (argv) => parseArgs(argv, rescueConfig);

Users can now invoke /codex:rescue --dry-run <task>, and your handler can inspect argv.dryRun to conditionally execute logic.

Adding New Skills

The repository ships with a skills directory at plugins/codex/skills/* that supports plugin extension without code modification. Adding a new skill requires only a SKILL.md file that defines the command name, description, and optional validateRequest hook.

The companion script automatically discovers these files and registers them as sub-commands. For example, the gpt-5-4-prompting skill demonstrates the required structure and metadata format.

Summary

• Toggle the review gate using /codex:setup commands or the setConfig API in state.mjs to control whether Codex reviews run before session ends.
• Change models via .codex/config.toml or runtime flags passed through codex-companion.mjs.
• Extend argument parsing by modifying the config object in args.mjs to support custom boolean or value flags.
• Add capabilities by dropping SKILL.md files into the skills directory, which the plugin auto-discovers.

Frequently Asked Questions

How do I enable the stop-review gate permanently?

Use the /codex:setup --enable-review-gate command or programmatically call setConfig(cwd, "stopReviewGate", true) from plugins/codex/scripts/lib/state.mjs. This persists the setting to the JSON state file, and the hook in stop-review-gate-hook.mjs will check this value via getConfig before each session ends.

Can I use a different AI model than the default?

Yes. Set model = "your-model-name" in .codex/config.toml at your repository root, or pass --model flags directly to commands like /codex:review. The plugin forwards these settings to the Codex CLI via the client.request("config/read") mechanism in codex.mjs.

Where are plugin settings stored?

Persistent state lives in a JSON file managed by plugins/codex/scripts/lib/state.mjs. The default state includes a config object with flags like stopReviewGate. The loadState and setConfig functions handle reading and writing this file, merging user overrides with defaults at startup.

How do I add a custom slash command to the plugin?

Create a new directory under plugins/codex/skills/ containing a SKILL.md file that defines the command name, description, and optional validation hooks. The companion script automatically discovers these skills and registers them as sub-commands without requiring changes to the core dispatcher logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}