# How the OpenAI Codex Plugin Handles Job Resumption with `--resume` and `--resume-last` Flags

> Learn how the OpenAI Codex plugin uses --resume and --resume-last flags to seamlessly resume job threads in your Claude sessions. Understand this powerful feature for uninterrupted workflows.

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

---

**The Codex plugin treats `--resume` as a user-friendly alias that always maps to the internal `--resume-last` flag, which attaches new prompts to the most recent persisted job thread in the current Claude session.**

The **job resumption** feature in the OpenAI `codex-plugin-cc` repository allows developers to continue interrupted or completed LLM tasks without losing conversation context. This capability is implemented through a two-step flag-parsing and dispatch system that ensures session isolation and deterministic behavior.

## Flag Parsing in the CLI Entry Point

In `plugins/codex/scripts/codex-companion.mjs`, the command-line interface defines three mutually exclusive Boolean options: `--resume`, `--resume-last`, and `--fresh`.

The parsing logic collapses the user-facing `--resume` flag into the internal `--resume-last` behavior:

```js
const resumeLast = Boolean(options["resume-last"] || options.resume);
if (options.fresh && resumeLast) {
  throw new Error("Choose either --resume/--resume-last or --fresh.");
}

```

- **`--resume`** — Convenience alias that activates `--resume-last`
- **`--resume-last`** — Internal flag that triggers actual job lookup
- **`--fresh`** — Explicitly disables resumption, forcing a new task

The CLI enforces exclusivity: combining `--fresh` with either resume flag throws an immediate error.

## Dispatch to the Task Sub-Command

When users execute:

```bash
node scripts/codex-companion.mjs task [--resume|--resume-last] "follow-up prompt"

```

the runtime performs **flag stripping and normalization** before invoking the job-control layer:

| User Input | Normalized Command | Flag in LLM Prompt? |
|------------|-------------------|---------------------|
| `--resume` | `task --resume-last` | No (stripped) |
| `--resume-last` | `task --resume-last` | No (stripped) |
| `--fresh` | `task` | N/A |

This normalization happens in `plugins/codex/scripts/codex-companion.mjs` before the request reaches `plugins/codex/scripts/lib/job-control.mjs`.

## Job Lookup and Thread Attachment

The `task` command implementation in `job-control.mjs` consults the persisted state managed by `state.mjs`. When `--resume-last` is present, the resumption logic executes three steps:

1. **Query** the latest job entry matching:
   - Current Claude session ID
   - Status not marked as finished

2. **Attach** the new prompt to the matched job's thread, preserving full conversation history for the LLM

3. **Fallback** to fresh task creation if no qualifying job exists (no error raised for missing resume targets)

The state persistence in `plugins/codex/scripts/lib/state.mjs` records job metadata including session identifiers, timestamps, and completion status—enabling this cross-invocation lookup.

## Session Safety Guarantees

The test suite in `tests/runtime.test.mjs` validates critical isolation properties:

- **Session-scoped resumption** — Only jobs from the initiating Claude session are eligible
- **Running job exclusion** — Active jobs from other sessions are ignored regardless of timestamp
- **Deterministic alias behavior** — `--resume` and `--resume-last` produce identical runtime effects

These constraints prevent accidental cross-session interference in multi-user or long-running environments.

## Skill Integration

Per [`plugins/codex/skills/codex-cli-runtime/SKILL.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/skills/codex-cli-runtime/SKILL.md), skills generate commands using the simplified `--resume` flag:

```markdown
- "keep going" → emit: `task --resume`
- "dig deeper" → emit: `task --resume`
- "apply the top fix" → emit: `task --resume`

```

The runtime automatically converts these to `--resume-last` before job execution, keeping skill definitions clean while maintaining internal consistency.

## Usage Examples

```bash

# Continue the most recent thread (recommended user syntax)

codex-companion task --resume "finish the implementation"

# Explicit internal flag (identical behavior)

codex-companion task --resume-last "finish the implementation"

# Force new task, ignore history

codex-companion task --fresh "analyze a different module"

```

Inside skill definitions, prefer `--resume` for readability; the runtime handles normalization.

## Summary

- **`--resume`** is a convenience alias that the CLI expands to `--resume-last` before dispatch
- **`--resume-last`** triggers lookup of the latest non-finished job in the current Claude session via `state.mjs`
- **Flag stripping** ensures resume directives never appear in LLM prompts
- **Session isolation** prevents resuming jobs from other Claude sessions
- **`--fresh`** explicitly disables all resumption behavior

## Frequently Asked Questions

### What happens if I use `--resume` without any previous jobs?

The request processes as a fresh task. The implementation does not raise an error when no matching resume target exists—it simply starts a new job thread.

### Can I resume a job from a different Claude session?

No. The `job-control.mjs` implementation filters by the current session ID stored in the state file. Jobs from other sessions are never considered for resumption.

### Why are there two flags if they do the same thing?

`--resume` provides user-facing clarity, while `--resume-last` names the internal mechanism explicitly. The dual naming allows skills to use intuitive language (`--resume`) while the runtime maintains precise semantics.

### Does `--resume` appear in the LLM's prompt context?

No. The CLI strips both `--resume` and `--resume-last` from the prompt text before forwarding to the task runner, ensuring the LLM receives only the substantive instruction.