claude-codex-subagent

claude-codex-subagent

Save Claude's tokens by delegating grunt work to the local Codex CLI.

A Claude Code skill that turns codex exec into a worker subagent. Claude stays the orchestrator — planning, deciding, verifying — while Codex handles everything that would otherwise burn Claude's context: web searches, large reads, bulk analysis, long file writes, running tests, audits.

Works on macOS, Linux, and Windows (git-bash or WSL). Zero runtime dependencies beyond codex on your PATH. No Node, no Python, no MCP server.

---

The problem

Claude Code is great, but every WebFetch, every Read of a 2000-line file, every long grep output eats into your context window. Do it enough times in one session and you've paid thousands of tokens for work that produced a one-sentence conclusion.

Codex CLI solves this if you use it right: it has its own fresh context, its own network, and its own sandboxed shell. You hand it a scoped task, it does a ton of work internally, and it hands back a short answer. You (Claude) only pay for the prompt in and the answer out.

This skill teaches Claude when to delegate, how to write good dispatch prompts, how to pick the right sandbox mode adaptively, and how to classify the result.

How it works

  ┌────────────┐    1. dispatch         ┌────────────┐
  │            │ ──────────────────▶   │            │
  │   Claude   │                        │   Codex    │
  │ (orchestr.)│ ◀──────────────────    │  (worker)  │
  │            │    2. final answer     │            │
  └────────────┘                        └────────────┘
        │                                     │
        │ owns: planning, decisions,          │ owns: web search, file I/O,
        │ judgment, verification,             │ long reads, bulk analysis,
        │ conversation state                  │ writes, tests, audits

Claude's context stays tiny. Codex's context absorbs all the grunt work. The conversation you care about is unaffected.

Features

• Adaptive sandbox — defaults to --full-auto (workspace-write), automatically escalates to --dangerously-bypass-approvals-and-sandbox when the task needs network or cross-workspace access. No approval prompts — Claude announces the choice in one line and proceeds.
• Thin-forwarder contract — Codex's stdout is the authoritative return. No Claude-side freelancing, no phantom-answer drift.
• Smart stderr logging — captures Codex's thinking stream to /tmp/codex-<rand>.log instead of /dev/null, so the happy path stays clean but failures are fully debuggable.
• Reasoning effort by task class — audits and security reviews get high, normal edits use the default. No extra config.
• Resume-first pattern — follow-ups reuse Codex's prior session state via codex exec resume --last, avoiding redundant context re-loading.
• Parallel batch dispatch — independent subtasks fire in parallel via Claude Code's background task system.
• Background lifecycle — long runs go background (run_in_background: true), poll with TaskOutput, cancel with TaskStop.
• Structured outcome classification — every result is classified as success / partial / error and handled accordingly. No silent retries.
• Multi-modal personas — 5 pre-written persona templates (reviewer, debugger, auditor, researcher, refactorer), each with its own sandbox/effort defaults and explicit return-format contract. Drop-in your own in the same format.
• Zero-dep helper scripts — scripts/doctor.sh for health checks, scripts/codex-dispatch.sh for direct CLI use, scripts/sync-skill.sh for maintainers.

Prerequisites

1. Claude Code (CLI, desktop app, or IDE extension)
2. Codex CLI — OpenAI's codex command-line agent. Install via npm:

   npm install -g @openai/codex
   codex login    # first-time auth
   

3. A bash-compatible shell:
   • macOS, Linux: native
   • Windows: git-bash (comes with Git for Windows) or WSL

That's it. No Node dependencies for the skill itself, no config files, no MCP servers.

Install

Pick one:

Option A — Manual skill copy (works anywhere, 10 seconds)

git clone https://github.com/dwgx/claude-codex-subagent.git
cp -r claude-codex-subagent/skills/codex-subagent ~/.claude/skills/

That's it. Claude Code auto-discovers skills under ~/.claude/skills/.

Option B — As a Claude Code plugin

If your Claude Code supports marketplace plugins: