codex-claude-subagents

Use Claude as subagents in Codex. Yep, that's it.

No more keeping Codex and Claude open side by side, manually shuttling context between them. This skill lets Codex spawn Claude CLI workers directly — scoped to a directory, resumable by session ID, logs kept out of git.

OpenAI ships a Codex plugin for Claude Code. This is the other direction: Claude as a worker, orchestrated from inside Codex.

Why

Codex and Claude are both capable agents with different strengths. Codex excels at orchestration, planning, and driving multi-step workflows. Claude excels at deep reasoning, careful edits, and long-horizon tasks. Running Claude subagents from inside Codex lets you get the best of both — without a framework, extra packages, or glue code.

This skill wires them together:

No framework, no extra packages — stdlib only.

Install

cp -R skills/claude-subagents ~/.codex/skills/

Restart your Codex session after installing — Codex discovers skills at session start.

Requirements

• Codex CLI installed
• Claude CLI (Claude Code) installed and authenticated (claude --version)
• Python 3.9+

Quickstart

Read-only audit

python3 ~/.codex/skills/claude-subagents/scripts/run_claude_subagent.py \
  --task audit-security \
  --prompt examples/prompts/read-only-audit.md

Scoped fix

python3 ~/.codex/skills/claude-subagents/scripts/run_claude_subagent.py \
  --task fix-auth \
  --prompt examples/prompts/scoped-fix.md \
  --write-scope src/auth

Resume an interrupted run

python3 ~/.codex/skills/claude-subagents/scripts/run_claude_subagent.py \
  --task fix-auth \
  --prompt examples/prompts/scoped-fix.md \
  --session-id <session-id-from-ledger> \
  --write-scope src/auth

Session IDs are stored in .agent-runs/claude/ledger.json after each run.

How to use from inside Codex

Once the skill is installed, Codex picks it up automatically. Ask Codex things like:

"Run a security audit on this repo using the Claude subagent skill."

"Delegate the auth refactor to a Claude worker scoped to src/auth."

Codex will invoke the launcher, wait for the summary, and report back.

CLI reference

run_claude_subagent.py [options]

Required:
  --task   <id>       Stable kebab-case task identifier (used for log filenames)
  --prompt <file>     Markdown prompt file to send to the worker

Optional:
  --write-scope <dir> Directory the worker may edit (repeatable; omit = read-only)
  --session-id  <id>  Resume a previous Claude session
  --model       <m>   Claude model (default: sonnet)
  --effort      <e>   Reasoning effort: low|medium|high|xhigh|max (default: high)
  --permission-mode   Claude permission mode (default: acceptEdits)
  --cwd         <dir> Working directory for the Claude run (default: .)
  --name        <n>   Display name for the session (default: task id)

Log layout

All logs are written to .agent-runs/claude/ in the working directory. This path is automatically added to .gitignore.

Worker contract

Every prompt is prepended with a contract that tells Claude:

• Codex is lead orchestrator; Claude is a scoped worker
• Writes are restricted to --write-scope (or read-only if unset)
• Structured output goes to logs; don't summarize to stdout
• Write a compact summary to .agent-runs/claude/<task>.summary.md
• Summary must include: Outcome, Files Inspected, Files Changed, Verification, Risks, Next

This contract is injected automatically — your prompt file only needs the task description.

Example prompts

Ready-made prompts live in examples/prompts/:

Concurrency and feedback model

Workers run sequentially per launcher call. The launcher blocks on subprocess.run until the Claude process exits. There is no built-in parallel dispatch.

To run multiple workers in parallel, background multiple launcher calls with distinct --task IDs:

python3 run_claude_subagent.py --task audit-auth  --prompt prompts/audit.md &
python3 run_claude_subagent.py --task audit-tests --prompt prompts/audit.md &
wait

Per-task log files (<task>.jsonl, <task>.summary.md) are keyed by task ID and do not collide. ledger.json is a shared file with no write lock — if two workers finish simultaneously, one ledger entry can be lost. For hard guarantees, add a file lock around the ledger write or use separate ledger files per task.

Feedback is post-hoc and one-way. Codex is blind while a worker runs. The only output channel is the summary file the worker writes on exit, plus the JSON blob the launcher prints to stdout on completion. There is no mid-run signalling: the worker cannot return partial results, and Codex cannot interrupt or redirect a running worker. To get intermediate visibility, tail the .jsonl log from a separate process while the worker runs.

Limitations

• Requires Claude CLI installed and authenticated locally.
• Codex does not hot-reload skills — restart the session after cp.
• Broad --write-scope values (. or /) are unsafe; always scope to the minimum required directory.
• Session resumption depends on Claude CLI's --session-id support; behaviour may vary across CLI versions.

Contributing

Issues and PRs welcome. Keep it stdlib-only — no new runtime dependencies.