How the Codex Plugin Handles Timeout and Polling for Status Checks

The Codex plugin provides both immediate status retrieval and a configurable wait-and-poll mode with default timeouts of 4 minutes and 2-second polling intervals.

The openai/codex-plugin-cc repository implements a dual-mode status checking system that lets developers either fetch the current state of a job instantly or block and poll until completion. This article examines the timeout and polling mechanics in the plugin's CLI and underlying JavaScript modules.

Immediate vs. Wait-and-Poll Modes

The codex status command in codex-companion.mjs supports two distinct behaviors:

• Immediate mode: codex status <job-id> returns the current job snapshot without blocking
• Wait-and-poll mode: codex status <job-id> --wait repeatedly polls until the job finishes or a timeout expires

Default Timeout and Polling Constants

The plugin defines its default timing parameters in codex-companion.mjs at lines 69-70:

const DEFAULT_STATUS_WAIT_TIMEOUT_MS = 240000;   // 4 minutes
const DEFAULT_STATUS_POLL_INTERVAL_MS = 2000;   // 2 seconds

These values establish the baseline behavior when users enable waiting without specifying custom durations.

CLI Option Parsing

The handleStatus function extracts user-supplied overrides for timeout and polling configuration. Located around lines 883-889 in codex-companion.mjs, it processes:

• --wait flag to enable polling mode
• --timeout-ms for custom timeout duration
• --poll-interval-ms for custom polling frequency

The Polling Loop Implementation

The core wait-and-poll logic resides in waitForSingleJobSnapshot, implemented in codex.mjs (referenced at lines 182-226 in codex-companion.mjs):

1. Timeout calculation: Uses DEFAULT_STATUS_WAIT_TIMEOUT_MS unless --timeout-ms is provided
2. Poll interval determination: Defaults to DEFAULT_STATUS_POLL_INTERVAL_MS unless overridden via --poll-interval-ms
3. Polling execution: While the job status remains "queued" or "running" and the deadline has not passed, the function sleeps for the smaller of the poll interval or remaining time, then generates a fresh snapshot via buildSingleJobSnapshot
4. Result composition: Returns the final snapshot with a waitTimedOut boolean flag indicating timeout-induced exit

Command-Line Usage Examples

Fetch status immediately without waiting:

codex status 12345

Wait with default timeout (4 minutes) and polling interval (2 seconds):

codex status 12345 --wait

Custom timeout and faster polling:

codex status 12345 --wait --timeout-ms 30000 --poll-interval-ms 500

Programmatic API Usage

The same polling logic can be invoked directly from JavaScript:

import { waitForSingleJobSnapshot } from "./plugins/codex/scripts/lib/codex.mjs";

const cwd = process.cwd();
const jobId = "12345";

const snapshot = await waitForSingleJobSnapshot(cwd, jobId, {
  timeoutMs: 30_000,          // 30 seconds
  pollIntervalMs: 500        // 0.5 seconds
});

console.log(snapshot);

Key Source Files

File	Purpose
plugins/codex/scripts/codex-companion.mjs	Main CLI entry point containing handleStatus, default constants, and --wait handling
plugins/codex/scripts/lib/state.mjs	Stores default timeout values and exports DEFAULT_STATUS_* constants
plugins/codex/scripts/lib/codex.mjs	Implements waitForSingleJobSnapshot driving the polling loop

Summary

• The Codex plugin implements configurable timeout and polling through the --wait flag with sensible defaults
• Default limits prevent indefinite hangs: 4-minute timeout and 2-second polling intervals
• User overrides are supported via --timeout-ms and --poll-interval-ms CLI options
• The waitTimedOut flag in the response clearly distinguishes timeout exits from completion
• Both CLI and programmatic interfaces expose identical polling behavior

Frequently Asked Questions

What is the default timeout when using codex status --wait?

The default timeout is 240000 milliseconds (4 minutes), defined as DEFAULT_STATUS_WAIT_TIMEOUT_MS in codex-companion.mjs. This prevents CLI commands from hanging indefinitely on long-running jobs.

How does the polling interval work when a job is about to timeout?

The polling logic in waitForSingleJobSnapshot sleeps for the smaller of the poll interval or the remaining time until deadline. This ensures the function returns promptly when the timeout is reached, rather than sleeping through the deadline.

Can I use the polling functionality without the CLI?

Yes. Import waitForSingleJobSnapshot from plugins/codex/scripts/lib/codex.mjs and pass a job ID with optional timeoutMs and pollIntervalMs configuration. The function returns a promise resolving to the final snapshot including the waitTimedOut indicator.

Where are the default timeout constants defined?

The DEFAULT_STATUS_WAIT_TIMEOUT_MS and DEFAULT_STATUS_POLL_INTERVAL_MS constants appear in both codex-companion.mjs (for CLI usage) and state.mjs (as the canonical source), ensuring consistent defaults across the plugin's modules.

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