# How the Codex Plugin Handles Timeout and Polling for Status Checks

> Learn how the Codex plugin manages timeout and polling for status checks. Discover its default 4-minute timeout and 2-second polling intervals for efficient monitoring.

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

---

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

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

```bash
codex status 12345

```

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

```bash
codex status 12345 --wait

```

Custom timeout and faster polling:

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

```

## Programmatic API Usage

The same polling logic can be invoked directly from JavaScript:

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