codex-cli

What this skill does

# OpenAI Codex CLI Skill

Use OpenAI Codex CLI (`codex`) for coding tasks including code review, refactoring, bug fixes, CI repairs, and feature implementation. Codex CLI runs locally on your machine with full filesystem access.

## When to Use

- User asks for code changes, refactoring, or implementation
- CI/build failures need fixing
- Code review before commit/push
- Large codebase exploration or explanation
- Tasks requiring file editing + command execution
- When GPT-5-Codex model strengths are needed (code generation, tool use)

## Installation & Auth

Codex CLI requires ChatGPT Plus/Pro/Business/Enterprise subscription.

```bash
# Install
npm i -g @openai/codex

# Authenticate (opens browser for OAuth)
codex login

# Or use API key
printenv OPENAI_API_KEY | codex login --with-api-key

# Verify auth
codex login status
```

## Core Commands

### Interactive Mode (TUI)
```bash
codex                           # Launch interactive terminal UI
codex "explain this codebase"   # Start with a prompt
codex --cd ~/projects/myapp     # Set working directory
```

### Non-Interactive (Scripting)
```bash
codex exec "fix the CI failure"                    # Run and exit
codex exec --full-auto "add input validation"      # Auto-approve workspace writes
codex exec --json "list all API endpoints"         # JSON output for parsing
codex exec -i screenshot.png "match this design"   # With image input
```

### Session Management
```bash
codex resume               # Pick from recent sessions
codex resume --last        # Continue most recent
codex resume <SESSION_ID>  # Resume specific session
```

## Slash Commands (In TUI)

| Command | Purpose |
|---------|---------|
| `/model` | Switch model (gpt-5-codex, gpt-5) |
| `/approvals` | Set approval mode (Auto, Read Only, Full Access) |
| `/review` | Code review against branch, uncommitted changes, or specific commit |
| `/diff` | Show Git diff including untracked files |
| `/compact` | Summarize conversation to free context |
| `/init` | Generate AGENTS.md scaffold |
| `/status` | Show session config and token usage |
| `/undo` | Revert most recent turn |
| `/new` | Start fresh conversation |
| `/mcp` | List configured MCP tools |
| `/mention <path>` | Attach file to conversation |

## Approval Modes

| Mode | Behavior |
|------|----------|
| **Auto** (default) | Read/edit/run commands in workspace; asks for outside access |
| **Read Only** | Browse files only; requires approval for changes |
| **Full Access** | Full machine access including network (use sparingly) |

## Key Flags

| Flag | Purpose |
|------|---------|
| `--model, -m <model>` | Override model (gpt-5-codex, gpt-5) |
| `--cd, -C <path>` | Set working directory |
| `--add-dir <path>` | Add additional writable roots |
| `--image, -i <path>` | Attach image(s) to prompt |
| `--full-auto` | Workspace write + approve on failure |
| `--sandbox <mode>` | read-only, workspace-write, danger-full-access |
| `--json` | Output newline-delimited JSON |
| `--search` | Enable web search tool |

## Clawdbot Integration Patterns

### Pattern 1: Direct exec Tool
Call Codex from Clawdbot's exec tool for coding tasks:

```bash
# In Clawdbot session
exec codex exec --full-auto --cd ~/projects/medreport "fix the TypeScript errors in src/components"
```

### Pattern 2: Subagent Delegation
Spawn a coding subagent that uses Codex:

```json5
// In agents.defaults or per-agent config
{
  agents: {
    list: [
      {
        id: "coder",
        workspace: "~/clawd-coder",
        model: "openai-codex/gpt-5.2",  // Uses Codex auth
        tools: {
          allow: ["exec", "read", "write", "edit", "apply_patch", "process"]
        }
      }
    ]
  }
}
```

### Pattern 3: CLI Backend Fallback
Configure Codex as a text-only fallback:

```json5
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "codex",
          args: ["exec", "--full-auto"],
          output: "text",
          sessionArg: null  // Codex manages its own sessions
        }
      }
    }
  }
}
```

### Pattern 4: MCP Server Mode
Run Codex as an MCP server for other agents:

```bash
codex mcp-server  # Exposes Codex tools via stdio MCP
```

## Clawdbot Config: OpenAI Codex Provider

Use your ChatGPT Pro subscription via the `openai-codex` provider:

```json5
{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.2" },
      models: {
        "openai-codex/gpt-5.2": { alias: "Codex" },
        "anthropic/claude-opus-4-5": { alias: "Opus" }
      }
    }
  }
}
```

Auth syncs automatically from `~/.codex/auth.json` to Clawdbot's auth profiles.

## Code Review Workflow

```bash
# Interactive review
codex
/review  # Choose: branch, uncommitted, or specific commit

# Non-interactive
codex exec "review the changes in this PR against main branch"
```

## Multi-Directory Projects

```bash
# Work across monorepo packages
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

# Or in TUI
codex --cd ~/projects/myapp --add-dir ~/projects/shared-lib
```

## Custom Slash Commands

Create reusable prompts in `~/.codex/prompts/`:

```markdown
<!-- ~/.codex/prompts/pr.md -->
---
description: Prepare and open a draft PR
argument-hint: [BRANCH=<name>] [TITLE="<title>"]
---

Create branch `dev/$BRANCH` if specified.
Stage and commit changes with a clear message.
Open a draft PR with title $TITLE or auto-generate one.
```

Invoke: `/prompts:pr BRANCH=feature-auth TITLE="Add OAuth flow"`

## MCP Integration

Add MCP servers to extend Codex:

```bash
# Add stdio server
codex mcp add github -- npx @anthropic/mcp-server-github

# Add HTTP server
codex mcp add docs --url https://mcp.deepwiki.com/mcp

# List configured
codex mcp list
```

## Web Search

Enable in `~/.codex/config.toml`:

```toml
[features]
web_search_request = true

[sandbox_workspace_write]
network_access = true
```

Then Codex can search for current docs, APIs, etc.

## Best Practices

1. **Start with `/init`** to create AGENTS.md with repo-specific instructions
2. **Use `/review` before commits** for AI code review
3. **Set `/approvals` appropriately** — Auto for trusted repos, Read Only for exploration
4. **Use `--add-dir`** for monorepos instead of `danger-full-access`
5. **Resume sessions** to maintain context across coding sessions
6. **Attach images** for UI work, design specs, error screenshots

## Example Workflows

### Fix CI Failure
```bash
codex exec --full-auto "The CI is failing on the lint step. Fix all ESLint errors."
```

### Refactor Component
```bash
codex exec --cd src/components "Refactor UserProfile.tsx to use React Query instead of useEffect for data fetching"
```

### Implement Feature from Spec
```bash
codex exec -i spec.png --cd ~/projects/app "Implement this feature based on the design spec"
```

### Code Review PR
```bash
codex exec "Review the diff between main and feature/auth branch. Focus on security issues."
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Auth fails | Run `codex logout` then `codex login` |
| Commands blocked | Check `/approvals`, may need `--full-auto` |
| Out of context | Use `/compact` to summarize |
| Wrong directory | Use `--cd` flag or check `/status` |
| Model unavailable | Verify subscription tier supports model |

## References

- [Codex CLI Overview](https://developers.openai.com/codex/cli)
- [Codex CLI Features](https://developers.openai.com/codex/cli/features)
- [Codex CLI Reference](https://developers.openai.com/codex/cli/reference)
- [Slash Commands Guide](https://developers.openai.com/codex/cli/slash-commands)
- [AGENTS.md Spec](https://agents.md)
- [Codex GitHub](https://github.com/openai/codex)