local-codex git:20261021.4f94683A

Immutable. This exact content never changes and is served at /api/v1/blob/e9e3f77f21a63fda.

---
name: local-codex
description: >-
  Launches and manages the local OpenAI Codex CLI as a non-interactive coding sub-agent via ChatGPT
  OAuth, never API keys. Use to delegate coding tasks to Codex, run codex exec, generate or
  refactor code, or get a Codex code review; phrases like 'codex', 'run codex', 'codex exec',
  'delegate to 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](references/oauth-guide.md) and follow its [recovery recipe](references/oauth-guide.md#remote-account-switch-and-expired-login-recovery). 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](references/oauth-guide.md#bind-refresh-ownership-before-native-queries); a nominally read-only query can refresh credentials.

## 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` — whatever is first on PATH. **This is the build the surrounding
   environment actually runs**, so it is the right default: npm global installs under
   nvm (`~/.nvm/versions/node/*/bin/codex`) resolve here.
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**, not `codex --version`: the bare command always resolves the PATH copy, 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
```

Two builds on one machine is the normal state, not an anomaly.

## Usage Patterns

### 1. Basic exec (single task)

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

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

### 2. Code review

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

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

### 3. Check status

```bash
python3 scripts/codex_wrapper.py status
```

## Output Format

The wrapper returns JSON with:
- `success`: bool
- `exit_code`: int
- `elapsed_seconds`: float
- `stdout`: raw output
- `stderr`: error stream (truncated)
- `parsed_jsonl`: parsed JSONL events (if --json)
- `final_message`: extracted assistant text (if available)

## Parameters

| Parameter | Default | Options |
|-----------|---------|---------|
| model | `gpt-5.5` | `gpt-5.5`, `gpt-5.5-pro`, `o4-mini`, etc. |
| sandbox | `workspace-write` | `read-only`, `workspace-write`, `danger-full-access` |
| timeout | 300 | seconds (increase for large tasks) |
| json_output | true | always true (wrapper parses JSONL) |

## 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:
```bash
# First step
codex exec --ephemeral "Step 1..."
# Later
codex exec resume --last "Step 2..."
```

The wrapper currently runs single-shot exec. For multi-step workflows, use raw `codex exec` commands.

## 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.
- `codex doctor` works and is the first thing to run when Codex misbehaves. Run it **without** `--summary` — `--summary` cuts reachability down to a bare `✗ reachability ... unreachable` line (it actually prints twice, once under Notes and once under Connectivity) with no host and no remedy, in both the fail and the warning state. The full form names the host, the endpoint statuses, and a `→ check proxy, ...` remedy line, likewise in both states; what differs between fail and warning is which endpoint failed and whether it is marked `(required)`. For `--json`, everything lives under `checks["network.provider_reachability"]`: `details` maps endpoint → status, and `issues` is a list whose objects carry `severity` / `cause` / `measured` / `expected` / `remedy` / `fields` (the last three are optional). Two traps: there is **no top-level `issues` key at all** — do not write `report["issues"]` (KeyError) or `report.get("issues")` (silently None); and a check's own `issues` key is **omitted entirely when empty** rather than sent as `[]`, so `check.get("issues")` returns None for the 20+ checks that have nothing to report. Top level has exactly 5 keys, `generatedAt` is a string like `"1790057704s since unix epoch"` rather than a timestamp, and exit 1 fires on **any** failed check, not just reachability — `rollout_db_parity` is ⚠ on this install, and if it ever flips to fail it turns that exit code red for a reason unrelated to your network, which is what gates like `codex-1m-context-window-setup`'s `returncode == 0` check read. Verified 2026-09-22 on 0.155.1 (npm) and 0.155.0-alpha.9.2 (ChatGPT.app-bundled); the remedy wording quoted here is specific to those builds — upstream has since changed it.
- Environment variables are NOT inherited into Codex's sandbox; pass via config or prompt
- Large file operations may need increased timeout