/collaborating-with-codex

name: collaborating-with-codex
description: Delegate tasks to Codex CLI for prototyping, debugging, code review, implementation handoff, cross-model second opinions, and multi-turn Codex sessions via SESSION_ID.
metadata:
  short-description: Delegate to Codex CLI

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`.

Commands below write `<skill_dir>` for the absolute path of the directory containing this SKILL.md. Your harness usually reports that path when it loads the skill. If it does not, use this SKILL.md's own location. Substitute it before running, for example `~/.claude/skills/collaborating-with-codex`.

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

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.

Host-side approval (the bridge call itself)

Everything above governs the child Codex. The **host** agent's own permission layer gates the `python3 … codex_bridge.py` Bash call first — and under classifier-gated auto-approval (Claude Code `auto`/`dontAsk`, Codex non-interactive runs), a long-running script that spawns another agent over the codebase pattern-matches "high-risk" and can be **denied silently**: the delegation never starts. A host permission error instead of bridge JSON means the host blocked the bridge, not that Codex failed.

• **Pre-authorize the bridge instead of relying on the classifier.** Claude Code host: add `"Bash(python3 *collaborating-with-codex*bridge.py*)"` to `permissions.allow` in your `settings.json`. The wildcard form keeps matching wherever the skill is installed. Sandboxed hosts also need `"python3 *collaborating-with-codex*bridge.py*"` in `sandbox.excludedCommands`, because sandbox network policy blocks the child CLI's API traffic even after the command is allowed. Install and approval runbooks: [docs/setup/](https://github.com/appautomaton/agent-designer/tree/main/docs/setup) in the source repo.
• **Codex host: the sandbox is the second gate.** The child `codex` CLI needs API network, which the host sandbox blocks in `read-only` and `workspace-write`. Run the bridge call through an approved escalation, or knowingly grant network for that call.
• **Never degrade silently.** If the host denies the bridge call, report it and propose the allowlist fix — don't substitute your own answer for the independent second opinion that was requested.

Quick start

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

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

python3 <skill_dir>/scripts/codex_bridge.py \
  --cd "." \
  --PROMPT "$PROMPT"

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

python3 <skill_dir>/scripts/codex_bridge.py \
  --cd "." \
  --prompt-file /tmp/codex-prompt.md

Typical response:

{
  "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