Skip to content
Back to search

codex-skill

Give Claude Code a second opinion using OpenAI Codex - automatic plan review via hooks

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cathrynlavery--codex-skill/badge.svg)](/listings/cathrynlavery--codex-skill)

HTML

<a href="/listings/cathrynlavery--codex-skill"><img src="/api/listings/cathrynlavery--codex-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A: Install as Claude Code plugin (recommended)

claude plugin marketplace add cathrynlavery/codex-skill
claude plugin install codex-skill@codex-skill

This auto-registers both the `/codex` skill and the automatic plan review hook. No manual configuration needed.

Option B: Manual installation

1. Install the skill

git clone https://github.com/cathrynlavery/codex-skill.git
mkdir -p ~/.claude/skills/codex
cp codex-skill/skills/codex/SKILL.md ~/.claude/skills/codex/

2. Set up automatic plan review

Copy the hook script:

mkdir -p ~/.claude/hooks
cp codex-skill/hooks/plan-review.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/plan-review.sh

Add to your `~/.claude/settings.json`:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/plan-review.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "codex-skill",
  3. "description": "Single-plugin marketplace for codex-skill",
  4. "owner": {
  5. "name": "cathrynlavery"
  6. },
  7. "plugins": [
  8. {
  9. "name": "codex-skill",
  10. "source": "./",
  11. "description": "Give Claude Code a second opinion using OpenAI Codex - automatic plan review via hooks"
  12. }
  13. ]
  14. }
README.md · README · 171 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Codex Skill for Claude Code
  2. Give Claude Code a "second opinion" by letting it consult OpenAI's Codex CLI for independent verification.
  3. ## What It Does
  4. When Claude Code creates a plan, Codex automatically reviews it before you approve. Two AIs checking each other's work catches more edge cases.
  5. **Automatic review on:**
  6. - Every plan Claude creates (via hook)
  7. - Architecture decisions
  8. - Implementation approaches
  9. **Manual use for:**
  10. - Researching unfamiliar APIs or libraries
  11. - Verifying complex code patterns
  12. - Getting alternative perspectives
  13. ## Prerequisites
  14. Install [Codex CLI](https://github.com/openai/codex):
  15. ```bash
  16. npm install -g @openai/codex
  17. ```
  18. Configure your OpenAI API key.
  19. ## Supported Models
  20. The skill supports the current visible Codex lineup. Automatic plan reviews do not pin a model; they inherit your configured Codex default.
  21. | Model | Default effort | Supported efforts | Best for |
  22. |-------|----------------|-------------------|----------|
  23. | `gpt-6-astra` | `low` | `low`–`ultra` | Most capable option for difficult architecture, debugging, security, and long-horizon work |
  24. | `gpt-6.1-sol` | `medium` | `low`–`ultra` | Latest workhorse for coding and everyday work |
  25. | `gpt-6.1-terra` | `low` | `low`–`ultra` | Balanced everyday coding and review |
  26. | `gpt-6-sol` | `medium` | `low`–`ultra` | Previous-generation workhorse |
  27. | `gpt-6-luna` | `medium` | `low`–`max` | Fast and affordable checks |
  28. `gpt-5.6-sol`, `gpt-5.6-terra` and `gpt-5.6-luna` are still listed as older generations.
  29. ## Installation
  30. ### Option A: Install as Claude Code plugin (recommended)
  31. ```bash
  32. claude plugin marketplace add cathrynlavery/codex-skill
  33. claude plugin install codex-skill@codex-skill
  34. ```
  35. This auto-registers both the `/codex` skill and the automatic plan review hook. No manual configuration needed.
  36. ### Option B: Manual installation
  37. #### 1. Install the skill
  38. ```bash
  39. git clone https://github.com/cathrynlavery/codex-skill.git
  40. mkdir -p ~/.claude/skills/codex
  41. cp codex-skill/skills/codex/SKILL.md ~/.claude/skills/codex/
  42. ```
  43. #### 2. Set up automatic plan review
  44. Copy the hook script:
  45. ```bash
  46. mkdir -p ~/.claude/hooks
  47. cp codex-skill/hooks/plan-review.sh ~/.claude/hooks/
  48. chmod +x ~/.claude/hooks/plan-review.sh
  49. ```
  50. Add to your `~/.claude/settings.json`:
  51. ```json
  52. {
  53. "hooks": {
  54. "PostToolUse": [
  55. {
  56. "matcher": "ExitPlanMode",
  57. "hooks": [
  58. {
  59. "type": "command",
  60. "command": "~/.claude/hooks/plan-review.sh",
  61. "timeout": 120
  62. }
  63. ]
  64. }
  65. ]
  66. }
  67. }
  68. ```
  69. ## How It Works
  70. ```
  71. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  72. │ Claude │────>│ ExitPlanMode│────>│ Codex │
  73. │ creates plan│ │ (hook) │ │ reviews │
  74. └─────────────┘ └─────────────┘ └─────────────┘
  75. │
  76. v
  77. ┌─────────────┐
  78. │ You approve │
  79. │ with context│
  80. └─────────────┘
  81. ```
  82. The hook intercepts `ExitPlanMode` and reads the plan from `tool_response.plan` (the field where Claude Code stores the plan content). It passes the plan to Codex for review and displays the result before you approve.
  83. Automatic plan reviews always use `codex exec --sandbox read-only` to restrict model-generated shell commands to read-only access. Manual consultations default to the same mode; explicit requests to implement changes use `--sandbox workspace-write`. If Codex fails, the hook reports that the review was skipped on stderr and exits successfully so your workflow can continue.
  84. Codex reviews for:
  85. - Potential issues or risks
  86. - Missing steps
  87. - Better alternatives
  88. - Edge cases not addressed
  89. ## Manual Usage
  90. Invoke directly:
  91. ```
  92. /codex
  93. ```
  94. Or ask Claude:
  95. > "Can you verify this approach with Codex?"
  96. > "Get a second opinion on this architecture"
  97. These consultation requests use read-only mode. To have Codex make changes, explicitly request implementation, for example:
  98. > "Have Codex review and fix the parser bug, then run the relevant tests."
  99. An explicit implementation request uses `--sandbox workspace-write` for edits and checks within the requested scope. No additional confirmation is needed for that same scope. Reviews do not automatically switch modes when a check needs to write files; they report the limitation. The automatic plan-review hook stays read-only even when the plan describes future edits.
  100. The skill uses your configured Codex default. For the hardest questions (novel architecture, deep analysis, or security review), explicitly select `gpt-6-astra` with high or greater reasoning effort. For trivial fact checks, select `gpt-6-luna`.
  101. ## Example Output
  102. ```
  103. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  104. CODEX SECOND OPINION ON PLAN
  105. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  106. LGTM - Plan covers the main implementation steps.
  107. Minor suggestions:
  108. - Consider adding error handling for the API timeout case
  109. - Step 3 could be split into separate DB migration and code changes
  110. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  111. ```
  112. ## Troubleshooting
  113. **Plan review skipped:** The hook prints `codex-skill: plan review skipped (codex exited <status>; check installation, authentication, and configuration).` on stderr when Codex fails, while remaining non-blocking. Make sure Codex CLI is installed (`codex --version`), on your PATH, authenticated, and configured correctly. Exit status 127 usually means the executable could not be found.
  114. **No plan content found:** The hook reads from `tool_response.plan` (primary) with fallbacks to `tool_response.filePath` and filesystem search. If you're seeing issues, check that you're using a current version of Claude Code.
  115. ## Development
  116. Run the hook regression tests (requires Python 3, Bash, and `jq`; uses a stub Codex executable):
  117. ```bash
  118. python3 -m unittest discover -s tests -v
  119. ```
  120. ## License
  121. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.