codex-offload

name

codex-offload

description

Task routing — Claude tokens are expensive, Codex usage is cheap. When an "execution-style" task comes in (bulk file edits, translation, long-form/sample code/test generation, format conversion, data cleanup, image generation, large-output reconnaissance, web research), read this skill first and decide whether it can be offloaded to codex exec. Claude only breaks the task down, writes the work order, and handles verification. If Claude gets stuck twice, it can also ask Codex for a second opinion on stuck tasks. Use this when the user says "use codex", "save tokens", "offload to codex", or /codex-offload. The following tasks should not be offloaded and should be handled by Claude directly as usual (this is not a ban): tasks that need session context or memory, architecture decisions, outward-facing actions, and small jobs that can be finished in a few minutes.

Codex Offload (codex-offload)

Division of Labor

• Claude (expensive, smart): understand the request, break down the task, write the work order, verify the result, and handle failures.
• Codex (cheap, gets work done): execute concrete work with clear specs and clear verification.

One-line rule: If you can write it as a self-contained work order for an external engineer, and verification is much cheaper than doing it yourself, offload it.

Decision Checklist

Offload to Codex

Task type	Examples
Bulk mechanical work	Rename dozens of files, reformat them, or add headers
Translation	Long-form translation, multi-file doc localization to/from Chinese or English
Long content generation	Clearly specified first drafts, READMEs, test cases, boilerplate code
Format conversion	HTML->Markdown, JSON->CSV, data cleanup
Image generation	Illustrations/infographics through Codex's built-in image_gen (better accuracy for text and numbers inside images)
Isolated coding tasks	Clearly bounded single-function/single-module implementation, bug fixes with an explicit spec
Large-file digestion	Read a pile of long files and return only conclusions/summaries
Large-output reconnaissance commands	Exploratory commands that can flood context, such as find, grep -r, long logs, or dependency trees; return only distilled conclusions
Web research	GitHub/web information gathering (--enable web_search); require the work order to report only verified facts with sources
Domain CLI batch work	Domains where both sides have the same kind of skill installed (for example, office-suite CLIs); clearly specified batch work can still be offloaded
Second opinion on stuck tasks	Bugs/hard problems Claude has tried twice and failed to solve; hand them to Codex for another angle, with attempted fixes and failure symptoms included in the work order

Do Not Offload; Claude Handles Directly

Note: this section defines ownership (who does the work), not a prohibition. The tasks below should still be done as usual; they just should not be handed to Codex.

Situation	Reason
Tasks that need session context/user memory	Codex is stateless; reconstructing context costs more than it saves
Ambiguous requirements, architecture decisions, tradeoff analysis	These need judgment, which is exactly why Claude tokens are expensive
Small tasks expected to finish in a few tool calls	Writing a work order + verification costs more than doing it directly
Destructive/outward-facing operations (delete data, send messages, deploy)	Claude must stay in direct control
Tasks Codex has failed twice in a row	Stop spending cycles; Claude should take over

Split mixed tasks: for example, "scrape a webpage -> translate -> insert into database" can be offloaded as a whole or split into pieces; decide step by step using the table above.

Skill alignment: Claude Code and Codex use compatible skill formats. If Codex is missing a skill, add it with ln -s ~/.claude/skills/<name> ~/.codex/skills/<name> and continue offloading as usual (symlinks are recognized). Do not keep the task just because the skill is missing; for temporary cases, inline the operating knowledge directly in the work order.

Invocation

Base template (non-interactive, returns when done):

codex exec --skip-git-repo-check -C <working-dir> -s <sandbox-level> \
  -o /tmp/codex-last-msg.md \
  "<work order>" </dev/null 2>/dev/null

Three traps to avoid:

1. stdin must be closed: codex exec always reads stdin and appends it to the positional prompt. If stdin is left open, it can hang forever (symptoms: zero output, zero CPU). Always end the command with </dev/null; 2>/dev/null filters reasoning noise from stderr.
2. The sandbox has no network by default: tasks that need shell network access must add -c sandbox_workspace_write.network_access=true; otherwise curl and similar commands will all fail. Pure search can use --enable web_search and does not require shell network access.
3. Put long work orders in files: if the prompt is longer than one screen, write it to a file and pass it through stdin: codex exec ... - < /tmp/task.md (- means read the work order from stdin, so do not add </dev/null). This avoids quote-escaping pain.

Common parameters and run modes:

• Sandbox level: use read-only for analysis-only work; use workspace-write for file edits (it can only write inside -C; add extra directories with --add-dir). Do not use danger-full-access.
• Result retrieval: the final response is written to the file specified by -o; read generated text tasks from there.
• Background by default: unless it is clearly a one- or two-minute job, run it in the background so Claude can do other work, then verify after it finishes.
• Parallelism: run multiple codex exec processes for independent subtasks.
• Continue a session: codex exec resume --last "<follow-up instructions>" </dev/null appends instructions to the previous session without rewriting the context.
• Model tier: omit -m by default; for highly mechanical bulk work, you may choose a cheaper/faster model and lower reasoning with --config model_reasoning_effort.

Work Order (Prompt) Requirements

Codex cannot see Claude's conversation context. The work order must be self-contained and written like an operator instruction, not a chat message:

1. Block structure: for long work orders, use <task>, <context>, <constraints>, and <output_format>; keep it compact and imperative.
2. Absolute paths: spell out all input and output paths.
3. Complete background: include the relevant background in the work order; do not refer to "what was said above".
4. Verification criteria: define what "done" means so Codex can self-check and Claude can verify.
5. Output contract: constrain the returned format and length (for example, "30 lines max: conclusion + evidence + recommendations"). Claude pays to read the result too, so ask for distilled output, not a dump.
6. Truthfulness constraints (required for research): report only verified facts with sources/URLs; explicitly say "if you cannot find it, say you cannot find it; do not invent from memory".
7. Prohibitions: list files not to touch, whether network access is allowed, and any other constraints as needed.

Verification (Required)

After Codex finishes, Claude must verify the result, but verify cheaply:

• File operations: use ls / wc -l / grep to spot-check key points; do not read whole files back into context.
• Code: run tests or type checks and inspect the exit code.
• Content generation: read the beginning + one random section + check structural completeness.
• Translation/localization: regex-check for leftover source-language characters (e.g. grep -P "[\x{4e00}-\x{9fff}]" on English docs); when a work order says "do not translate code blocks", scope it to commands and syntax only -- comments, diagrams, and example text still need translating.
• Research/information tasks: spot-check important facts (for example, use the GitHub API to confirm a repo exists and the star count is plausible). Fabrication is the top risk in outsourced research.
• If verification fails: write the concrete issue as a follow-up instruction and fix once with codex exec resume --last; if it fails again, Claude takes over.

Smart Triggering (Optional Enhancement)

This skill's description stays in context as a "soft trigger". The repository also includes a UserPromptSubmit hook (hooks/codex-offload-nudge.py): a local, zero-token keyword precheck that injects a routing reminder only when the user's message looks offloadable, and stays silent otherwise. See the repository README for installation.

Fallback Executors

If Codex quota runs out (quota/429-style errors), use another headless CLI as a fallback (for example, kimi -y -p "<work order>" or gemini -p "<work order>"). Reuse the same work order.