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

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:

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:

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, skills generate commands using the simplified --resume flag:

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

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

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