When to Use Read-Only Sandbox Mode with the Codex Plugin

Use read-only sandbox mode when you need Codex to analyze, review, or diagnose code without modifying files, and switch to write-capable mode only when you explicitly want Codex to apply patches or generate new code.

The openai/codex-plugin-cc repository provides a ChatGPT plugin that integrates Codex into your development workflow. Understanding when to use read-only sandbox mode versus write-capable execution is critical for safe, effective AI-assisted coding. This guide explains the specific scenarios where sandbox mode protects your codebase while delivering valuable insights based on the actual source implementation.

What Is Read-Only Sandbox Mode?

According to the source code in README.md and plugins/codex/skills/codex-cli-runtime/SKILL.md, Codex operates in two distinct execution styles:

Read-only (sandbox) mode runs Codex in an isolated environment that only inspects code. It never edits, creates, or deletes files. Write-capable mode grants Codex permission to modify the repository, apply patches, and generate new implementations.

The plugin architecture treats read-only as the safe default for analysis tasks. The documentation in README.md explicitly states that /codex:review "will not perform any changes" and marks /codex:adversarial-review as read-only commands that "do not fix code."

When to Use Read-Only Sandbox Mode

Use read-only sandbox mode in the following scenarios:

Code Quality Reviews When running /codex:review to analyze current changes without risking unintended edits. This command is read-only by design, guaranteeing zero file modifications while providing feedback on your code.

Adversarial and Design Critiques For architecture discussions and challenging design decisions using /codex:adversarial-review. The sandbox ensures Codex only critiques trade-offs and potential bugs without applying automatic fixes.

Exploratory Diagnosis When investigating failing tests or flaky behavior without immediate remediation. Run /codex:rescue without the --write flag to get diagnostics first, or use /codex:review to understand the problem before allowing modifications.

Security-Sensitive Repositories In production environments where accidental writes could be harmful. Sandboxing isolates Codex to analysis only, preventing any code changes in critical systems.

Background CI Jobs When executing /codex:review --background in continuous integration pipelines. The background job remains read-only, allowing you to monitor status or cancel without worrying about repository mutations.

How to Invoke Read-Only vs. Write Mode

The invocation method determines which mode Codex uses:

Read-Only Commands

• /codex:review – Analyzes changes without writing
• /codex:adversarial-review – Provides critiques only
• Any codex command without the --write flag

Write-Capable Commands

• /codex:rescue --write – Applies fixes and patches
• Any command with explicit --write flag

As documented in plugins/codex/skills/codex-cli-runtime/SKILL.md, the default behavior adds --write unless the user explicitly requests read-only behavior. However, review-related commands override this default to remain sandboxed.

Practical examples:

# Read-only review (safe default)

/codex:review

# Read-only adversarial critique

/codex:adversarial-review "challenge the caching strategy"

# Background read-only review for CI

/codex:review --background

# Write-capable rescue (explicit permission required)

/codex:rescue --write "fix the failing test"

# Read-only rescue (diagnostics only)

/codex:rescue "investigate the flaky test"

Key Implementation Files

The sandbox behavior is defined across several configuration files:

README.md – Lists all slash commands and explicitly marks which are read-only, documenting that review commands "will not perform any changes."

plugins/codex/skills/codex-cli-runtime/SKILL.md – Describes the default --write behavior and specifies when read-only is forced for safety.

plugins/codex/agents/codex-rescue.md – Shows the default write-capable mode for rescue operations, with exceptions for explicit read-only requests.

plugins/codex/skills/gpt-5-4-prompting/references/codex-prompt-recipes.md – Notes that diagnosis and fix-oriented recipes run in write mode by default unless the user explicitly asks for read-only behavior.

Summary

• Read-only sandbox mode is the safe default for review commands like /codex:review and /codex:adversarial-review.
• Use sandbox mode whenever you need analysis, design critique, or diagnostics without file modifications.
• Add --write explicitly only when you want Codex to apply fixes, refactor code, or generate new files.
• Background jobs and CI pipelines should use read-only mode to prevent accidental repository mutations.
• Review commands in README.md are hardcoded as read-only, while rescue operations default to write-capable unless the flag is omitted.

Frequently Asked Questions

How do I know if a Codex command will modify my files?

Check whether you included the --write flag. According to the source code in plugins/codex/skills/codex-cli-runtime/SKILL.md, the default behavior adds --write unless explicitly overridden. However, /codex:review and /codex:adversarial-review are permanently read-only regardless of flags, as documented in README.md.

Can I switch from read-only to write mode mid-session?

You cannot upgrade a running sandbox session to write mode. If you started with /codex:review and want Codex to apply fixes, you must issue a new command with the --write flag, such as /codex:rescue --write, to grant file modification permissions.

Is read-only mode slower than write mode?

No performance difference exists between modes. The sandbox restriction is a permission boundary, not a computational overhead. The read-only mode simply prevents the file system from receiving write operations while maintaining the same analysis speed.

What happens if I run a rescue command without --write?

Running /codex:rescue without the --write flag executes the command in read-only sandbox mode. As noted in plugins/codex/agents/codex-rescue.md, this allows Codex to diagnose issues and explain solutions without applying patches, giving you the opportunity to review the planned changes before committing to them.

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