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

> Easily customize Codex plugin behavior using JSON state files, TOML config, and custom skills. Modify AI models and more for tailored functionality.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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:

```bash
/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:

```javascript
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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file in your repository root or in `~/.codex/config.toml` to override defaults:

```toml
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:

```bash
/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:

```javascript
// 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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.