# Put Claude in charge of Codex and Grok: implementation spec for an AI agent

Source: https://jacobkunselman.com/tips/claude-orchestrates-codex-and-grok/ (AI tips, No. 2, 2026-09-25)

You are an AI coding agent, most likely Claude Code. Your user has Codex (the OpenAI Codex
CLI, on a ChatGPT plan) and Grok Build (xAI's CLI) as well as you. Set up a split where YOU
orchestrate: you write the spec, dispatch work headlessly to the other two, and review
everything they return. The reference files are in `reference/` next to this file. Adapt the
paths; keep the rules.

## Prerequisites (check, don't assume)

- `codex --version` works and `codex login status` shows it is signed in. **Use the plan
  login, not an API key**, unless the user wants per-token API billing.
- The Grok Build CLI is installed (the reference expects `~/.grok/bin/grok`) and signed in.
- Neither CLI is ever started in interactive mode from a tool call. Headless only.

## Components

1. **Routing rules in the user's `CLAUDE.md`.** Copy `reference/claude-md-routing.md` in
   (global `~/.claude/CLAUDE.md` for every project, or a project's own). Grok Build loads
   `CLAUDE.md` and `AGENTS.md` too, so both agents read the same rules.
2. **The Grok bridge**: `reference/ask-grok.sh` plus `reference/_render.py`, in one folder
   with an `exchanges/` subfolder.
   - Read-only by default: `--tools read_file,grep,list_dir`. `--write` adds
     `search_replace,run_terminal_cmd` and `--permission-mode bypassPermissions`; `--web` adds
     `web_search,web_fetch`.
   - `--output-format json`; `_render.py` prints the answer, prints a receipt (model, cost,
     session id) to stderr, and writes `exchanges/<stamp>-grok.md` with the prompt, the
     answer and the cost.
   - The timeout defaults to 110 s, under the caller's 120 s Bash default, so a slow consult
     fails with a message instead of being killed silently. `--timeout N` for heavy asks.
   - `--resume <session-id>` continues a thread.
3. **The Codex call** (no wrapper needed):
   ```sh
   timeout 1800 codex exec --sandbox workspace-write --skip-git-repo-check \
     "$(cat task.md)" < /dev/null > codex-<task>.log 2>&1
   ```
   Run it in the background and read the log when it exits. `-c model_reasoning_effort=high`
   sets reasoning per run; `-i image.png --` attaches an image before the prompt.
4. **The worker-call template**: `reference/worker-call-template.md`. Every call carries all
   six parts: a spec file by path, the exact output path, an emphasis, acceptance commands,
   the no-questions line and the no-git line.

## Rules

1. **Route by the work, not the price.** Plan, spec and final review: you, never delegated.
   Specified build: Codex. Research, second opinions, adversarial reads: Grok. Physical or
   irreversible (print, push, purchase): the human.
2. **Review everything.** Run the acceptance commands yourself and look at the output (render
   it if it is visual). A worker's own "all checks passed" does not count as the review.
3. **No worker commits.** Say so in every prompt and verify with `git status` / `git log`
   afterwards. Only the session commits.
4. **Escalation:** Grok first, in parallel batches. Codex for what Grok couldn't fix, one at a
   time. The most expensive model last, with the user's approval.
5. **Keep the spec in a file.** The prompt names the file; never paste the spec into the prompt.
6. **Log and meter.** Every exchange is logged with its cost. Failed calls usually aren't, so
   treat the remaining budget as smaller than the logs say.

## Pitfalls (each cost real time)

- `codex exec` with stdin open prints `Reading additional input from stdin...` and waits
  forever. Always `< /dev/null`.
- Without the no-questions line, a headless worker stops to ask and delivers nothing.
- Permission modes that ask will hang headless. Use tool allowlists.
- A read-only worker told to write a file spends its turns reading and dies with
  `max turns reached`. Pass `--write` when the deliverable is a file, and raise `--max-turns`
  (80) for write-and-check work. Grok's write tools have no create-file tool: tell it to create
  new files with a heredoc through the terminal.
- Don't `pgrep -af` or `pkill -f` a running codex: its whole prompt is in its argv, and the
  pattern also matches the shell running pkill, which kills your own command.
- A higher reasoning setting on a tightly specified build buys self-checking, not quality.

## Acceptance tests

1. `ask-grok.sh "What is in this directory?"` (from a repo) answers, prints a cost receipt,
   and writes one file to `exchanges/`.
2. `ask-grok.sh "Create a file named probe.txt"` without `--write`: no `probe.txt` exists
   afterwards.
3. `ask-grok.sh --timeout 5 "Summarise every file here in detail"` fails with the TIMED OUT
   message and exit code 124, not a hang.
4. A Codex call using the template, told to write `out/hello.py` that prints "ok", with the
   acceptance command `python3 out/hello.py`: the file exists, the command prints ok, and
   `git log` shows no new commit from the worker.
5. The routing block is in `CLAUDE.md`, and a fresh Grok session asked "who does specified
   builds here?" answers "Codex".