Session Runtime Status Check in the Codex Plugin: Purpose and Implementation

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

codex:status

Request detailed output for a specific job, bypassing the session filter:

codex:status <job-id>

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 <job-id>), 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.

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