How to Refactor Code with the Codex Plugin: A Complete Guide

To refactor code with the Codex plugin, initiate a rescue job using /codex:rescue, monitor its progress with /codex:status, retrieve the transformed code via /codex:result, and validate the changes with /codex:review—all without leaving your Claude Code environment.

The openai/codex-plugin-cc repository delivers a set of slash commands that integrate the Codex model directly into Claude Code. By leveraging these commands, you can offload heavy refactoring tasks to the Codex API while the plugin handles authentication, session persistence, and background job management automatically.

Step 1: Initiate a Rescue Job

The /codex:rescue command is the primary mechanism to refactor code with the Codex plugin. This command packages your repository state, sends a natural-language prompt to the Codex API, and returns a transformed version of your code.

According to the command documentation in plugins/codex/commands/rescue.md, you can specify the target scope, model, and effort level:

/codex:rescue --model gpt-5.4-mini --effort high \
  "Refactor src/utils.js to use async/await and improve error handling"

For larger refactoring tasks, add the --background flag to run the job asynchronously. This prevents blocking your Claude Code session while the Codex model processes the changes.

Step 2: Monitor Progress and Retrieve Results

While a background job runs, query its status using /codex:status. This command reads from the state management system implemented in plugins/codex/scripts/lib/state.mjs, which tracks job IDs, timestamps, and execution status.

Once complete, view the generated code with /codex:result. The output includes transformed source files and a codex resume <session-id> token that allows you to reopen the exact generation session in the Codex web app for manual tweaks. The status and result command definitions live in plugins/codex/commands/status.md and plugins/codex/commands/result.md respectively.

Step 3: Validate the Refactor

After applying the changes to your working tree, run a read-only review to catch regressions. The /codex:review command (documented in plugins/codex/commands/review.md) analyzes the diff and suggests improvements. For more rigorous validation, use the steerable variant /codex:adversarial-review to explicitly test for edge cases and potential bugs.

Technical Implementation Details

The plugin's core logic resides in plugins/codex/scripts/lib/codex.mjs, which constructs a JSON-RPC request containing your prompt, repository snapshot, and optional model parameters. The Codex backend returns a structured patch that the plugin applies automatically, or leaves pending if you used --background.

Because the workflow relies entirely on slash commands, you never write boilerplate HTTP clients or handle token management manually—the plugin manages environment detection and API authentication for you.

Complete Workflow Example

Here is a typical command sequence for refactoring a module:

# Start a background refactor job

/codex:rescue --model gpt-5.4-mini --effort high --background \
  "Refactor src/utils.js to use modern ES2022 syntax, replace callbacks with promises, and add JSDoc comments"

# Check job status

/codex:status

# View the generated diff once complete

/codex:result

# Run a read-only review to verify safety

/codex:review --background

# Check review status

/codex:status

# Inspect review output

/codex:result

For small files, omit --background to run commands synchronously and block until the model finishes.

Summary

• /codex:rescue initiates refactoring jobs with customizable model and effort parameters, as defined in plugins/codex/commands/rescue.md.
• /codex:status and /codex:result track background jobs and retrieve transformed code, utilizing state management from plugins/codex/scripts/lib/state.mjs.
• /codex:review provides automated validation of refactored code to catch regressions before committing.
• The core request building happens in plugins/codex/scripts/lib/codex.mjs, handling JSON-RPC serialization and authentication automatically.

Frequently Asked Questions

How do I run a refactor without blocking my Claude Code session?

Add the --background flag to your /codex:rescue command. This runs the job asynchronously, allowing you to continue working while the Codex model processes the request. Use /codex:status to check completion and /codex:result to retrieve the output.

What is the difference between /codex:review and /codex:adversarial-review?

/codex:review performs a standard read-only analysis of your refactored code to identify potential issues. /codex:adversarial-review is a steerable variant that specifically tests for edge cases, security vulnerabilities, and breaking changes, making it ideal for critical code paths.

Where does the Codex plugin store job state and session information?

Job metadata—including IDs, status, and timestamps—is tracked in plugins/codex/scripts/lib/state.mjs. This module persists session data locally, enabling you to resume workflows across Claude Code restarts and retrieve historical results using /codex:result.

Can I reopen a completed refactor session in the Codex web interface?

Yes. When you retrieve results via /codex:result, the output includes a codex resume <session-id> token. Copy this token into the Codex app to reopen the exact generation session for manual editing or additional iterations.

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