---
name: codex-heavy-lift
description: Delegate heavy implementation, bulk or mechanical work, and independent code review to ChatGPT Codex (`codex exec`) instead of doing it in the main session. Use by default for any substantial build, migration, sweep, test-authoring batch, or non-trivial review, and for important technical decisions that need a second opinion. Standing order from Carl until he says stop. Skip for small surgical edits.
---
# Codex heavy lift
Standing order (Carl, 2026-10-05): use Codex for heavy lifting as much as possible
until Carl says stop. The main Claude Code session stays the orchestrator and owns
every final decision. Codex's output is a claim, not proof.
## When to use it
- Large or wide builds: new modules, migrations, refactors, sweeps, test authoring.
- Independent review of a finished batch (a different model family, shares none of
our assumptions).
- A hard or important technical decision: get an independent opinion first.
- Two implementations are faster than one argument: have Codex build on its own
worktree or branch, then judge both.
Do not use it for small surgical fixes, one-line edits, or quick lookups.
## Workflow for important decisions
1. Ask for an independent opinion (Codex, or the second-opinion agent named in the
project's rules). Describe the symptom, not the answer you suspect.
2. Review the advice critically.
3. The main session makes the final decision.
4. Implement the change (delegate the heavy authoring to Codex when it is large).
5. Use Codex to review the final changes (`-s read-only`).
6. Fix the valid problems the review found; reject the invalid ones, with a reason.
7. Run the tests before finishing.
## How to call it
Always backgrounded, one shot; these runs take minutes. Never block on one.
```
codex exec --skip-git-repo-check -C
-o ""
```
- `-C` sets the working root. Writes are confined to it (plus `--add-dir` roots).
- `-o` writes the final message to a file; read it when the run completes.
- `-s read-only` for analysis and review that must not touch the tree.
- `-m ` to pin a model; unpinned uses the plan's current default.
- `resume --last` continues the previous session.
- Run it from Bash/PowerShell with `run_in_background: true`; put the outfile in the
session scratchpad.
Auth uses the OpenAI API key from the vault (`openai-api`). Set it before running:
```powershell
$raw = powershell -NoProfile -File C:\Projects\_General\vault\vault.ps1 get openai-api
$env:OPENAI_API_KEY = ($raw | Select-String 'key\s+sk-').ToString().Trim() -replace '^\S+\s+',''
```
Defaults live in `~/.codex/config.toml` (approvals off, workspace-write sandbox, network on).
ChatGPT OAuth login is also present as a fallback (`codex login status`).
Short one-shot questions can go through the registered `codex` MCP tools
(`mcp__codex__codex`, `codex-reply`); anything long-running uses the command above.
## Briefing Codex
It does not inherit this session, the master rules, or the project's CLAUDE.md.
Everything it needs goes in the prompt:
1. Explicit file paths and the shared contract (data model, helpers, endpoints) pinned
before it starts.
2. The project's conventions it must follow (stack, naming, comment density, CSS,
auth/CSRF) - copy the relevant lines in.
3. The five working points: act when you have enough information; do the simplest
thing that works; audit every claim against an actual result before reporting;
pause only for a destructive action or input only Carl can give; lead with the
outcome.
4. No competitor or other-platform names in anything it writes into the repo
(master rules Part 6). In a non-ShowHelm project, no ShowHelm resources
(Part 12).
5. What "done" means: which tests or checks it must run and report.
## File contention
On a single working tree never let Codex and another agent edit the same file.
Give each large file to exactly one track; use a separate worktree or branch for
parallel Codex builds.
## After it returns
Verify it yourself (master rules Part 4): read the diff, run the tests, load the
page, screenshot any UI. Never merge or repeat its summary on its own say-so. If
two runs fail the same way, change approach rather than retrying a third time.
## Naming
"Codex" is functional machinery. Keep it out of shipped UI copy, changelog entries,
and page content.