Difference Between --write and Read-Only Sandbox Mode in the Codex Plugin

The --write flag permits the Codex plugin to apply file modifications, while omitting it (or explicitly using --read-only) restricts Codex to inspection-only sandbox mode where no edits are generated.

The openai/codex-plugin-cc repository extends Claude Code with AI-powered coding assistance through two distinct execution modes. Understanding the difference between read-only sandbox mode and write-capable mode is essential for safely integrating automated code analysis and changes into your development workflow.

Read-Only Sandbox Mode Explained

Read-only sandbox mode prevents Codex from emitting any file-changing edits. When operating in this mode, Codex functions strictly as a code reviewer, diagnosing problems, researching solutions, or performing design analysis without modifying the repository.

You activate sandbox mode by either omitting the --write flag entirely or explicitly passing --read-only to commands. This mode guarantees that your repository remains unchanged regardless of what Codex discovers during analysis.

According to the source code in plugins/codex/skills/codex-cli-runtime/SKILL.md, the plugin automatically omits the --write flag when processing explicit read-only requests, ensuring that the underlying codex task invocation cannot generate patches.

Write-Capable Mode (--write)

Write-capable mode authorizes Codex to apply fixes, generate patches, and modify files in your repository. When you include the --write flag, the plugin forwards this parameter to the underlying codex task command, enabling edit-generating behavior.

This mode is appropriate when you want Codex to actively fix failing tests, refactor code, or implement features rather than merely suggest changes. The codex:rescue command specifically leverages this capability to apply automated fixes to your codebase.

Default Behavior and Automatic Flag Handling

The plugin implements specific logic to determine when to enable write capabilities automatically. As documented in plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 24-25), the default behavior varies by command type.

The internal safety rule states: "Default to write-capable Codex work in codex:codex-rescue unless the user explicitly asks for read-only behavior."

This means:

• codex:rescue automatically adds --write unless you explicitly request read-only behavior
• codex:review defaults to read-only operation and never modifies files

Practical CLI Examples

The following examples demonstrate how to invoke each mode from the command line:

# Read-only review (sandbox mode)

# Codex only inspects code without making changes

codex:review --background
codex:review --read-only

# Write-capable rescue (default behavior)

# The plugin automatically adds --write to the underlying invocation

codex:rescue fix the failing test

# Explicitly request write mode (same as default)

codex:rescue --write fix the failing test

Source Code References

The distinction between these modes is enforced in the following source files:

• plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 24-25): Defines execution rules for the rescue sub-agent, including the default --write handling logic
• plugins/codex/agents/codex-rescue.md (lines 34-35): Documents the rescue agent's default behavior regarding write capability
• README.md (line 99): Documents public slash commands and notes which commands operate in read-only mode

Summary

• Read-only sandbox mode restricts Codex to inspection and analysis without file modifications
• --write flag enables edit-generating behavior and allows file modifications
• codex:rescue automatically applies --write by default unless explicitly overridden with --read-only
• codex:review operates in sandbox mode by default for safe code analysis
• The plugin controls behavior by either including or omitting the --write flag in underlying codex task invocations

Frequently Asked Questions

Does codex:rescue use --write by default?

Yes. According to plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 24-25), the plugin automatically adds the --write flag to codex:rescue commands unless you explicitly request read-only behavior. This ensures the AI can apply fixes immediately when rescuing code.

How do I force read-only mode when using rescue commands?

You can force sandbox mode by explicitly adding the --read-only flag to your command. For example: codex:rescue --read-only analyze this bug. This instructs the plugin to omit the --write flag from the underlying invocation, preventing any file modifications.

What is the difference between codex:review and codex:rescue regarding file modifications?

codex:review always operates in read-only sandbox mode and only inspects code, as noted in README.md (line 99). In contrast, codex:rescue defaults to write-capable mode and can modify files to fix issues, unless you explicitly override this with --read-only.

Is it safe to run Codex in write-capable mode on production codebases?

While the --write flag enables automated fixes, you should treat it as potentially destructive. The documentation in plugins/codex/agents/codex-rescue.md (lines 34-35) establishes write capability as the default for rescue operations, but version control backups are recommended before allowing automated edits in production environments.

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