Skip to content

majiayu000/spellbook / skills/codex-agent

codex-agent

Verified

Use when you want a second-opinion review via Codex CLI, cross-verification after another agent implements changes, debugging help, or alternative implementation proposals. Requires Codex CLI to be installed and authenticated.

FileKindSize
README.mdmarkdown4.9 KB
SKILL.mdskill md7.5 KB
advanced.mdmarkdown3.8 KB
examples.mdmarkdown4.3 KB
sandbox-modes.mdmarkdown2.0 KB
scripts/check-codex.shexecutablescript1.0 KB
scripts/codex-wrapper.shexecutablescript3.5 KB
# Codex Agent Skill

A Spellbook skill for optional Codex-based second-opinion reviews, cross-verification, debugging, and alternative implementation proposals.

## Core Workflow

```
Code Review Request
       ↓
   ┌───────────────────┐
   │  Codex Reviews    │  ← Primary agent calls Codex CLI
   │  (read-only)      │
   └───────────────────┘
       ↓
   ┌───────────────────┐
   │  Codex Feedback   │  ← Issues with file:line:severity
   └───────────────────┘
       ↓
   ┌───────────────────┐
   │  Primary Agent    │  ← Primary agent fixes code using Edit tool
   │  Fixes            │
   └───────────────────┘
       ↓
   ┌───────────────────┐
   │  (Optional)       │  ← Codex re-verifies
   │  Re-verify        │
   └───────────────────┘
```

## Features

- **Second-Opinion Review**: Use Codex when you want an independent review pass
- **Guided Fixes**: Apply fixes based on Codex's specific feedback
- **Structured Output**: Codex provides file paths, line numbers, and severity levels
- **Re-verification**: Optional second pass to confirm fixes

## Prerequisites

### Install Codex CLI

```bash
# Via npm
npm install -g @openai/codex

# Via Homebrew (macOS)
brew install --cask codex
```

### Authenticate

```bash
codex login
```

## Installation

### Option 1: User-level (all projects)

```bash
cp -r codex-agent ~/.claude/skills/codex-agent
cp -r codex-agent ~/.agents/skills/codex-agent
```

### Option 2: Project-level

```bash
mkdir -p .claude/skills
cp -r codex-agent .claude/skills/codex-agent

mkdir -p .agents/skills
cp -r codex-agent .agents/skills/codex-agent
```

## Usage

When you ask for a Codex second opinion, the primary agent will:

1. **Call Codex** to perform the review
2. **Parse feedback** from Codex (file, line, severity, issue, fix)
3. **Apply fixes** using Edit tool only when the user asked for fixes
4. **Optionally re-verify** with Codex

### Example Prompts

```
Review my authentication code and fix any issues
```

```
Do a security review of src/api/ and apply the fixes
```

```
Review the recent changes and fix problems Codex finds
```

## Workflow Details

### Step 1: Codex Review

The primary agent executes:
```bash
REPORT="$(mktemp -t codex-review.XXXXXX.md)"
codex exec -C /project -s read-only -o "$REPORT" \
  "Review src/auth/. Check for security, performance, code quality.
   Provide file paths, line numbers, and specific fixes."
cat "$REPORT"
```

### Step 2: Parse Feedback

Codex outputs structured feedback:
```
- File: src/auth/login.ts
- Line: 45
- Severity: high
- Issue: SQL injection vulnerability
- Fix: Use parameterized query instead of string concatenation
```

### Step 3: Primary Agent Applies Fixes

The primary agent reads the file, applies the fix with Edit tool:
```
old_string: `SELECT * FROM users WHERE id = '${userId}'`
new_string: `SELECT * FROM users WHERE id = $1`, [userId]
```

### Step 4: Re-verify (Optional)

```bash
codex exec -C /project -s read-only \
  "Verify fixes in src/auth/login.ts. Confirm SQL injection is resolved."
```

## File Structure

```
codex-agent/
├── SKILL.md           # Main skill with optional Codex review workflow
├── sandbox-modes.md   # Sandbox security documentation
├── examples.md        # Usage examples
├── advanced.md        # Advanced configuration
├── scripts/
│   ├── codex-wrapper.sh   # Helper wrapper script
│   └── check-codex.sh     # Installation checker
└── README.md          # This file
```

## Configuration

### Recommended Permissions

Add to `.claude/settings.local.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(REPORT=*)",
      "Bash(DIFF_REPORT=*)",
      "Bash(codex:*)",
      "Bash(mktemp:*)",
      "Bash(cat:*)"
    ]
  }
}
```

## Sandbox Modes

| Mode | Description |
|------|-------------|
| `read-only` | No file writes (used for reviews) |
| `workspace-write` | Write to project directory |
| `danger-full-access` | Unrestricted (use with caution) |

Use `read-only` for review and re-verification by default. Treat
`danger-full-access`, `--dangerously-bypass-approvals-and-sandbox`,
`--dangerously-bypass-hook-trust`, and `--skip-git-repo-check` as high-impact
options that need explicit user approval.

## Troubleshooting

### Codex not found

```bash
npm install -g @openai/codex
```

### Authentication issues

```bash
codex logout
codex login
```

## License

MIT

## References

- [OpenAI Codex CLI](https://github.com/openai/codex)
- [Claude Code Skills](https://code.claude.com/docs/en/skills)
- [Codex Documentation](https://developers.openai.com/codex)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall