skill-codex

A cross-platform Claude Code skill that integrates OpenAI Codex CLI for code review, task delegation, and consultation. Uses your existing Codex subscription -- no API key required.

Why?

Claude Code and Codex CLI have different strengths. Claude excels at reasoning, architecture, and complex refactors. Codex is fast, thorough, and great at focused execution and review. skill-codex lets them work together from a single terminal -- no second window, no copy-paste, no context loss.

• /codex-review -- Have Codex review your current changes as a second reviewer
• /codex-do -- Delegate well-scoped implementation tasks to Codex
• /codex-consult -- Get a second opinion on architecture or design decisions
• Auto-review hook -- Smart PostToolUse hook suggests review after significant changes
• Subscription-first -- Works with codex login, no OPENAI_API_KEY needed
• Edge case handling -- Retry logic, timeout, anti-recursion, lock files, pre-flight checks

Prerequisites

• Node.js >= 18
• Claude Code installed and authenticated
• Codex CLI installed and logged in (codex login)

Quick Start

# Option A: Run directly (no global install)
npx skill-codex setup

# Option B: Install globally, then setup
npm i -g skill-codex
skill-codex setup

# Restart Claude Code to load the MCP server, then use:
/codex-review              # Review uncommitted changes
/codex-do "write tests"    # Delegate a task to Codex
/codex-consult "approach?" # Get a second opinion

The setup command:

1. Registers the MCP server in your Claude Code config (~/.claude.json)
2. Installs slash commands globally (~/.claude/commands/)
3. Configures the auto-review PostToolUse hook
4. Verifies everything works

Tip: Add .skill-codex.lock to your .gitignore

How It Works

You in Claude Code
  |
  |-- /codex-review        --> MCP tool --> codex exec (read-only) --> review findings
  |-- /codex-do "task"     --> MCP tool --> codex exec --full-auto --> reviewed output
  +-- /codex-consult "q"   --> MCP tool --> codex exec (read-only) --> synthesized opinion

The MCP server spawns codex exec as a subprocess, using your logged-in Codex session. Claude sees the output and critically evaluates it -- Codex is treated as a peer, not an authority.

Auto-review

After significant code changes (3+ files, 100+ lines, security-related paths), the PostToolUse hook suggests running /codex-review. Trivial changes (docs-only, < 5 lines, whitespace) are skipped to preserve your Codex quota.

Example Output

When Codex runs, the MCP tool returns a structured plain-text response:

[read-only │ D:\myproject │ 21538 tok in (15744 cached) → 129 out]
  ✔ exec: powershell -Command 'git diff --cached'  (ok)

CRITICAL — src/auth/login.ts:42
Password comparison uses == instead of timing-safe comparison.

MEDIUM — src/api/routes.ts:18
Missing rate limiting on login endpoint.

The first line shows mode, working directory, and token usage. Activity lines show commands Codex executed (with status icons: ✔ ok, ✘ blocked/failed). The response content follows after a blank line.

Configuration

Environment variables (all optional):

Smart Filter Thresholds

Edge Cases Handled

Project Structure

skill-codex/
|-- src/
|   |-- index.ts              # MCP server entry point
|   |-- server.ts             # MCP server + tool registration
|   |-- tools/codex-exec.ts   # codex_exec tool handler
|   |-- runner/               # exec-runner, retry, timeout, output parser
|   |-- guards/               # pre-flight checks (binary, auth, git, recursion, lock)
|   |-- filter/               # smart diff filter for auto-review
|   |-- lock/                 # lock file with stale detection
|   |-- errors/               # typed error classes
|   |-- config/               # constants, paths, platform utils
|   +-- util/                 # platform detection, truncation
|-- commands/
|   |-- codex-review.md       # /codex-review slash command
|   |-- codex-do.md           # /codex-do slash command
|   +-- codex-consult.md      # /codex-consult slash command
|-- hooks/
|   |-- post-tool-use-review.sh   # Auto-review hook (macOS/Linux)
|   +-- post-tool-use-review.ps1  # Auto-review hook (Windows)
|-- setup/                    # npx skill-codex setup installer
|-- bin/                      # CLI entry point
+-- __tests__/                # vitest test suite

Uninstall

npx skill-codex uninstall

Development

git clone https://github.com/Arystos/skill-codex.git
cd skill-codex
npm install
npm run build
npm test

Troubleshooting

Setup says "Hook script not found" Run npm run build first, then npx skill-codex setup again. The hook scripts live in the package root, not in dist/.

/codex-review says "Unknown tool: codex_exec" Restart Claude Code after running setup. The MCP server only loads on startup.

Codex keeps timing out Increase the timeout: export SKILL_CODEX_TIMEOUT_MS=1200000 (20 min). Large codebases can take longer.

"Auth expired" but Codex works in another terminal The MCP server runs in its own process. Run codex login and restart Claude Code. On Windows, the auth pre-check is skipped automatically (PowerShell profile errors can cause false negatives); auth is still verified when Codex actually runs.

Lock file blocking runs If a previous run crashed, a stale .skill-codex.lock may remain. It auto-cleans after 15 minutes, or delete it manually.

Inspired By

• Dunqing/claude-codex-bridge -- retry logic, anti-recursion, output parsing
• EpocheDrift/claude-codex-skill -- subscription-first, delegation heuristics
• incadawr/claude-codex-skill -- MCP server approach, auto-triggers

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Support

If you find this useful, consider supporting the project:

License

MIT