# Session Runtime Status Check in the Codex Plugin: Purpose and Implementation > Understand the Codex plugin's session runtime status check purpose. It isolates Claude/Codex sessions and cleans up orphaned processes for robust session management. - Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) - Tags: internals - Published: 2026-07-12 --- **The session runtime status check ensures complete isolation between Claude/Codex sessions by filtering all job operations through the active `CODEX_COMPANION_SESSION_ID`, while automatically cleaning up orphaned processes when sessions terminate.** The `openai/codex-plugin-cc` repository implements a session-aware job management system that prevents cross-session interference. When developers invoke status commands or terminate sessions, the plugin uses runtime session identifiers to scope all operations to the current workflow context. ## Why Session Runtime Status Matters In multi-session development environments, job isolation prevents one session's tasks from bleeding into another. The Codex plugin addresses this by binding every job to a specific **session ID** stored in the `CODEX_COMPANION_SESSION_ID` environment variable. This architecture delivers three critical guarantees: - **Isolation**: Jobs from other sessions remain invisible during status checks - **Cleanup**: Terminated sessions automatically trigger cleanup of their associated jobs - **Accuracy**: Users see only relevant active and recent jobs for their current workflow ## How the Session Runtime Status Check Works The implementation spans two primary components that intercept session boundaries and command invocations. ### Session Lifecycle Hook When a session ends, the plugin executes `cleanupSessionJobs` to prevent orphaned processes. In `plugins/codex/scripts/session-lifecycle-hook.mjs` (lines 20-78), the hook reads the `SESSION_ID_ENV` variable to identify the closing session, then removes all jobs whose `sessionId` property matches the terminated session. This ensures that long-running processes spawned within a specific Claude/Codex session do not persist after the session closes, eliminating resource leaks and zombie processes. ### Status Command Implementation The `codex:status` command defined in [`plugins/codex/commands/status.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/status.md) forwards requests to `codex-companion.mjs`. When no explicit job ID is provided, the script loads persisted state from `state.mjs` and filters the job table to include only entries matching the current `CODEX_COMPANION_SESSION_ID`. Users can bypass this filter by specifying a specific job ID directly, which returns detailed information for that individual job regardless of session ownership. ## Key Implementation Files The session runtime status system relies on these specific components: - **`plugins/codex/scripts/session-lifecycle-hook.mjs`**: Handles `SessionStart` and `SessionEnd` events, appends environment variables, and triggers job cleanup on shutdown - **`plugins/codex/scripts/lib/state.mjs`**: Persists job metadata including the `sessionId` field that enables session-scoped queries - **`plugins/codex/scripts/lib/broker-lifecycle.mjs`**: Manages broker session metadata consumed by the lifecycle hook - **[`plugins/codex/commands/status.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/status.md)**: Defines the user-facing command interface that triggers the session-filtered status display ## Practical Usage Examples Display a compact table of all jobs for the current session: ```bash codex:status ``` Request detailed output for a specific job, bypassing the session filter: ```bash codex:status ``` The first command renders a Markdown table containing job ID, kind, status, phase, elapsed time, and summary—all filtered to the active session context. ## Summary The session runtime status check in the Codex plugin maintains strict boundaries between development sessions: - It reads `CODEX_COMPANION_SESSION_ID` from the environment to scope all operations - The `session-lifecycle-hook.mjs` cleans up running jobs when sessions terminate - The `codex:status` command filters output to show only current session jobs unless a specific job ID overrides the filter - Job persistence in `state.mjs` includes session metadata enabling accurate retrospective queries ## Frequently Asked Questions ### What happens to running jobs when a Codex session ends? When a session terminates, the lifecycle hook in `session-lifecycle-hook.mjs` extracts the session ID and calls `cleanupSessionJobs`, which terminates any processes still associated with that specific `sessionId`. This prevents orphaned jobs from consuming resources after the session closes. ### Can I view jobs from previous sessions? By default, `codex:status` filters output to the current session using `CODEX_COMPANION_SESSION_ID`. However, you can view detailed information for any specific job by providing its job ID as an argument (e.g., `codex:status `), which bypasses the session filter. ### Where is session information stored? Session metadata persists in `plugins/codex/scripts/lib/state.mjs`, which records each job's `sessionId` alongside execution details. The lifecycle hook and status commands reference this state to determine job ownership and filter appropriate results. ### How does the plugin prevent cross-session interference? The plugin isolates sessions by checking the `CODEX_COMPANION_SESSION_ID` environment variable before performing any job operations. Both the cleanup routine and status command use this ID to ensure jobs from other sessions remain invisible and unreachable, maintaining strict workflow boundaries.