# Configuration Options for Customizing Codex CC Plugin Behavior

> Explore Codex CC plugin configuration options including JSON manifest files, CLI arguments, and environment variables. Customize UI and automation without altering core code.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: configuration-guide
- Published: 2026-08-05

---

**The Codex CC plugin provides six declarative configuration sources—spanning JSON manifest files, CLI arguments, environment variables, hook definitions, command schemas, and JSON data contracts—that let you customize everything from UI settings to review-gate automation without modifying core engine code.**

The `openai/codex-plugin-cc` repository implements a flexible configuration architecture that separates plugin metadata from runtime execution logic. By editing specific JSON files in the `plugins/codex/` directory or passing flags when launching the broker, you can control authentication, feature toggles, and hook workflows. These configuration options for customizing plugin behavior follow a strict precedence hierarchy, ensuring that environment-level defaults can be overridden by session-specific arguments or per-workspace user settings.

## Plugin Metadata and UI Settings

The [`plugins/codex/.claude-plugin/plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/.claude-plugin/plugin.json) file defines core metadata (name, version, description) and exposes a **JSON Schema** that drives the Claude UI settings panel. The `settings` object within this file declares configurable parameters—such as token budgets or model selection—using standard schema types, defaults, and descriptions.

When users install the plugin, Claude renders input controls based on this schema. The selected values are persisted into the runtime state managed by `plugins/codex/scripts/lib/state.mjs` and accessed as `settings.<propertyName>`.

```json
{
  "name": "codex-cc",
  "version": "1.0.6",
  "settings": {
    "type": "object",
    "properties": {
      "maxTokens": {
        "type": "integer",
        "default": 2048,
        "description": "Maximum token budget for generated code snippets."
      },
      "useClaudeV2": {
        "type": "boolean",
        "default": false,
        "description": "Switch to Claude-V2 model for higher quality completions."
      }
    },
    "required": []
  }
}

```

## Hook Execution Control

The [`plugins/codex/hooks/hooks.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/hooks/hooks.json) file acts as a registry for built-in extension points. You can enable, disable, or replace hooks such as `session-lifecycle-hook` and `stop-review-gate-hook` by adjusting the module paths or setting values to `null`.

Setting a hook to `null` tells the bootstrap loader to skip that extension point entirely, while specifying a custom path injects your own logic at well-defined lifecycle stages.

```json
{
  "sessionLifecycle": "plugins/codex/scripts/lib/session-lifecycle-hook.mjs",
  "stopReviewGate": null,
  "brokerLifecycle": "plugins/codex/scripts/lib/broker-lifecycle.mjs"
}

```

## Command-Line Overrides

Located at `plugins/codex/scripts/lib/args.mjs`, the argument parser exposes runtime flags that override JSON configuration without editing files. Available options include `--port`, `--log-level`, `--no-review-gate`, and `--config <path>`.

Passing **--no-review-gate** flips the `reviewGateEnabled` boolean that `stop-review-gate-hook.mjs` checks before executing, effectively bypassing the gate for that specific session.

```bash

# Start the plugin-server with a custom port and skip the review-gate hook

node plugins/codex/scripts/app-server-broker.mjs --port 4242 --no-review-gate

```

## Environment Variables and State Consolidation

The `plugins/codex/scripts/lib/state.mjs` module consolidates configuration from three sources: **environment variables** prefixed with `CODEx_` (e.g., `CODEx_API_KEY`, `CODEx_WORKSPACE_ROOT`), **CLI arguments**, and **user settings** from [`plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugin.json). This hierarchy ensures that sensitive credentials can be injected globally while keeping feature flags flexible per session.

Environment variables provide global defaults, CLI arguments offer session-specific overrides, and user settings supply per-workspace persistence. The module resolves these values at startup, making them available to command implementations and hook scripts.

## Data Contracts and CLI Extensions

### JSON Schema Validation

Files under `plugins/codex/schemas/`—such as [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json)—define the shape of data exchanged between the plugin and Claude. By editing these schemas, you can introduce new optional fields that the UI surfaces as configurable parameters without breaking existing workflows.

### Command Definitions

The `plugins/codex/commands/` directory contains markdown files (e.g., [`setup.md`](https://github.com/openai/codex-plugin-cc/blob/main/setup.md), [`status.md`](https://github.com/openai/codex-plugin-cc/blob/main/status.md), [`review.md`](https://github.com/openai/codex-plugin-cc/blob/main/review.md), [`result.md`](https://github.com/openai/codex-plugin-cc/blob/main/result.md)) that document CLI commands and expose additional knobs like `--dry-run` or `--force`. These files are rendered as help pages by the `codex-cli`, while the underlying libraries (`process.mjs`, `render.mjs`, `git.mjs`) respect the same configuration hierarchy used by the server broker.

## Configuration Precedence Hierarchy

Configuration values resolve in the following order of precedence, as implemented in `state.mjs`:

1. **User-provided settings** from [`plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugin.json) (persisted per-workspace)
2. **Command-line arguments** (session-specific overrides parsed by `args.mjs`)
3. **Environment variables** (global defaults prefixed with `CODEx_`)

This hierarchy means that a flag like `--no-review-gate` temporarily disables the `stop-review-gate-hook` even if [`hooks.json`](https://github.com/openai/codex-plugin-cc/blob/main/hooks.json) enables it by default, while `CODEx_API_KEY` provides a fallback credential when not specified via CLI.

## Summary

- **Plugin manifest** ([`plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugin.json)): Defines UI-visible settings via JSON Schema, controlling features like token budgets and model selection.
- **Hook registry** ([`hooks.json`](https://github.com/openai/codex-plugin-cc/blob/main/hooks.json)): Enables or disables automation hooks such as `stop-review-gate-hook` and `session-lifecycle-hook`.
- **CLI arguments** (`args.mjs`): Supports runtime flags including `--port`, `--log-level`, `--no-review-gate`, and `--config <path>`.
- **Environment variables**: `CODEx_` prefixed variables (e.g., `CODEx_API_KEY`, `CODEx_WORKSPACE_ROOT`) provide global defaults.
- **State consolidation** (`state.mjs`): Resolves configuration precedence across environment variables, CLI args, and user settings.
- **Data contracts** (`schemas/`): JSON Schema files validate and extend the data exchanged with Claude, allowing safe evolution of plugin parameters.

## Frequently Asked Questions

### How do I disable the review gate without modifying JSON files?

Pass the `--no-review-gate` flag when starting the broker via `app-server-broker.mjs`. This sets `reviewGateEnabled` to false in the runtime state, causing `stop-review-gate-hook.mjs` to skip execution for that session only.

### Where do I define custom settings that appear in the Claude UI?

Add properties to the `settings` object in [`plugins/codex/.claude-plugin/plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/.claude-plugin/plugin.json). The JSON Schema you define there automatically renders as configuration controls in the Claude interface, with values persisted to the workspace state by `state.mjs`.

### What is the precedence order for configuration values?

The `state.mjs` module resolves values in reverse order of specificity: environment variables provide base defaults, CLI arguments override them for the current session, and user settings from [`plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugin.json) take highest precedence for per-workspace persistence.

### Can I add new validation rules for data returned by the plugin?

Yes. Edit the relevant file in `plugins/codex/schemas/` (e.g., [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json)) to add new optional properties. The plugin validates payloads against these schemas, and new fields can surface as configurable parameters in the UI if exposed through [`plugin.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugin.json).