skill-codex 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arystos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# skill-codex
+
+![npm](https://img.shields.io/npm/v/skill-codex)
+![CI](https://github.com/Arystos/skill-codex/actions/workflows/ci.yml/badge.svg)
+![Windows](https://img.shields.io/badge/Windows-0078D4?style=flat&logo=windows&logoColor=white)
+![macOS](https://img.shields.io/badge/macOS-000000?style=flat&logo=apple&logoColor=white)
+![Linux](https://img.shields.io/badge/Linux-FCC624?style=flat&logo=linux&logoColor=black)
+![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat&logo=node.js&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-blue?style=flat)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat&logo=ko-fi&logoColor=white)](https://ko-fi.com/arystos)
+
+A cross-platform [Claude Code](https://code.claude.com) skill that integrates [OpenAI Codex CLI](https://github.com/openai/codex) 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](https://nodejs.org) >= 18
+* [Claude Code](https://code.claude.com) installed and authenticated
+* [Codex CLI](https://github.com/openai/codex) installed and logged in (`codex login`)
+
+## Quick Start
+
+```shell
+# 1. Install and configure everything in one command
+npx skill-codex setup
+
+# 2. Restart Claude Code to load the MCP server
+
+# 3. Use the commands in any project
+/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: `/codex-review`
+
+```
+> /codex-review
+
+Reviewing uncommitted changes (3 files, ~85 lines)...
+
+Codex found 2 issues:
+
+CRITICAL — src/auth/login.ts:42
+Password comparison uses == instead of timing-safe comparison.
+Claude's assessment: Agree. Use crypto.timingSafeEqual() instead.
+
+MEDIUM — src/api/routes.ts:18
+Missing rate limiting on login endpoint.
+Claude's assessment: Agree. Add rate limiter middleware.
+
+Shall I fix these issues?
+```
+
+## Configuration
+
+Environment variables (all optional):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SKILL_CODEX_TIMEOUT_MS` | `600000` (10 min) | Subprocess timeout |
+| `SKILL_CODEX_MAX_RETRIES` | `3` | Retry count for transient errors |
+| `SKILL_CODEX_DEBUG` | -- | Enable debug logging to stderr |
+
+### Smart Filter Thresholds
+
+| Condition | Action | Rationale |
+|-----------|--------|-----------|
+| < 5 lines changed | Skip | Not worth the Codex call |
+| All files are `.md`/`.txt`/`.rst` | Skip | Documentation-only |
+| Whitespace or import-only diff | Skip | Formatting change |
+| Path contains `auth`/`security`/`crypto` | **Force review** | Security-sensitive |
+| > 100 lines changed | **Force review** | High-impact change |
+| > 3 files changed | **Force review** | Cross-cutting change |
+
+## Edge Cases Handled
+
+| Scenario | What Happens |
+|----------|-------------|
+| Codex not installed | Clear error with install instructions |
+| Auth expired | Advises `codex login`, no retry |
+| Network down | Retries 3x with exponential backoff |
+| Rate limited (429) | Retries with backoff + jitter |
+| Codex hangs | Killed after timeout (SIGTERM then SIGKILL) |
+| Concurrent runs | Lock file prevents conflicts (stale after 15min) |
+| Recursive calls | `SKILL_CODEX_DEPTH` limit prevents infinite loops |
+| Trivial changes | Smart filter skips auto-review |
+| Empty Codex output | Retries once, then reports clearly |
+
+## 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
+
+```shell
+npx skill-codex uninstall
+```
+
+## Development
+
+```shell
+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.
+
+**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](https://github.com/Dunqing/claude-codex-bridge) -- retry logic, anti-recursion, output parsing
+* [EpocheDrift/claude-codex-skill](https://github.com/EpocheDrift/claude-codex-skill) -- subscription-first, delegation heuristics
+* [incadawr/claude-codex-skill](https://github.com/incadawr/claude-codex-skill) -- MCP server approach, auto-triggers
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Support
+
+If you find this useful, consider supporting the project:
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/arystos)
+
+## License
+
+MIT

package/commands/codex-consult.md

@@ -0,0 +1,36 @@
+# Consult Codex for a Second Opinion
+
+Get Codex's perspective on a technical question, plan, or approach.
+
+## Instructions
+
+You are consulting Codex for a second opinion. This is read-only — no files will be modified.
+
+1. **Parse the question** from `$ARGUMENTS`. This could be:
+   - A technical question about the codebase
+   - A plan you want validated before implementing
+   - An architecture decision you want a second perspective on
+   - A debugging hypothesis you want challenged
+   - A technology choice comparison
+
+2. **Prepare a focused prompt** for Codex. Include:
+   - The specific question or plan to evaluate
+   - Relevant context: file paths, code snippets, constraints
+   - What kind of feedback you want (validation, alternatives, risks, tradeoffs)
+
+3. **Call the `codex_exec` MCP tool** with:
+   - `prompt`: "Provide your analysis and recommendation on the following question. Consider tradeoffs, alternatives, and potential risks. Be specific and cite concrete examples where possible.\n\n<question with context>"
+   - `mode`: "exec"
+
+4. **Synthesize both perspectives** for the user:
+   - Present Codex's analysis
+   - Provide your own independent analysis
+   - Where you agree and why
+   - Where you disagree and why (with evidence)
+   - Your recommended path forward with reasoning
+
+## Important
+
+- Codex runs in **read-only mode** — it cannot modify files
+- This is a **consultation, not a delegation** — the final decision rationale comes from this conversation
+- If you and Codex strongly disagree, present both arguments fairly and let the user decide

package/commands/codex-do.md

@@ -0,0 +1,44 @@
+# Delegate Task to Codex
+
+Delegate a well-scoped implementation task to Codex.
+
+## Instructions
+
+You are delegating an implementation task to Codex. Follow these steps:
+
+1. **Parse the task** from `$ARGUMENTS`. If the argument is vague or missing, ask the user to be more specific before proceeding.
+
+2. **Evaluate if the task is suitable for delegation**:
+   - **Good for Codex**: repetitive bulk changes, boilerplate generation, test writing for existing code, migration scripts, file format conversions, well-defined single-file edits
+   - **Keep for yourself**: architectural decisions, cross-module refactoring, tasks requiring deep conversation context, ambiguous requirements, tasks under 50 lines
+   - If the task is poorly scoped, explain why and suggest how to break it down.
+
+3. **Prepare a precise, self-contained prompt** for Codex. Include:
+   - Exact file paths to create or modify
+   - The specific change required with examples if helpful
+   - Constraints (language, framework, coding style, naming conventions)
+   - What "done" looks like
+
+4. **Call the `codex_exec` MCP tool** with:
+   - `prompt`: the prepared prompt
+   - `mode`: "full-auto"
+   - `requireGit`: true
+
+5. **Review Codex's output critically**:
+   - Run `git diff` to see exactly what Codex changed
+   - Check for introduced bugs, regressions, or style violations
+   - Verify it matches the requested changes
+   - Verify it doesn't modify files outside the requested scope
+
+6. **Present the result** with your assessment:
+   - What was done correctly
+   - What needs adjustment
+   - Apply changes only if they pass your review
+   - If issues found, offer to fix them yourself or re-delegate with refined instructions
+
+## Important
+
+- Codex runs in **full-auto mode** — it CAN modify files in the workspace
+- Always `git diff` after Codex runs to verify what changed
+- Codex is a **peer, not an authority** — review all output before accepting
+- For complex multi-file tasks, consider doing it yourself instead

package/commands/codex-review.md

@@ -0,0 +1,35 @@
+# Codex Code Review
+
+Review the current changes using Codex as a second reviewer.
+
+## Instructions
+
+You are invoking Codex for a second-opinion code review. Follow these steps:
+
+1. **Determine what to review** based on `$ARGUMENTS`:
+   - If empty or "uncommitted": get unstaged changes via `git diff`. If empty, try staged changes via `git diff --cached`. If both empty, inform the user there are no changes to review.
+   - If it looks like a branch name: get changes via `git diff <branch>...HEAD`
+   - If it looks like a commit SHA: get changes via `git show <sha>`
+
+2. **Check the diff size**:
+   - If the diff is empty, tell the user and stop.
+   - If the diff exceeds 50,000 characters, summarize it first and warn that Codex will see a truncated version.
+
+3. **Call the `codex_exec` MCP tool** with:
+   - `prompt`: "Review the following code changes. For each finding, specify: severity (CRITICAL/HIGH/MEDIUM/LOW), file and line, description, and suggested fix.\n\nFocus on: bugs, security issues, performance problems, error handling gaps, and readability.\n\n```diff\n<the diff>\n```"
+   - `mode`: "exec"
+   - `requireGit`: true
+
+4. **Present findings** to the user:
+   - Group by severity (CRITICAL first)
+   - For each finding, add your own assessment: agree, disagree, or nuance
+   - Note anything Codex missed that you think is important
+   - Summarize actionable items at the end
+
+5. **If Codex found issues**, offer to fix them.
+
+## Important
+
+- Codex runs in **read-only mode** — it cannot modify files
+- Codex is a **peer, not an authority** — evaluate each finding critically
+- If the MCP tool returns an error, explain what happened and suggest remediation