collaborating-with-codex

# Collaborating with Codex

Use Codex CLI as an independent collaborator while the primary agent remains responsible for verification, synthesis, and final user-facing decisions.

The bridge script (`scripts/codex_bridge.py`) wraps `codex exec` in JSON mode, streams progress to stderr, returns structured JSON, and manages multi-turn continuity via `SESSION_ID`.

In Claude Code, run bridge calls in the background by default for non-trivial tasks:

```text
Bash tool call:
  command: python3 <skill_dir>/scripts/codex_bridge.py --cd "/project" --PROMPT "Analyze auth flow in src/auth/"
  run_in_background: true
```

`run_in_background` is a host tool parameter, not a shell argument. Use the host's task-output view to monitor timestamped stderr progress, commands Codex ran, response previews, stalls, and completion.

## Safety model

Default to read-only delegation:

- `--sandbox read-only` - default; use for review, diagnosis, research, and second opinions.
- `--sandbox workspace-write` - use only after write access is appropriate; prefer an isolated worktree under `/tmp`.
- `--sandbox danger-full-access` - use only in an externally sandboxed environment.
- `--bypass-sandbox` - forwards Codex's dangerous bypass flag; requires explicit user consent.
- `--full-auto` - deprecated bridge compatibility alias only; maps to `workspace-write` and is not forwarded to Codex CLI.

Do not hand secrets, private keys, production data, or irreversible operations to Codex.

On a new host, probe sandbox support once with `codex sandbox -- true` (exit 0 means healthy). If sandboxed commands all fail with exit 182, the host kernel cannot enforce Codex's sandbox (common under containers, PRoot, and older WSL); the bridge warns when it sees this signature. On such hosts, delegate only from an externally sandboxed environment using `--sandbox danger-full-access` with explicit user consent.

## Network access and approvals

`codex exec` is non-interactive: nothing can be approved mid-run. Actions that would prompt simply fail and the failure is returned to the model. Every authority decision is made up front by the primary agent through `--sandbox`, `--add-dir`, `--search`, and `--network` — get user consent before granting anything beyond read-only. `-a on-request` and `-a untrusted` therefore add nothing in bridge calls; use `-a never` or omit the flag.

Codex has two separate network paths:

- Web search: without `--search`, Codex's `web_search` tool answers from an OpenAI-maintained cached index and fetches no live pages. `--search` switches it to live search with no per-call approval, so passing the flag is itself the approval.
- Shell network (`curl`, `pip`, `npm`): blocked in both `read-only` and `workspace-write`. Grant it only when the task needs it (dependency installs, integration tests) via `--sandbox workspace-write --network`, preferably in an isolated worktree.

## Quick start

Backticks in prompts trigger shell command substitution. Use a single-quoted heredoc; see `references/shell-quoting.md`.

```bash
PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"

python3 skills/collaborating-with-codex/scripts/codex_bridge.py \
  --cd "." \
  --PROMPT "$PROMPT"
```

For large or generated handoffs, write the prompt under `/tmp` and avoid argv and shell-quoting limits:

```bash
python3 skills/collaborating-with-codex/scripts/codex_bridge.py \
  --cd "." \
  --prompt-file /tmp/codex-prompt.md
```

Typical response:

```json
{
  "success": true,
  "SESSION_ID": "019...",
  "agent_messages": "Findings...",
  "commands_ran": 2
}
```

For long-running calls, run the command in the host's background-command mode when available, then monitor stderr progress and the final JSON result.

## Multi-turn sessions

Capture `SESSION_ID` from the first response and pass it back:

```bash
python3 skills/collaborating-with-codex/scripts/codex_bridge.py \
  --cd "." \
  --PROMPT "Analyze the bug in foo()."

python3 skills/collaborating-with-codex/scripts/codex_bridge.py \
  --cd "." \
  --SESSION_ID "<id>" \
  --PROMPT "Now propose the smallest safe fix."

python3 skills/collaborating-with-codex/scripts/codex_bridge.py \
  --cd "." \
  --last \
  --PROMPT "Check edge cases before finalizing."
```

## Bridge flags

| Flag | Purpose | Default |
|---|---|---|
| `--PROMPT` | Prompt text | required unless `--prompt-file` is used |
| `--prompt-file` | Read prompt from a file and stream it to Codex stdin | off |
| `--stdin-file` | Pipe an additional context file while using `--PROMPT` | off |
| `--cd` | Workspace root passed to Codex | required |
| `--SESSION_ID` | Resume a previous session | new session |
| `--last` | Resume the most recent session | off |
| `--resume-all` | With resume, disable Codex cwd filtering | off |
| `--model` | Override Codex model | CLI default |
| `--sandbox` | `read-only`, `workspace-write`, or `danger-full-access` | `read-only` |
| `-a`, `--ask-for-approval` | `untrusted`, `on-request`, `never`, or deprecated `on-failure` | CLI default |
| `--profile` | Load a Codex config profile | off |
| `-c`, `--config` | Override Codex config values | none |
| `--enable`, `--disable` | Toggle Codex feature flags | none |
| `--image` | Attach image files; repeatable | none |
| `--add-dir` | Additional writable directories | none |
| `--skip-git-repo-check` | Allow non-git directories | on |
| `--require-git-repo` | Disable the default non-git allowance | off |
| `--ephemeral` | Do not persist session files | off |
| `--bypass-sandbox` | Forward Codex dangerous bypass flag | off |
| `--bypass-hook-trust` | Forward Codex dangerous hook-trust bypass flag | off |
| `--search` | Enable live web search by forwarding top-level `codex --search` before `exec` | off |
| `--network` | Allow shell network in the workspace-write sandbox (`sandbox_workspace_write.network_access=true`) | off |
| `--oss`, `--local-provider` | Use OSS/local provider mode | off |
| `--i