Configuration Options for Customizing Codex CC Plugin Behavior

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 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>.

{
  "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 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.

{
  "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.

# 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. 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—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, status.md, review.md, 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 (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 enables it by default, while CODEx_API_KEY provides a fallback credential when not specified via CLI.

Summary

• Plugin manifest (plugin.json): Defines UI-visible settings via JSON Schema, controlling features like token budgets and model selection.
• Hook registry (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. 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 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) 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.

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