# Codex Plugin Environment Variables: Complete Configuration Reference > Discover all ten Codex plugin environment variables for configuration. Control session persistence, file locations, and server communication without code changes. Explore the complete reference. - Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) - Tags: api-reference - Published: 2026-07-11 --- **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: ```javascript 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: ```bash 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: ```javascript 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.