What Is SESSION_ID_ENV and How It Powers Session Tracking in the Codex Plugin

SESSION_ID_ENV is a constant that defines the environment variable name CODEX_COMPANION_SESSION_ID, which serves as the single source of truth for tracking active Codex companion sessions across the openai/codex-plugin-cc repository.

The SESSION_ID_ENV variable centralizes session identification throughout the Codex plugin ecosystem, ensuring that hooks, job trackers, and runtime components can consistently read and write the current session identifier. By standardizing on one constant rather than hardcoding the environment variable name, the codebase maintains reliable session isolation and simplifies testing scenarios.

What Is SESSION_ID_ENV?

SESSION_ID_ENV is a string constant with the value CODEX_COMPANION_SESSION_ID. It represents the standardized environment variable key that stores the active session identifier for Codex companion operations. Rather than scattering the literal string "CODEX_COMPANION_SESSION_ID" throughout the codebase, the plugin declares this constant once and imports it wherever session context is required.

This approach guarantees that every module references the same environment variable name, preventing subtle bugs from typos or inconsistent naming conventions.

Where SESSION_ID_ENV Is Defined

The constant originates in plugins/codex/scripts/session-lifecycle-hook.mjs at line 20, where it is declared and exported for use by session management logic. Additionally, it is re-exported from plugins/codex/scripts/lib/tracked-jobs.mjs at line 6, providing a convenient import path for job tracking modules that need to tag operations with the current session ID.

By centralizing the definition in the session lifecycle hook and re-exporting through the jobs library, the architecture creates a clear dependency chain: lifecycle hooks set the variable, while downstream utilities read it.

How SESSION_ID_ENV Is Used in the Codex Plugin

The environment variable propagates through multiple subsystems to enable session-aware execution and cleanup.

Session Lifecycle Management

In session-lifecycle-hook.mjs, the hook writes the session ID to the process environment when a session starts using appendEnvVar(SESSION_ID_ENV, input.session_id). This makes the identifier visible to all child processes spawned during the session. When the session ends, the same hook cleans up jobs associated with that specific session ID.

// From session-lifecycle-hook.mjs
import { SESSION_ID_ENV } from "./lib/tracked-jobs.mjs";

function startSession(sessionId) {
  // Export the session ID so downstream processes can see it
  appendEnvVar(SESSION_ID_ENV, sessionId);
}

Job Tracking and Control

The lib/tracked-jobs.mjs module uses SESSION_ID_ENV to retrieve the current session from the environment, falling back to a configurable alternative if provided. This allows job trackers to associate background tasks with the correct session context.

In lib/job-control.mjs, the utility checks the environment variable to determine whether a job belongs to the active session, enabling scoped operations and preventing cross-session interference.

// From lib/job-control.mjs
return options.env?.[SESSION_ID_ENV] ?? process.env[SESSION_ID_ENV] ?? null;

Stop-Review Gate Operations

The stop-review-gate-hook.mjs script consumes SESSION_ID_ENV to resolve the current session context when handling stop-review gates. It accepts an explicit session ID from input parameters but falls back to the environment variable, ensuring continuity even when the ID isn't explicitly passed.

// From stop-review-gate-hook.mjs
const sessionId = input.session_id || process.env[SESSION_ID_ENV] || null;

Companion Helper Utilities

Finally, codex-companion.mjs exposes a getSessionId helper that simply returns process.env[SESSION_ID_ENV], providing a clean API for other plugin components to access the active session identifier without directly accessing environment variables.

// From codex-companion.mjs
return process.env[SESSION_ID_ENV] ?? null;

Practical Code Examples

When spawning child processes in test suites or runtime environments, you can simulate specific sessions by setting CODEX_COMPANION_SESSION_ID directly:

// From tests/runtime.test.mjs
run("node", [SESSION_HOOK, "SessionStart"], {
  env: {
    CODEX_COMPANION_SESSION_ID: "sess-current",
    // …other env vars
  },
});

To retrieve the current session ID in custom scripts:

import { SESSION_ID_ENV } from "./session-lifecycle-hook.mjs";

function getCurrentSessionId() {
  return process.env[SESSION_ID_ENV] ?? null;
}

Summary

• SESSION_ID_ENV is a constant equal to CODEX_COMPANION_SESSION_ID, serving as the canonical environment variable name for session tracking.
• Defined in session-lifecycle-hook.mjs and re-exported from lib/tracked-jobs.mjs to ensure consistency across the plugin.
• Enables session tracking by allowing jobs, hooks, and runtime components to associate work with specific sessions.
• Provides isolation between concurrent sessions (e.g., "sess-current", "sess-other", "sess-stop-review") by scoping operations to unique IDs stored under the same environment key.
• Simplifies testing by allowing test suites in tests/runtime.test.mjs to inject arbitrary session IDs via process.env to simulate various states.

Frequently Asked Questions

What happens if SESSION_ID_ENV is not set in the environment?

If SESSION_ID_ENV (or CODEX_COMPANION_SESSION_ID) is not set, the various helper functions return null or fall back to alternative logic. For example, stop-review-gate-hook.mjs defaults to null when the variable is missing, and codex-companion.mjs returns null via its getSessionId helper, allowing the plugin to operate in a session-less mode or require explicit session IDs via input parameters.

Can I customize the environment variable name used for session tracking?

While the constant SESSION_ID_ENV is fixed to "CODEX_COMPANION_SESSION_ID", some functions in lib/tracked-jobs.mjs accept an options.sessionIdEnv parameter that overrides the default. This allows specific job tracking operations to use a custom environment variable name while maintaining backward compatibility with the standard constant.

Why is SESSION_ID_ENV defined as a constant rather than used as a string literal?

Using a constant prevents typographical errors and ensures that all modules reference the exact same environment variable key. If the variable name needs to change in future versions, updating the single declaration in session-lifecycle-hook.mjs automatically propagates to all consumers, reducing maintenance risk and ensuring consistent session identification throughout the openai/codex-plugin-cc codebase.

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