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

> Discover how SESSION_ID_ENV powers session tracking in the Codex plugin by defining the CODEX_COMPANION_SESSION_ID environment variable for seamless session management.

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

---

**`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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

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

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

```javascript
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.