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

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:

// 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:

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:

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:

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.

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