# Session Runtime Status Check in Codex: How It Manages Shared vs Direct Execution

> Learn how Codex's session runtime status check optimizes resource usage by deciding to reuse a shared broker or launch a new private process for shared vs direct execution.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-10

---

**The session runtime status check determines whether Codex will reuse an existing shared broker or launch a new private process, optimizing resource usage and session isolation.**

The session runtime status check is a core mechanism in the `openai/codex-plugin-cc` repository that inspects the environment to determine how the Codex runtime will be launched for a given Claude session. Implemented in `plugins/codex/scripts/lib/codex.mjs`, this check distinguishes between shared broker reuse and direct process startup, ensuring efficient resource management and clear user diagnostics.

## What Is the Session Runtime Status Check?

The session runtime status check is performed by the function `getSessionRuntimeStatus` defined in `plugins/codex/scripts/lib/codex.mjs`. This function evaluates the environment to determine whether the current Claude session should connect to an existing shared broker or start a fresh Codex process.

The function returns an object indicating one of two **execution modes**:

**Shared Mode**: Triggered when `process.env[BROKER_ENDPOINT_ENV]` is set or when a broker session file exists at `loadBrokerSession(cwd)`. In this mode, the current Claude session reuses an existing shared Codex broker, with all review and task commands connecting to that broker instead of starting new processes.

**Direct Mode**: Activated when neither environment variable nor broker session file exists. In this case, the first Codex command (such as `/codex:review` or `/codex:task`) starts a new, private Codex process on demand.

The returned object includes detailed metadata:

```javascript
// Shared mode example
{
  mode: "shared",
  label: "shared session",
  detail: "This Claude session is configured to reuse one shared Codex runtime.",
  endpoint: "unix:/tmp/fake-broker.sock"
}

// Direct mode example
{
  mode: "direct",
  label: "direct startup",
  detail: "No shared Codex runtime is active yet. The first review or task command will start one on demand.",
  endpoint: null
}

```

## Why the Session Runtime Status Check Is Necessary

Understanding the runtime mode is essential for several architectural reasons:

**Resource Management**: Starting a Codex process is relatively heavyweight. Reusing a broker in shared mode avoids launching a new process for each command, significantly saving CPU and memory resources across sessions.

**Session Isolation**: When no broker is present (direct mode), each Claude session receives its own isolated Codex runtime. This prevents cross-session interference and ensures reproducible results between different tasks.

**User Feedback**: The status is surfaced in the `/codex:setup` report and the `/codex:status` command (implemented in `plugins/codex/scripts/lib/render.mjs`). This transparency helps users understand whether a shared runtime is already running or will be started on demand.

**Error Handling**: Certain commands, particularly background tasks, need to know whether a broker is available to correctly enqueue work or report that a shared runtime must be started first.

## How to Query and Use the Runtime Status

Developers can interact with the session runtime status check programmatically or observe it through CLI commands.

**Directly Querying the Runtime Status**

To inspect the current runtime mode programmatically:

```javascript
import { getSessionRuntimeStatus } from "./plugins/codex/scripts/lib/codex.mjs";

const status = getSessionRuntimeStatus(process.env, "/path/to/repo");
console.log(`Mode: ${status.mode}`);
console.log(`Details: ${status.detail}`);

```

**Integration in Setup Reports**

The runtime status is integrated into the setup workflow in `plugins/codex/scripts/codex-companion.mjs`:

```javascript
async function buildSetupReport(cwd, actionsTaken = []) {
  const workspaceRoot = resolveWorkspaceRoot(cwd);
  const codexStatus = getCodexAvailability(cwd);
  const authStatus = await getCodexAuthStatus(cwd);
  const config = getConfig(workspaceRoot);

  return {
    ready: nodeStatus.available && codexStatus.available && authStatus.loggedIn,
    sessionRuntime: getSessionRuntimeStatus(process.env, workspaceRoot),
    // additional fields...
  };
}

```

**Rendering in Status Commands**

The `render.mjs` file formats the status for user display:

```javascript
function renderStatusReport(report) {
  return [
    `# Codex Status`,

    `- Codex: ${report.codex.detail}`,
    `- Authentication: ${report.sessionRuntime.detail}`,
    // additional fields...
  ].join("\n");
}

```

## Key Implementation Files

The session runtime status check spans several files in the repository:

- **`plugins/codex/scripts/lib/codex.mjs`** – Defines `getSessionRuntimeStatus` and related helper functions for detecting broker endpoints.
- **`plugins/codex/scripts/codex-companion.mjs`** – Orchestrates CLI sub-commands and builds the setup report using the runtime status.
- **`plugins/codex/scripts/lib/render.mjs`** – Formats human-readable reports for `status` and `setup` commands.
- **`plugins/codex/scripts/lib/job-control.mjs`** – Aggregates job information, including runtime status for `/codex:status` output.
- **`tests/runtime.test.mjs`** – Unit tests validating both `direct` and `shared` modes.

## Summary

- The **session runtime status check** determines whether Codex operates in shared broker mode or direct startup mode.
- **Shared mode** reuses an existing broker via environment variables or session files, conserving resources.
- **Direct mode** launches isolated processes on demand, ensuring session independence.
- The check provides critical metadata for user-facing commands like `/codex:setup` and `/codex:status`.
- Implementation resides primarily in `plugins/codex/scripts/lib/codex.mjs` with integrations across the companion scripts.

## Frequently Asked Questions

### What triggers shared mode versus direct mode in Codex?

Shared mode activates when either the `BROKER_ENDPOINT_ENV` environment variable is set or a valid broker session file exists in the current working directory. Direct mode occurs only when neither condition is met, causing Codex to start a fresh process on the next command.

### How does the session runtime status check improve performance?

By detecting an existing shared broker, the check allows multiple Claude sessions to reuse a single Codex runtime rather than spawning separate processes for each command. This reduces memory overhead and eliminates the latency of process startup for subsequent operations.

### Where can I see the current runtime status as a user?

Users can view the runtime status through the `/codex:status` command or during `/codex:setup`, both of which display the mode, label, and detailed description of the current session configuration according to the rendering logic in `plugins/codex/scripts/lib/render.mjs`.

### Is the session runtime status check available for programmatic use?

Yes, developers can import `getSessionRuntimeStatus` from `plugins/codex/scripts/lib/codex.mjs` to programmatically determine the execution mode, enabling custom tooling to adapt behavior based on whether a shared broker is active.