// Run Codex CLI (exec, resume) for parallel work, delegating tasks to another model, or background code generation. Handles code analysis, refactoring, and automated editing. Includes Spark vs standard guidance. Triggers: "codex", "run codex", "use codex to".
| name | codex |
| description | Run Codex CLI (exec, resume) for parallel work, delegating tasks to another model, or background code generation. Handles code analysis, refactoring, and automated editing. Includes Spark vs standard guidance. Triggers: "codex", "run codex", "use codex to". |
--profile edit — local edits, build, or test (workspace-write, full-auto)--profile full — network or broad filesystem access (danger-full-access, full-auto)Use --profile edit whenever the task involves go test, go build, or any command that writes build artifacts. The default read-only sandbox blocks all writes including compiler temp dirs.
For complex tasks, add --config model_reasoning_effort="xhigh".
Default to the project model in .codex/config.toml (gpt-5.4).
Use --model gpt-5.3-codex-spark for speed-first interactive work:
Stay on default gpt-5.4 for depth-first work:
If the user explicitly requests a model, follow the user's request.
Project defaults in .codex/config.toml. Always include --skip-git-repo-check and 2>/dev/null. Only override model when the user explicitly requests it, or when the task clearly fits the Spark speed-first criteria above.
| Use case | Command |
|---|---|
| Read-only analysis | codex exec --skip-git-repo-check -o "$CODEX_OUT" "prompt" 2>/dev/null |
| Speed-first interactive loop (Spark) | add --model gpt-5.3-codex-spark |
| Apply local edits | add --profile edit |
| Network / broad access | add --profile full |
| Resume session | echo "prompt" | codex exec --skip-git-repo-check -o "$CODEX_OUT" resume --last 2>/dev/null |
Create a temp file for output before running: CODEX_OUT=$(mktemp /tmp/codex-out.XXXXXX). Read the result from $CODEX_OUT after completion.
Run with Bash run_in_background: true. Monitor via TaskOutput with block: true, timeout: 600000 — do NOT use sleep commands to poll. Read the -o file for the final answer.
Don't pass model/effort/sandbox flags when resuming — original session settings carry over. -o is safe to include.
This is a Go project. Use go test, go build, go vet in prompts. Codex workers don't receive CLAUDE.md or hooks, so project conventions must be explicit.
Always verify Codex output via git diff --stat — never trust the worker's self-reported file list. Codex workers may make out-of-scope changes (deleting files, reverting unrelated code, removing test functions). The completion promise may list only intended files while omitting destructive side effects.
When other work exists in the same codebase, include explicit "DO NOT modify or delete" file lists in the prompt. The positive instruction ("only touch these files") is insufficient — Codex interprets "clean up" broadly.
Per [[principles/prove-it-works]]: trust artifacts, not self-reports.
With -C <worktree-dir>, the worktree has its own git index. .claude/ may symlink to .agents/ — use .agents/ paths for git operations.
Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, typography, micro-interactions, enter/exit animations, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, font smoothing, tabular numbers, image outlines, box shadows.
Systematic planning for medium-to-large tasks. Gathers context, identifies domain skills, writes phased plans to brain/plans/. Does NOT implement. Use for new features, multi-file refactors, or architectural changes — not small fixes. Triggers: "plan this", "break this down".
Adversarial code review using cross-model approach. Spawns reviewers on the opposing model (Claude uses Codex, Codex uses Claude) to challenge work from distinct critical lenses. Produces a synthesized verdict with findings and lead judgment. Triggers: "adversarial review".
Structural code search via ast-grep — use when code shape and element relationships matter, not just text. E.g., "find async functions without error handling", "refactor foo(a, b) to foo({ a, b })". Use Grep for simple name lookups.
Read/write brain files (Obsidian vault at brain/). Use for any task that persists knowledge — reflection, planning, or direct edits. Triggers after debugging sessions, mistakes, corrections, architectural decisions, or any insight worth preserving across sessions. Use on 'add to brain', 'remember this', 'write a note', or brain/ modifications.
Create conventional commit messages. Use when the user says "commit this", "save changes", "git commit", asks to commit code, write a commit message, or format git history. Follows conventional commits specification.