Skill: adamsardo/codex-sub-agents (version 1.0.0)

--- name: codex-cli description: "Use OpenAI Codex CLI for coding tasks. Triggers: codex, code review, fix CI, refactor code, implement feature, coding agent, gpt-5-codex. Enables Clawdbot to delegate coding work to Codex CLI as a subagent or direct tool." --- # 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)

path: cli-reference.md
content: # Codex CLI Quick Reference

## Commands

| Command | Description |
|---------|-------------|
| `codex` | Launch interactive TUI |
| `codex exec <prompt>` | Non-interactive execution |
| `codex resume [--last]` | Continue previous session |
| `codex login` | Authenticate via OAuth |
| `codex logout` | Clear credentials |
| `codex apply <task_id>` | Apply Codex Cloud diff locally |
| `codex completion <shell>` | Generate shell completions |
| `codex mcp <subcommand>` | Manage MCP servers |
| `codex mcp-server` | Run Codex as MCP server |
| `codex cloud [exec]` | Manage Codex Cloud tasks |
| `codex sandbox` | Run commands in sandbox |

## Global Flags

| Flag | Values | Description |
|------|--------|-------------|
| `--model, -m` | string | Override model |
| `--image, -i` | path[,path...] | Attach images |
| `--cd, -C` | path | Set working directory |
| `--add-dir` | path | Add writable root |
| `--sandbox, -s` | read-only, workspace-write, danger-full-access | Sandbox policy |
| `--ask-for-approval, -a` | untrusted, on-failure, on-request, never | Approval mode |
| `--full-auto` | boolean | workspace-write + approve on failure |
| `--yolo` | boolean | No approvals or sandbox (dangerous) |
| `--profile, -p` | string | Config profile name |
| `--oss` | boolean | Use local Ollama |
| `--search` | boolean | Enable web search |
| `--json` | boolean | JSON output |

## codex exec Flags

| Flag | Description |
|------|-------------|
| `PROMPT` | Task instruction (or `-` for stdin) |
| `--skip-git-repo-check` | Allow non-Git directories |
| All global flags | Inherited |

## codex mcp Subcommands

| Subcommand | Description |
|------------|-------------|
| `list [--json]` | List configured MCP servers |
| `get <n> [--json]` | Show server config |
| `add <n> -- <cmd...>` | Add stdio server |
| `add <n> --url <url>` | Add HTTP server |
| `remove <n>` | Delete server |
| `login <n>` | OAuth for HTTP server |
| `logout <n>` | Clear OAuth |

## Slash Commands (TUI)

| Command | Description |
|---------|-------------|
| `/approvals` | Set approval mode |
| `/compact` | Summarize to free context |
| `/diff` | Show Git diff |
| `/exit`, `/quit` | Exit CLI |
| `/feedback` | Send logs to maintainers |
| `/init` | Generate AGENTS.md |
| `/logout` | Sign out |
| `/mcp` | List MCP tools |
| `/mention <path>` | Attach file |
| `/model` | Switch model |
| `/new` | Fresh conversation |
| `/review` | Code review |
| `/status` | Session info |
| `/undo` | Revert last turn |

## Approval Modes

| Mode | Read | Edit | Execute | Network |
|------|------|------|---------|---------|
| Auto | ✓ | ✓ (workspace) | ✓ (workspace) | Ask |
| Read Only | ✓ | Ask | Ask | Ask |
| Full Access | ✓ | ✓ | ✓ | ✓ |

## Sandbox Policies

| Policy | Description |
|--------|-------------|
| `read-only` | No writes allowed |
| `workspace-write` | Writes in workspace + /tmp |
| `danger-full-access` | No restrictions |

## Config File

Location: `~/.codex/config.toml`

```toml
[model]
default = "gpt-5-codex"

[features]
web_search_request = true
rmcp_client = true

[sandbox_workspace_write]
network_access = true

[mcp_servers]
# Defined via codex mcp add
```

## Custom Prompts

Location: `~/.codex/prompts/<n>.md`

```markdown
---
description: Short description
argument-hint: KEY=<value>
---

Prompt content with $KEY placeholders.
$1-$9 for positional args.
$ARGUMENTS for all args.
$$ for literal dollar sign.
```

## Session Files

Location: `~/.codex/sessions/`

## Auth Files

Location: `~/.codex/auth.json`

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error / task failure |
| Non-zero | git apply conflict, auth failure, etc |


path: clawdbot-integration.md
content: # Clawdbot + Codex CLI Integration Patterns

## Overview

Clawdbot can integrate with OpenAI Codex CLI in multiple ways:
1. **Provider**: Use `openai-codex` provider for ChatGPT Pro subscription routing
2. **Exec tool**: Call `codex exec` directly from Clawdbot
3. **Subagent**: Spawn a dedicated coding subagent
4. **CLI Backend**: Fallback text-only mode
5. **MCP Server**: Run Codex as MCP server for tool access

## Pattern 1: OpenAI Codex Provider

Use your ChatGPT Pro/Plus subscription with Clawdbot's built-in `openai-codex` provider.

### Config

```json5
// ~/.clawdbot/clawdbot.json
{
  agents: {
    defaults: {
      model: { 
        primary: "openai-codex/gpt-5.2",
        fallbacks: ["anthropic/claude-sonnet-4-5"]
      },
      models: {
        "openai-codex/gpt-5.2": { alias: "Codex" },
        "anthropic/claude-opus-4-5": { alias: "Opus" }
      }
    }
  }
}
```

### Auth Sync

Clawdbot auto-syncs OAuth tokens from Codex CLI:
- Source: `~/.codex/auth.json`
- Target: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
- Profile key: `openai-codex:codex-cli`

### Onboarding

```bash
clawdbot onboard --auth-choice openai-codex
# Or if Codex CLI is already authenticated:
codex-cli  # Clawdbot detects and imports tokens
```

## Pattern 2: Direct Exec Tool

Call Codex CLI directly from Clawdbot's exec tool for coding tasks.

### Usage

```bash
# From Clawdbot chat
> Fix the TypeScript errors in src/components

# Clawdbot runs:
exec codex exec --full-auto --cd ~/projects/medreport "fix TypeScript errors in src/components"
```

### Best Practices

- Use `--full-auto` for trusted repos
- Use `--cd` to target specific project
- Use `--json` for parsing results
- Check exit code for success/failure

### Example AGENTS.md Instruction

```markdown
## Coding Tasks

When asked to fix code, refactor, or implement features:

1. Use the codex CLI for complex coding tasks
2. Command: `codex exec --full-auto --cd <project_path> "<task>"`
3. For large changes, use interactive mode: `codex --cd <path>`
4. Report the result back to the user
```

## Pattern 3: Coding Subagent

Spawn a dedicated subagent for coding that uses Codex or runs in a sandboxed environment.

### Config

```json5
{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/clawd",
        model: { primary: "anthropic/claude-opus-4-5" }
      },
      {
        id: "coder", 
        workspace: "~/clawd-coder",
        model: { primary: "openai-codex/gpt-5.2" },
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "rw"
        },
        tools: {
          allow: ["exec", "read", "write", "edit", "apply_patch", "process"],
          deny: ["browser", "canvas", "cron"]
        },
        subagents: {
          allowAgents: ["main"]  // Main can spawn coder
        }
      }
    ]
  },
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["main", "coder"]
    }
  }
}
```

### Usage

From main agent:
```
sessions_spawn task="Refactor the Dashboard component to use React Query" agentId="coder"
```

The coder subagent runs with Codex model, announces result back to main chat.

## Pattern 4: CLI Backend Fallback

Configure Codex CLI as a text-only fallback when API providers fail.

### Config

```json5
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "codex",
          args: ["exec", "--full-auto"],
          output: "text"
        }
      }
    }
  }
}
```

### Notes

- CLI backends are text-only (no tool calls)
- Used as fallback when API auth fails or rate limits
- Sessions managed by Codex internally
- Good for emergencies but less capable

## Pattern 5: MCP Server Mode

Run Codex as an MCP server that Clawdbot can call.

### Setup

```bash
# Terminal 1: Start Codex MCP server
codex mcp-server

# Configure Clawdbot to connect
# In ~/.clawdbot/clawdbot.json or via skill
```

### Skill Integration

Create a skill that declares Codex MCP:

```markdown
---
name: codex-mcp
mcp:
  - name: codex
    command: codex
    args: ["mcp-server"]
---
```

## Model Handoff Patterns

### Opus → Codex Handoff

Use Opus for planning, Codex for implementation:

```json5
{
  agents: {
    list: [
      {
        id: "planner",
        model: { primary: "anthropic/claude-opus-4-5" },
        subagents: { allowAgents: ["coder"] }
      },
      {
        id: "coder",
        model: { primary: "openai-codex/gpt-5.2" }
      }
    ]
  }
}
```

Workflow:
1. User asks planner for architecture
2. Planner designs solution
3. Planner spawns coder subagent with implementation task
4. Coder implements and announces result
5. Planner reviews and responds to user

### Channel-Based Routing

Route WhatsApp to fast model, Telegram to Codex:

```json5
{
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "coder", match: { channel: "telegram" } }
  ]
}
```

## Cost Optimization

### Strategy 1: Subagent Model Override

```json5
{
  agents: {
    defaults: {
      subagents: {
        model: "openai/gpt-5-mini"  // Cheaper for subagents
      }
    }
  }
}
```

### Strategy 2: Task-Based Routing

- Quick questions → Sonnet/Mini
- Code review → Codex
- Deep analysis → Opus

### Strategy 3: Fallback Chain

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openai-codex/gpt-5.2",
          "openai/gpt-5-mini"
        ]
      }
    }
  }
}
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Codex auth not syncing | Run `codex login` then restart gateway |
| Subagent not spawning | Check `subagents.allowAgents` includes caller |
| Exec timeout | Increase `tools.exec.timeoutSec` |
| Sandbox blocks codex | Add codex binary to allowed paths |
| Wrong workspace | Use `--cd` flag explicitly |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)