Codex Plugin Environment Variables: Complete Configuration Reference

The Codex plugin utilizes ten distinct environment variables—ranging from CODEX_HOME for data directories to CODEX_COMPANION_APP_SERVER_ENDPOINT for broker connectivity—to control session persistence, file locations, and server communication without modifying source code.

The openai/codex-plugin-cc repository implements a Claude-compatible companion for the OpenAI Codex that relies on environment variables for runtime configuration. These variables determine where the plugin stores session data, how it identifies active companions, and whether it communicates directly with Codex or routes through a broker-based app-server.

Core Data and Session Variables

The plugin defines three primary variables for managing data locations and session identity.

CODEX_HOME

The CODEX_HOME variable specifies the base directory for Codex-related files. When unset, the plugin defaults to ~/.codex. This path anchors all persistent storage operations within the companion lifecycle.

According to the source code in plugins/codex/scripts/lib/codex.mjs, this variable resolves the root directory before any file operations begin.

CODEX_COMPANION_SESSION_ID

The CODEX_COMPANION_SESSION_ID variable (referenced internally as SESSION_ID_ENV) provides a unique identifier for the current companion session. This ID enables the plugin to track jobs and maintain state across process restarts.

In plugins/codex/scripts/lib/tracked-jobs.mjs, the plugin reads this variable to associate background tasks with specific user sessions.

CODEX_COMPANION_TRANSCRIPT_PATH

The CODEX_COMPANION_TRANSCRIPT_PATH variable (internal constant TRANSCRIPT_PATH_ENV) defines the filesystem path where session transcripts are written and read. This enables persistence of conversation history between companion restarts.

The implementation in plugins/codex/scripts/lib/claude-session-transfer.mjs uses this path to serialize and deserialize session state.

Broker-Based App-Server Configuration

When operating in broker mode, the plugin uses three additional variables to manage the app-server lifecycle.

CODEX_COMPANION_APP_SERVER_ENDPOINT

The CODEX_COMPANION_APP_SERVER_ENDPOINT variable (internal: BROKER_ENDPOINT_ENV) specifies the URL of the optional broker-based app-server. When this value is set, the plugin routes all requests to the specified server instead of communicating directly with the Codex endpoint.

This configuration is handled in plugins/codex/scripts/lib/app-server.mjs, where the presence of this variable triggers broker-mode initialization.

Process and Log Management

Two variables control the app-server's system integration:

• CODEX_COMPANION_APP_SERVER_PID_FILE (PID_FILE_ENV): Stores the process ID of the running app-server, enabling graceful shutdown detection.
• CODEX_COMPANION_APP_SERVER_LOG_FILE (LOG_FILE_ENV): Redirects the app-server's stdout and stderr streams to a specified log file.

Both variables are defined in plugins/codex/scripts/lib/broker-lifecycle.mjs, which manages the startup and teardown sequences.

Claude Integration and Lifecycle Variables

The plugin integrates with Claude-specific workflows through three additional environment variables.

CLAUDE_PLUGIN_DATA

The CLAUDE_PLUGIN_DATA variable (internal: PLUGIN_DATA_ENV) specifies the directory where the plugin stores persistent data, including session caches and state files. The function getPluginDataDir() in plugins/codex/scripts/lib/state.mjs resolves this path at runtime.

CLAUDE_ENV_FILE and CLAUDE_PROJECT_DIR

Two variables support the lifecycle hook system:

• CLAUDE_ENV_FILE: Points to a temporary shell script path that the plugin appends environment exports to. This facilitates variable propagation across the lifecycle boundary in plugins/codex/scripts/session-lifecycle-hook.mjs.
• CLAUDE_PROJECT_DIR: Identifies the current project directory, used as a fallback working directory in plugins/codex/scripts/stop-review-gate-hook.mjs.

System Environment Propagation

The plugin forwards two standard system variables to child processes:

• SHELL: Specifies the shell executable for spawning subprocesses on Windows, referenced in plugins/codex/scripts/lib/process.mjs.
• PATH: Inherited by spawned processes to ensure command resolution, as seen in tests/fake-codex-fixture.mjs.

These are not plugin-specific configurations but are critical for cross-platform process execution.

Practical Configuration Examples

Configure a custom data directory and session identifier before starting the companion:

process.env.CODEX_HOME = "/my/custom/codex";
process.env.CODEX_COMPANION_SESSION_ID = "my-session-123";

import { startCompanion } from "./plugins/codex/scripts/codex-companion.mjs";
await startCompanion();

Launch the plugin with broker-based app-server support:

export CODEX_COMPANION_APP_SERVER_ENDPOINT="http://localhost:5000"
export CODEX_COMPANION_APP_SERVER_PID_FILE="/tmp/codex-pid"
export CODEX_COMPANION_APP_SERVER_LOG_FILE="/tmp/codex.log"

node -r ./plugins/codex/scripts/codex-companion.mjs

Access the plugin data directory programmatically:

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

const dataDir = getPluginDataDir(); // uses CLAUDE_PLUGIN_DATA internally
console.log("Plugin data stored at:", dataDir);

Summary

• CODEX_HOME sets the base directory for all Codex files, defaulting to ~/.codex.
• CODEX_COMPANION_SESSION_ID and CODEX_COMPANION_TRANSCRIPT_PATH manage session identity and persistence.
• CODEX_COMPANION_APP_SERVER_ENDPOINT enables broker-mode operation, while CODEX_COMPANION_APP_SERVER_PID_FILE and CODEX_COMPANION_APP_SERVER_LOG_FILE handle process management.
• CLAUDE_PLUGIN_DATA, CLAUDE_ENV_FILE, and CLAUDE_PROJECT_DIR integrate with Claude-specific workflows.
• SHELL and PATH ensure proper subprocess execution across platforms.

Frequently Asked Questions

What happens if CODEX_HOME is not set?

The plugin automatically defaults to ~/.codex when the CODEX_HOME environment variable is undefined. This fallback is implemented in plugins/codex/scripts/lib/codex.mjs to ensure the companion always has a valid filesystem location for operations.

How do I enable broker mode for the Codex plugin?

Set the CODEX_COMPANION_APP_SERVER_ENDPOINT variable to the URL of your broker server (e.g., http://localhost:5000). When this variable is present, the plugin in plugins/codex/scripts/lib/app-server.mjs automatically routes requests through the specified endpoint instead of direct Codex communication.

Where does the plugin store session transcripts?

The plugin writes session transcripts to the path specified by CODEX_COMPANION_TRANSCRIPT_PATH. If this variable is not configured, the transcript location derives from other configuration values. The serialization logic resides in plugins/codex/scripts/lib/claude-session-transfer.mjs.

Can I use the Codex plugin without setting any environment variables?

Yes, the plugin operates with sensible defaults for most variables. Only CODEX_HOME defaults to ~/.codex, while optional features like broker mode require explicit configuration. Core functionality works without manual environment variable configuration, though production deployments typically customize paths and endpoints.

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