Codex exec automation

Codex Exec Automation

Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.

Use this skill for non-interactive Codex CLI work: codex exec, codex e, codex exec resume, codex exec review, top-level codex review, JSONL event streams, final-message capture, output schemas, prompt stdin, images, cwd selection, and CI-like checks.

Inspect First

Before relying on a flag, verify the installed CLI:

python3 "$PLUGIN_ROOT/scripts/codex_cli_inspector.py" --commands exec review doctor --json

If the user supplied a binary path, pass --codex "$CODEX_CLI_PATH".

Command Assembly

Build commands from these decisions, in this order:

1. Working root: use -C <repo> or run from the intended repository.
2. Autonomy: choose --sandbox and --ask-for-approval.
3. Config stack: add --profile, -c key=value, --enable, --disable, or --strict-config only when needed.
4. Prompt input: pass a short prompt argument, read from stdin with -, or pipe a structured prompt.
5. Output contract: use --json, --output-schema <file>, or -o <file> when automation must parse results.
6. Persistence: use --ephemeral only when the run should not persist session files.

Common safe patterns:

codex exec -C "$PROJECT" --sandbox workspace-write --ask-for-approval on-request "Implement the requested fix and run targeted tests."
codex exec -C "$PROJECT" --sandbox read-only --ask-for-approval never --json "Inspect this repo and report risks only."
codex review -C "$PROJECT" --uncommitted
codex review -C "$PROJECT" --base main
codex exec resume --last "Continue from the last non-interactive session and verify the fix."

For prompts that contain shell metacharacters, quotes, YAML, JSON, or long instructions, prefer stdin:

codex exec -C "$PROJECT" --sandbox workspace-write --ask-for-approval on-request - < prompt.md

Review Runs

Use codex review when the user asks for code review findings, changed-file risk, commit review, base-branch comparison, or uncommitted changes. Choose one review target:

• --uncommitted for staged, unstaged, and untracked changes.
• --base <branch> for branch diff review.
• --commit <sha> for one commit.

Keep custom review instructions narrow and actionable. Do not ask codex review to implement fixes; run a separate codex exec task if the user wants changes.

Output Handling

Use --json for event streams and parse line-by-line. Do not load large JSONL streams into memory as one array.

Use --output-schema <file> when downstream automation needs a typed final answer. Keep schemas small, explicit, and versioned.

Use -o <file> when the last assistant message should be saved for a report or handoff. Keep output files inside the intended workspace or an ignored output directory.

Safety Boundaries

• Do not use dangerous bypass flags unless the user explicitly selected an external sandbox boundary.
• Do not use --ignore-user-config, --ignore-rules, or --skip-git-repo-check casually. Explain what safety or reproducibility check is being bypassed.
• Do not pass secrets in prompt arguments. Use existing environment variables or ignored local files only when the user already owns that setup.
• For CI, prefer read-only or workspace-write with --ask-for-approval never; do not rely on interactive approval prompts.
• For network-dependent tasks, state whether web search, command network access, or both are required. They are separate concerns.

Failure Triage

If a run fails:

1. Re-run the relevant --help check if the error mentions an unknown flag.
2. Check codex doctor --summary --ascii for installation/config/auth/runtime issues.
3. If a persisted session exists and the failure is unclear, use codex-log-reader to inspect the rollout file safely.
4. Reduce to a read-only inspection prompt before retrying an automated edit.

Completion Standard

Report the exact command used or recommended, the sandbox and approval policy, the cwd, whether session persistence was enabled, the output file/schema if any, and the verification result or blocker.