codex-consult

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codex Consult

Call Codex (GPT) non-interactively from Claude Code. Two modes of operation:

- **Consult**: Get a second opinion. Codex runs in explicit read-only mode (`-s read-only`). You wait for
  the response, synthesize it with your own perspective, and present both to the user.
- **Delegate**: Hand off independent work. Codex runs with `-s workspace-write`. You
  run it in the background and continue working. You review the output before reporting it done.

## Choosing the right mode

### Consult when:

- You want to validate an implementation plan before executing
- You want an independent perspective on a solution or architecture decision
- You're stuck on a problem and want a fresh approach from a different model
- You're weighing multiple approaches and want another perspective

### Delegate when:

- Writing tests for code you just wrote
- Implementing a component while you work on another
- Code review of completed work items
- Any independent task that doesn't depend on your in-progress work

### Do NOT delegate when:

- The task depends on something you're currently building (it will work against stale state)
- Multiple agents would edit the same file (merge conflicts are inevitable)
- The task requires your current conversation context (Codex starts cold)

## Codex basics

Codex reads `AGENTS.md` files automatically for project instructions (`~/.codex/AGENTS.md` for
global defaults, `<repo>/AGENTS.md` for project-specific). This is similar to CLAUDE.md for
Claude Code.

Sandbox modes in non-interactive (`codex exec`) mode:

| Mode | Flag | Behavior |
|------|------|----------|
| Read-only | `-s read-only` | Reads and read-only commands; writes blocked |
| Workspace-write | `-s workspace-write` | Allows workspace edits; approvals follow configuration |

Use explicit read-only for consultations, `-s workspace-write` for delegations.

Progress output goes to stderr, final result to stdout. The `-o` flag captures the final message
to a file for clean reading.

---

## Consult Mode

### Constructing the prompt

Every consultation prompt needs three parts:

**1. Role framing** -- Tell Codex it's acting as a consultant/reviewer.

**2. Context** -- Include relevant context directly in the prompt. Codex has filesystem access,
but providing key information upfront saves time and focuses the analysis. Include:
- The plan, solution, or problem description
- Relevant file paths to examine (Codex cannot use `@` file references in exec mode)
- Constraints or requirements the user has mentioned
- What you've already tried (if getting unstuck)

**3. Specific ask** -- Be precise about what feedback you want. Vague prompts get vague answers.

**Good**: "Review this migration plan. Specifically: (1) will the schema change be safe under
concurrent writes? (2) should any steps be reordered? (3) what's the rollback path if step 3 fails?"

**Bad**: "What do you think of this plan?"

### Running the consultation

Create a unique temp file, then run Codex in read-only mode (`-s read-only`):

```bash
out="$(mktemp /tmp/codex-consult.XXXXXX)"
cat <<'PROMPT' | codex exec -s read-only --ephemeral -o "$out" -
Your prompt here.
PROMPT
```

If you are NOT inside a git repository (e.g., reviewing files in ~/.claude/), add
`--skip-git-repo-check`.

To set a specific working directory (useful when running from a different context):

```bash
cat <<'PROMPT' | codex exec -s read-only --ephemeral -C /path/to/project -o "$out" -
Your prompt here.
PROMPT
```

To attach screenshots or images for UI-related consultations:

```bash
codex exec -s read-only --ephemeral -i screenshot.png -o "$out" "Review this UI and suggest improvements"
```

Flags:
- `-s read-only`: Explicitly block writes while allowing read-only commands. Do not rely on the
  configured default sandbox mode for consultations.
- `--ephemeral`: Don't persist the session (one-shot consultation).
- `-C <path>`: Set working directory explicitly.
- `-i <path>`: Attach image(s) for visual context.
- `--skip-git-repo-check`: Required when running outside a git repository.
- `-o "$out"`: Capture Codex's final response for clean reading.

Set the Bash tool timeout to 300000ms. Consultations typically take 30-120 seconds, but complex
codebase questions where Codex needs to read several files can take longer.

### Presenting consultation results

After Codex responds:

1. Read the output from the temp file, then delete it
2. Synthesize both perspectives. Don't just parrot Codex's response. Add your own analysis.

From rcedwards/blaude-bode, MIT.

More from rcedwards/blaude-bode