Codex-for-Claude-Code

Cargando contenido…

Codex-for-Claude-Code | xt0n1

┌──────────────────┐         ┌────────────────────────────┐         ┌────────────────────┐
│  You ask Claude  │ ──────▶ │  Claude dispatches /codex  │ ──────▶ │  New terminal pane │
└──────────────────┘         │  (per-job id, prompt file) │         │  runs codex exec   │
                             └────────────────────────────┘         │  (you watch live)  │
                                       │                            └────────────────────┘
                                       │                                       │
                                       ▼                                       ▼
                             ┌────────────────────────────┐         ┌────────────────────┐
                             │  wait_and_read.sh polls +  │ ◀────── │  Done flag + status│
                             │  parses single truth block │         │  + session id file │
                             └────────────────────────────┘         └────────────────────┘
                                       │
                                       ▼
                             ┌────────────────────────────┐
                             │  CODEX_BEGIN / END block   │
                             │  final agent message only  │
                             │  (~2K Claude tokens)       │
                             └────────────────────────────┘

Problem	Solution
Native Claude `Task`/`Agent` subagents stream the entire transcript into Claude's context (~30-80K tokens per task). One pesky exploration can blow your 5-hour Max window.	This skill delegates to `codex` — a separate process drawing from your ChatGPT Plus/Pro quota, not your Claude plan. Claude only reads the final report (~2K tokens).
You can't see what a subagent is doing in real time.	The new terminal window shows the real `codex exec` CLI live — model, reasoning, exec calls, message, tokens. Pause with `Ctrl+S`, resume with `Ctrl+Q`.
Accidentally close the terminal? Your work is gone.	Every dispatch captures the codex `session id`. Run `resume.sh` to continue from where you left off — no re-reasoning.
Codex can hang on sandbox quirks (Python blocked, missing MCP servers, signal pipe errors).	Defensive prompt preamble + automatic stuck detection (file-growth heartbeat + repeated-error counter) auto-alert after 90 seconds with a clean diagnosis.

┌─────────────────────────────────────────────────────────────────────┐
│  Claude (this skill)                                                │
│   1. Generate JOB_ID                                                │
│   2. Write $TMPDIR/cx-<JOB>.prompt    (heredoc — any chars safe)    │
│   3. Write $TMPDIR/cx-<JOB>.env       (sourced by run.sh)           │
│   4. Bash background:                                               │
│        bash skill/spawn.sh JOB CONFIG                               │
│        bash skill/wait_and_read.sh JOB [TIMEOUT]                    │
│           ├─ done flag    → parse final block                       │
│           ├─ stuck flag   → diagnose + alert user                   │
│           └─ timeout      → abort + offer resume                    │
└─────────────────────────────────────────────────────────────────────┘
                  │
                  ▼  (spawn.sh detects OS, opens terminal)
┌─────────────────────────────────────────────────────────────────────┐
│  Terminal window (Windows Terminal · Terminal.app · gnome-terminal) │
│                                                                     │
│   bash run.sh CONFIG                                                │
│     ├─ trap on EXIT/INT/TERM/HUP → ALWAYS writes done flag          │
│     ├─ source CONFIG (MODEL, EFFORT, SANDBOX, TIER, CWD, PROMPT)    │
│     ├─ codex exec [resume <SID>] ARGS PROMPT  2>&1 | tee OUT        │
│     ├─ capture session id → cx-<JOB>.session  (for resume)          │
│     └─ write done + status files                                    │
└─────────────────────────────────────────────────────────────────────┘

File	Purpose
`skill/SKILL.md` · `SKILL.es.md`	The skill definition Claude reads (English / Spanish).
`skill/run.sh`	Cross-platform runner that runs inside the spawned terminal pane. Trap-based done flag, session capture, sandbox/tier configurable.
`skill/spawn.sh`	Cross-platform terminal spawner. Detects OS, picks best terminal emulator.
`skill/spawn-windows.cmd`	Windows helper that preserves quoting when `spawn.sh` launches `wt.exe` or `cmd`.
`skill/wait_and_read.sh`	Polls + reads result. Single call replaces inline wait loop + ctx_execute_file.
`skill/resume.sh`	Resumes an interrupted session by id. Inherits previous job's MODEL/EFFORT/SANDBOX.
`setup/SETUP.md` · `SETUP.es.md`	Copy-paste install prompts for Claude Code.

# OpenAI Codex CLI
npm i -g @openai/codex

# Sign in with your ChatGPT Plus / Pro account (one-time)
codex login

# Verify (needs >= 0.117)
codex --version

git clone https://github.com/xt0n1-t3ch/Codex-for-Claude-Code.git
cd Codex-for-Claude-Code
mkdir -Force "$env:USERPROFILE\.claude\skills\codex" | Out-Null
copy skill\SKILL.md            "$env:USERPROFILE\.claude\skills\codex\SKILL.md"
copy skill\run.sh              "$env:USERPROFILE\.claude\skills\codex\run.sh"
copy skill\spawn.sh            "$env:USERPROFILE\.claude\skills\codex\spawn.sh"
copy skill\spawn-windows.cmd   "$env:USERPROFILE\.claude\skills\codex\spawn-windows.cmd"
copy skill\wait_and_read.sh    "$env:USERPROFILE\.claude\skills\codex\wait_and_read.sh"
copy skill\resume.sh           "$env:USERPROFILE\.claude\skills\codex\resume.sh"
# (For Spanish) copy skill\SKILL.es.md "$env:USERPROFILE\.claude\skills\codex\SKILL.md"

git clone https://github.com/xt0n1-t3ch/Codex-for-Claude-Code.git
cd Codex-for-Claude-Code
mkdir -p ~/.claude/skills/codex
cp skill/SKILL.md skill/run.sh skill/spawn.sh skill/spawn-windows.cmd skill/wait_and_read.sh skill/resume.sh ~/.claude/skills/codex/
chmod +x ~/.claude/skills/codex/*.sh
# (For Spanish) cp skill/SKILL.es.md ~/.claude/skills/codex/SKILL.md

git clone https://github.com/xt0n1-t3ch/Codex-for-Claude-Code.git
cd Codex-for-Claude-Code
mkdir -p ~/.claude/skills/codex
cp skill/SKILL.md skill/run.sh skill/spawn.sh skill/spawn-windows.cmd skill/wait_and_read.sh skill/resume.sh ~/.claude/skills/codex/
chmod +x ~/.claude/skills/codex/*.sh
# (For Spanish) cp skill/SKILL.es.md ~/.claude/skills/codex/SKILL.md

codex: Delegate work to OpenAI Codex CLI (ChatGPT quota, NOT your Claude plan)…

Trigger	Model	Effort
`use /codex explore X` (basic)	`gpt-5.4-mini`	`medium`
`use /codex explore X deeply`	`gpt-5.4-mini`	`high`
`use /codex implement X`	`gpt-5.4`	`high`
`use /codex refactor X`	`gpt-5.4`	`high`
`use /codex review`	`gpt-5.4`	`high`
`use /codex run tests` / `prod ready`	`gpt-5.4`	`high`
`use /codex find bugs`	`gpt-5.4`	`high`

Approach	Per dispatch	2-hour heavy session (28 dispatches)
Native subagent (`Task` / `Agent`)	30K – 80K	800K – 2.2M
`/codex` with full Monitor stream	5K – 30K	150K – 525K
`/codex` (this skill)	2K – 4K	~60K – 110K

Native subagent:   ████████████████████████████  ~30-80K
Monitor full:      ████████████                    ~5-30K
THIS skill:        █                                ~2-4K  ← 92% savings

OS	Terminal emulator	Spawn mechanism	Status
Windows 11	Windows Terminal (`wt.exe`)	`cmd /c start "" wt.exe -w 0 nt …`	✅ Tested
Windows 10	`wt.exe` if installed, else `cmd /k` fallback	same	✅ Fallback works
macOS	Terminal.app via AppleScript	`osascript -e 'tell app "Terminal"…'`	✅
Linux (GNOME)	`gnome-terminal`	`gnome-terminal --title=… -- bash …`	✅
Linux (KDE)	`konsole`	`konsole --title … -e bash …`	✅
Linux (other)	xfce4-terminal · kitty · alacritty · wezterm · xterm	first available, in priority order	✅

Concern	Mitigation
Race conditions between concurrent dispatches	Per-job IDs (`cx-<JOB_ID>.{prompt,env,txt,done,status,stuck,session,spawn.log}`).
Abort hangs Claude (Ctrl+C / window close)	`trap EXIT INT TERM HUP` in `run.sh` always writes the done flag.
Codex stuck in a retry loop	Wait loop watches file-growth heartbeat (90s threshold) + repeated-error counter (3+ matches of `Access is denied`/`signal pipe`/etc) → writes `cx-<JOB>.stuck`.
Hard timeout	`TIMEOUT` per task type (3-20 min) → writes stuck flag and surfaces to user.
Accidental window close	Session id captured to `cx-<JOB>.session` → `resume.sh` continues with `codex exec resume <id>`.
Fragile prompt transport	Prompts written to file via heredoc, never passed via argv through `bash → wt → bash`.
Sandbox blocking codex tools	Default `SANDBOX=danger-full-access` lets codex use Python, MCPs, all shells. Configurable per dispatch.
Codex hallucinated MCP names	Defensive prompt preamble explicitly lists available MCPs and forbids non-existent ones (`filesystem`).
Verbose answers truncated	`wait_and_read.sh` uses marker-based extraction (between `codex\n` and `tokens used\n`), not `tail -100`.
Lazy polling / asking user about terminal contents	`wait_and_read.sh` as single source of truth + `SKILL.md` RULE forbidding fallback chatter.

Symptom	Fix
`unexpected argument '--ask-for-approval'`	Remove the flag — it doesn't exist on `codex exec`.
`not inside a trusted directory`	`--skip-git-repo-check` must be a real CLI flag (not `-c`). Already in template.
`model is not supported`	Valid: `gpt-5.4-mini`, `gpt-5.4`. `gpt-5.4-codex` does not exist.
Codex hangs reading stdin	`run.sh` already redirects via `tee`; ensure no `bash -c` wrapper sneaks past.
`Access is denied` loops in pwsh	Switch `SANDBOX` to `danger-full-access` (default) or update prompt preamble to forbid Python.
`unknown MCP server 'filesystem'`	Codex hallucinated. Preamble already forbids it. Re-dispatch.
Window closes immediately on Windows	Ensure `wt.exe` is installed and Git Bash's `bash` is in `PATH`. Check `cx-<JOB>.spawn.log`.
Stuck flag fires falsely	Increase `STUCK_THRESHOLD` in the dispatch template (default 120 s).

Codex-for-Claude-Code

Galería

Topics

Sobre este proyecto

Codex for Claude Code

Table of Contents

What it does

Why it matters

Architecture

Quick Start

1. Prerequisites

2. Install the skill — one-liner per OS

3. Restart Claude Code

4. Or let Claude install it for you

Routing rules

AUTO (no trigger — Claude routes silently)

ON-TRIGGER (`use /codex <action>`)

Urgency tier (manual opt-in)

Cost comparison

Cross-platform support

Resilience features

Troubleshooting

Credits

Contributing

License

Codex-for-Claude-Code

Galería

Topics

Sobre este proyecto

Codex for Claude Code

Table of Contents

What it does

Why it matters

Architecture

Quick Start

1. Prerequisites

2. Install the skill — one-liner per OS

3. Restart Claude Code

4. Or let Claude install it for you

Routing rules

AUTO (no trigger — Claude routes silently)

ON-TRIGGER (use /codex <action>)

Urgency tier (manual opt-in)

Cost comparison

Cross-platform support

Resilience features

Troubleshooting

Credits

Contributing

License

ON-TRIGGER (`use /codex <action>`)