local-codex

Local Codex

Delegate coding tasks to the local OpenAI Codex CLI agent using the authorized ChatGPT account's OAuth access.

When to Use

• User wants to generate, refactor, or review code via Codex
• User wants to run codex exec for non-interactive tasks
• User wants to use Codex's GPT-5.5 agent capabilities
• User mentions "codex", "run codex", "delegate to codex"

Authentication (ChatGPT OAuth)

CRITICAL: Use ChatGPT OAuth through the selected credential store. Do NOT set OPENAI_API_KEY or pass API keys for this workflow. Keep the authentication route separate from the account's allowance and extra Credit policy; OAuth does not guarantee that long work cannot consume extra Credit.

• Resolve the actual CODEX_HOME and store; the desktop app and CLI can share credentials.
• Before login, account switching or token recovery, read the OAuth guide and follow its recovery recipe. Use fresh empty stores for independent grants, retain explicitly authorized single-owner transfers, and verify actual access and existing-process adoption separately.
• Before a native quota query, read refresh ownership; a nominally read-only query can refresh credentials.
• For quota-driven continuation on another authorized account, use the included-usage check before substantial execution; cached login or a new default file is not that check.

Codex CLI Path

The skill auto-detects Codex CLI in this order:

1. CODEX_BIN env var, if set — explicit override. A non-executable path fails loudly instead of silently falling through to a different build (that would make whatever the wrapper measured unattributable).
2. which codex — the executable first on the wrapper process's PATH, including npm global installs under nvm (~/.nvm/versions/node/*/bin/codex). This lookup does not execute an interactive shell's alias or function.
3. /Applications/ChatGPT.app/Contents/Resources/codex — the copy bundled inside ChatGPT.app, fallback only. Its version tracks the Desktop app and can diverge from the npm build, so it is deliberately last.

If a bad CODEX_BIN was set, the wrapper exits 1 with {"error": "CODEX_BIN not executable", "path": <value>} — the offending value is in the error itself, and searched_paths is not emitted for this case (no other search step ran). If neither PATH nor the app bundle has a codex, the wrapper exits 1 with the actual search order in searched_paths.

Whichever binary wins, attribute behaviour to it by versioning the binary that ran. An unrelated shell's codex --version may resolve another entry, which is the wrong build to quote when the fallback picked the app-bundled one. Use the codex_path field from the wrapper's status output:

"<codex_path from status output>" --version

Before using this wrapper, resolve the user's ordinary CLI entry. When that entry is a shell function or launcher supplying network/auth context, use it through its owning shell instead of silently substituting the discovered binary. On macOS zsh, inspect with /bin/zsh -lic 'command -v codex; codex --version', then run codex inside that same shell mode. Put the finite timeout around the shell process: gtimeout … codex resolves an executable and cannot call a shell function. The bundled Python wrapper does not reproduce shell initialization or support every native flag; use native CLI invocation when those capabilities are required.

Usage Patterns

1. Basic exec (single task)

python3 scripts/codex_wrapper.py exec "<prompt>" [<workdir>] [<model>] [<sandbox>] [<timeout>]

Example:

python3 scripts/codex_wrapper.py exec \
  "Write a Python function to calculate fibonacci" \
  /tmp \
  gpt-5.5 \
  workspace-write \
  300

2. Code review

python3 scripts/codex_wrapper.py review [<workdir>] [<model>] [uncommitted:true] [<timeout>]

Example:

python3 scripts/codex_wrapper.py review \
  /path/to/repo \
  gpt-5.5 \
  true \
  300

3. Inspect cached login

python3 scripts/codex_wrapper.py status

Interpret this result using cached login inspection. For an authorized real access check, follow that guide's Verification route.

Parameters and results

The command arguments, defaults and JSON fields are defined by main(), exec_codex(), review_codex() and check_auth_status() in scripts/codex_wrapper.py. Use those definitions rather than a second parameter or output-field table.

Safety Notes

• sandbox=read-only for analysis/review tasks (no file writes)
• sandbox=workspace-write for code generation (writes to working dir)
• sandbox=danger-full-access only when explicitly needed (full system access)
• Always use --skip-git-repo-check when running outside git repos
• Use --ephemeral for one-off tasks (no session persistence)

Session Management

For multi-step tasks, Codex supports session resume:

# First step
codex exec --json "Step 1..."
# Later, use the session ID reported by that first invocation:
codex exec resume "${CODEX_SESSION_ID:?Set the session ID from the first invocation}" "Step 2..."

The wrapper currently runs single-shot exec. For multi-step workflows, use raw codex exec commands. An ephemeral invocation does not persist a session for later resume. Use --last only after confirming that the most recent recorded session is the intended target.

Limitations

• Remote login can use device authorization with a browser on another machine; follow the OAuth guide instead of requiring a desktop app on the remote host.
• Inspect the selected binary's doctor --help before using its diagnostics; when supported, use the full report for endpoint/remedy details rather than --summary. Interpret the failed check, not only the aggregate exit code, and read the emitted JSON schema instead of assuming an older build's keys.
• Shell environment inheritance follows the selected build's shell_environment_policy; inspect the effective configuration. Keep credentials out of prompts.
• Large file operations may need increased timeout