# codex-cli

> Procedural CLI invocation details for the Codex agent

- Author: Aleksi Tuominen
- Repository: alexivison/ai-config
- Version: 20260206112641
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/alexivison/ai-config
- Web: https://mule.run/skillshub/@@alexivison/ai-config~codex-cli:20260206112641

---

---
name: codex-cli
description: Procedural CLI invocation details for the Codex agent
user-invocable: false
---

# Codex CLI Procedures

## Safety

Always use `-s read-only` sandbox mode. Never run Codex with write permissions.

## Supported Task Types

| Task | Command Pattern |
|------|-----------------|
| Code review | `codex exec -s read-only "Review these changes for bugs, security, maintainability"` |
| Architecture review | `codex exec -s read-only "Analyze architecture of these files for patterns and complexity"` |
| Plan review | `codex exec -s read-only "Review this plan for: {plan review checklist below}"` |
| Design decision | `codex exec -s read-only "Compare approaches: {options}"` |
| Debugging | `codex exec -s read-only "Analyze this error/behavior: {description}"` |
| Trade-off analysis | `codex exec -s read-only "Evaluate trade-offs between: {options}"` |

## Plan Review Checklist (CRITICAL)

When reviewing plans (DESIGN.md, PLAN.md, TASK*.md), include these checks in your Codex prompt:

### Data Flow Integrity
- [ ] Are ALL data transformation points mapped in DESIGN.md?
- [ ] If a field is added to proto, does it appear in ALL converters?
- [ ] Are params conversion functions checked (e.g., path A → path B adapters)?

### Existing Standards
- [ ] Are existing patterns referenced (e.g., DataSource, Repository)?
- [ ] Is naming consistent with codebase conventions?
- [ ] Are integration points with existing code identified?

### Cross-Task Consistency
- [ ] If TASK1 adds X to endpoints A and B, do separate tasks handle BOTH?
- [ ] Are task scope boundaries explicit (what IS and ISN'T in scope)?
- [ ] Do task scopes sum to complete coverage?

### Bug Prevention
- [ ] Could any field be silently dropped in a conversion?
- [ ] Are all code paths covered (all variants that share the schema)?
- [ ] Are adapter patterns identified where data might be lost?

**Example of scope mismatch to catch:**
> TASK1 adds `new_field` to schema affecting code paths A and B.
> TASK2 only handles path A → BUG: path B silently drops the field.

## Execution Process

1. **Understand the task** — What type of analysis is needed?
2. **Gather context** — Read relevant domain rules from `claude/rules/` or `.claude/rules/` if they exist
3. **Invoke Codex** — Run `codex exec -s read-only "..."` with appropriate prompt
4. **Parse output** — Extract key findings and verdict
5. **Cleanup** — Stop any background tasks before returning (see Cleanup Protocol)
6. **Return structured result** — Use the output format below

## Bash Execution Rules (CRITICAL)

**NEVER use `run_in_background: true`** when invoking `codex exec`. Always run synchronously. If you violate this rule accidentally, the Cleanup Protocol below will catch orphaned processes.

**Use extended timeout** for Codex CLI (it uses extended reasoning):
```
timeout: 300000  # 5 minutes - Codex needs time for deep analysis
```

Example invocation:
```bash
codex exec -s read-only "Your prompt here"
```
With Bash tool parameters: `{ "command": "codex exec -s read-only \"...\"", "timeout": 300000 }`

## Cleanup Protocol

**Fallback for accidental background execution.** If you mistakenly used `run_in_background: true` (violating Bash Execution Rules above), clean up before returning:

1. **Detect:** If Bash tool results contain a `task_id`, a background task was created
2. **Stop:** Use `TaskStop` to terminate the orphaned process:
   ```
   TaskStop with task_id: "{task_id}"
   ```
3. **Handle errors:** If TaskStop fails, log the task ID in your response and continue — the main agent will handle escalation
4. **Return:** Only then return your structured response

This defense-in-depth prevents orphaned Codex processes from continuing after you've returned.

## Output Format

Always return structured output for the main agent to parse:

```markdown
## Codex Analysis

**Task:** {task type - review/architecture/plan/design/debug/trade-off}
**Scope:** {files or topic analyzed}

### Findings
{Key findings from Codex, with file:line references where applicable}

### Recommendations
- {Actionable items}

### Verdict
**APPROVE** | **REQUEST_CHANGES** | **NEEDS_DISCUSSION**
{One sentence reason}
```

### For Code/Architecture/Plan Review (PR workflow)

When used for pre-PR review, include "CODEX APPROVED" explicitly on approval:

```markdown
## Codex Analysis

**Task:** Code + Architecture Review
**Scope:** {changed files}

### Findings
{Analysis from Codex}

### Verdict
**APPROVE** — CODEX APPROVED
{Reason}
```

## Iteration Support

When invoked with iteration parameters:
- `iteration`: Current attempt (1, 2, 3)
- `previous_feedback`: What was found before

On iteration 2+:
1. First verify previous issues are addressed
2. Check for new issues introduced by fixes
3. After 3 iterations without resolution → NEEDS_DISCUSSION