# Codex Collab

> Codex Collaboration Skill

- Skill: `masup9/codex-collab` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add masup9/codex-collab`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masup9/codex-collab/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: masup9 (https://skillmd.com/u/masup9)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/masup9/codex-collab

---


# Codex Collaboration Skill

Coordinate tasks between Claude Code and OpenAI Codex CLI using adaptive workflow selection based on model strengths.

## Overview

This skill enables effective collaboration between two AI systems with **two workflow modes**:

**Codex-Leads (従来):**
- **Codex**: Planning, code review, architectural decisions
- **Claude Code**: Implementation, file operations, testing

**Claude-Leads (新規):**
- **Claude Code**: Deep analysis, planning, code review
- **Codex**: Fast implementation with workspace-write sandbox

デフォルト（`auto`）は常に **Codex-Leads** を選択。`claude-leads` は `workflow: claude-leads` を明示指定した場合のみ有効。

**通信方式**: MCP primary + Bash fallback のデュアルモード。
- **MCP mode** (`mcp__codex__codex`/`codex-reply`): ステートフルな会話（threadId で文脈保持）。ANSI 除去不要、ファイル I/O 不要。
- **Bash mode** (`codex exec`/`codex review`): ステートレス実行。`codex_run_exec()` が入出力、ANSI 除去、exit code ハンドリングを統合処理。MCP 未設定時の自動フォールバック。

## Prerequisites

Before starting collaboration:
1. **MCP tools check** (primary): Try `mcp__codex__codex` with a lightweight probe. If available → MCP mode.
2. **CLI fallback**: If MCP unavailable, verify `codex` CLI is available: `which codex` or `codex --version`
3. Verify `codex exec` works (Bash mode): `codex exec -s read-only - <<< "test"`
4. Check for project settings in `.claude/codex-collab.local.md`
5. If neither MCP nor CLI available, inform user and proceed with Claude-only mode

## Workflow: Review Type (Default)

### Phase 1: Task Analysis

When receiving a task for collaboration:

1. Parse the task description to identify:
   - Core objective
   - Affected files/components
   - Complexity level
   - Required context

2. Gather relevant context:
   - Read related files
   - Check existing tests
   - Review recent changes

### Phase 2: Request Plan from Codex

**MCP mode (primary):**
```
mcp__codex__codex(prompt: "[planning prompt]", sandbox: "read-only")
→ Returns response + threadId (saved for Phase 4)
```

**Bash mode (fallback):**
```bash
source scripts/codex-helpers.sh
PROMPT_FILE=$(codex_write_prompt "$PLANNING_PROMPT" "plan")
OUTPUT_FILE="$(codex_tmp_path 'codex-plan-output.md')"
codex_run_exec "$PROMPT_FILE" "$OUTPUT_FILE" "read-only"
```

Read results from tool response (MCP) or output file (Bash).

### Phase 3: Implement Based on Plan

After receiving Codex's plan:

1. Validate the plan is reasonable
2. Present plan to user for confirmation
3. Execute implementation step by step
4. Track changes made

### Phase 4: Request Review from Codex

After implementation:

1. **Stage changes for Codex visibility** (important!):
```bash
git add -A
git reset -- tmp/ 2>/dev/null || true
```
> **Why?** Staging ensures all changes are visible to Codex regardless of its file discovery method.

2. Run review (mode-dependent):

**MCP mode (primary):**
```
# Get diff, embed in prompt, continue same thread from Phase 2
mcp__codex__codex-reply(threadId: "[from Phase 2]", prompt: "[review prompt with diff]")
→ Parse verdict directly from response (no codex_infer_verdict needed)
```

**Bash mode (fallback):**
```bash
source scripts/codex-helpers.sh
REVIEW_OUTPUT="$(codex_tmp_path 'codex-review-output.md')"
codex_run_review "$REVIEW_OUTPUT" "$MODEL" || REVIEW_EXIT=$?

if [ "${REVIEW_EXIT:-0}" -ne 0 ]; then
  REVIEW_PROMPT_FILE=$(codex_write_prompt "$REVIEW_PROMPT" "review")
  codex_run_exec "$REVIEW_PROMPT_FILE" "$REVIEW_OUTPUT" "read-only"
fi
```

3. Parse verdict and findings (Bash mode):
```bash
RESPONSE=$(cat "$REVIEW_OUTPUT")
VERDICT=$(codex_infer_verdict "$RESPONSE") || true
FINDINGS=$(codex_extract_review_findings "$RESPONSE")
```

The review uses `[P1]-[P4]` priority markers as the primary source for verdict inference:
- `[P1]`/`[P2]` → fail
- `[P3]`/`[P4]` → conditional
- No findings + sufficient output → pass
- Metadata block (`verdict: pass/conditional/fail`) is also supported as an alternative

### Phase 5: Handle Review Result

Based on review verdict:

**Pass**: Report completion to user

**Conditional**:
1. Apply suggested improvements
2. Re-request review if significant changes

**Fail**:
1. Analyze failure reasons
2. Either fix issues or escalate to user

## Settings and Configuration

### Reading Project Settings

Check for `.claude/codex-collab.local.md` in project root:

```markdown
---
sandbox: read-only
language: ja
---

# Project-specific instructions
```

Parse YAML frontmatter for:
- `model`: Codex model to use (omit to use the Codex default from `~/.codex/config.toml`)
- `sandbox`: read-only | workspace-write | danger-full-access
- `workflow`: Workflow mode (auto | codex-leads | claude-leads, default: auto; auto は常に codex-leads を選択)
- `exchange.enabled`: Enable planning exchange (default: true, codex-leads only)
- `exchange.max_iterations`: Maximum rounds for multi-turn exchange (default: 3)
- `exchange.user_confirm`: When to ask user confirmation (never | always | on_important)
- `exchange.history_mode`: How to handle history (full | summarize; Bash fallback only — MCP threads preserve history)
- `review.enabled`: Enable review iteration (default: true, codex-leads only)
- `review.max_iterations`: Maximum rounds for review iteration (default: 5)
- `review.max_verdict_retries`: Retries when verdict is missing/unclear (default: 3)
- `review.user_confirm`: When to ask user confirmation for reviews (default: never)
- `claude_leads.sandbox`: Sandbox for Codex implementation (default: workspace-write)
- `claude_leads.consult_codex`: Enable plan consultation phase (default: true)
- `claude_leads.safety_checkpoint`: Pre-implementation checkpoint (stash | wip-commit | none, default: stash)
- `claude_leads.review.max_iterations`: Max review-fix iterations (default: 3)
- `codex.wait_timeout`: Max execution time for `codex exec` in seconds (default: 180, max: 600; Bash fallback only)

### Settings Priority

Apply settings in this order (later overrides earlier):

1. **Safe defaults**: sandbox=read-only
2. **Global settings**: ~/.claude/codex-collab.local.md
3. **Project settings**: .claude/codex-collab.local.md
4. **Command arguments**: Explicit user request

### Safe Defaults

Always start with secure defaults:
- `workflow: auto` - 常に codex-leads を選択（claude-leads は明示指定時のみ）
- `sandbox: read-only` - Codex cannot modify files (codex-leads)
- `exchange.enabled: true` - Planning exchange enabled by default
- `exchange.max_iterations: 3` - Prevent runaway exchanges
- `exchange.user_confirm: on_important` - Ask user for major decisions
- `exchange.history_mode: summarize` - Efficient token usage
- `review.enabled: true` - Review iteration enabled by default
- `review.max_iterations: 5` - More iterations allowed (goal is clear, diff is small)
- `review.user_confirm: never` - Auto-iterate without confirmation
- `claude_leads.sandbox: workspace-write` - Codex can modify project files (claude-leads)
- `claude_leads.consult_codex: true` - Plan consultation enabled
- `claude_leads.safety_checkpoint: stash` - Git stash before implementation
- `claude_leads.review.max_iterations: 3` - Claude review iterations

## Quality Gates

### Plan Quality Criteria

A valid plan from Codex must include:
- [ ] Clear list of files to modify
- [ ] Specific changes for each file
- [ ] Rationale for approach
- [ ] Identified risks or concerns
- [ ] Test coverage considerations

If plan is incomplete, request clarification from Codex.

### Review Acceptance Criteria

Accept review as "Pass" only when:
- [ ] All changed files reviewed
- [ ] No critical bugs identified
- [ ] Security concerns addressed
- [ ] Design aligns with original plan
- [ ] Test coverage adequate

## Running Codex

### MCP パターン（推奨）

MCP ツールが利用可能な場合、ステートフルな通信を使用:

```
# 新規セッション開始
mcp__codex__codex(prompt: "...", sandbox: "read-only")
→ Returns response + threadId

# 同一スレッドで継続
mcp__codex__codex-reply(threadId: "...", prompt: "...")
→ Returns response (conversation context preserved)
```

### codex exec パターン（フォールバック）

MCP が利用できない場合、`codex exec`（ステートレス実行）を使用:

```bash
# ヘルパー関数を使用（推奨）
source scripts/codex-helpers.sh
PROMPT_FILE=$(codex_write_prompt "$PROMPT_CONTENT" "plan")
OUTPUT_FILE="$(codex_tmp_path 'codex-output.md')"
codex_run_exec "$PROMPT_FILE" "$OUTPUT_FILE" "read-only"

# 直接実行（モデルは通常 Codex デフォルトを使用。指定する場合のみ -m を付ける）
codex exec -s read-only - < prompt.txt 2>&1 | tee output.md
```

### Codex CLI Options

- `-m, --model <model>` - Specify model (e.g., gpt-5.6-sol; omit to use the Codex default)
- `-s, --sandbox <mode>` - read-only | workspace-write | danger-full-access
- `-C, --cd <dir>` - Working directory
- `--full-auto` - Automatic execution mode
- `-` - Read prompt from stdin

### Important Notes

- **MCP mode**: Stateful sessions via threadId. Clean text output. No file I/O for prompts. Auto-detected in Step 0a.
- **Bash mode**: Each `codex exec` call is stateless (no conversation history between calls). Include all necessary context in each prompt.
- Use `-s read-only` for planning/review tasks (Codex won't modify files)
- Use `-s workspace-write` for implementation tasks (claude-leads workflow)
- Output may contain ANSI escape codes (Bash mode only); use `codex_strip_ansi()` or `codex_run_exec()` to clean
- **Stdin input** (Bash mode): Use redirect format (`codex exec - < file`) for reliable input
- **Timeout**: Bash tool has max 600s (10 minutes) timeout. MCP mode timeout is managed by MCP framework.
- **Background agents**: Background subagents (`run_in_background: true`) require pre-approved Bash permissions in `~/.claude/settings.json` or `.claude/settings.json`. Without pre-approval, Bash tool calls are auto-denied because permission prompts are unavailable in background mode.

## Error Handling

### CLI Unavailable

If `codex` command is not found:
1. Inform user: "Codex CLI is not installed or not in PATH"
2. Offer to proceed with Claude-only mode
3. Continue with standard Claude Code workflow

### Codex Timeout or Error

If `codex exec` returns non-zero exit code or times out:
1. Check error message in output file
2. Retry once with simplified prompt
3. If still failing, proceed manually and inform user

### Bash Tool Timeout

Bash tool has max 600s (10 minutes) timeout. For long-running tasks:
1. Set appropriate `codex.wait_timeout` setting
2. Consider breaking tasks into smaller parts
3. Use `run_in_background: true` for background execution

## Structured Communication Protocol

This plugin uses a minimal protocol header to enable structured communication between Claude Code and Codex CLI.

### Protocol Header

Every prompt to Codex includes a ~15-line protocol header:

```yaml
## Protocol (codex-collab/v1)
format: yaml
rules:
  - respond with exactly one top-level YAML mapping
  - include required fields: type, id, status, body
  - if unsure or blocked, use type=action_request with clarifying questions
types:
  task_card: {body: title, context, requirements, acceptance_criteria, proposed_steps, risks, test_considerations}
  result_report: {body: summary, changes, tests, risks, checks}
  action_request: {body: question, options, expected_response}
  review: {body: verdict, summary, findings, suggestions}
status: [ok, partial, blocked]
verdict: [pass, conditional, fail]
severity: [low, medium, high]
next_action: [continue, stop]
```

### Message Types

| Type | Purpose | Used By |
|------|---------|---------|
| `task_card` | Task definition with acceptance criteria | Codex (planning) |
| `result_report` | Execution results with check status | Claude (reporting) |
| `action_request` | Request for information or decision | Both |
| `review` | Review verdict and findings | Codex (review) |

### Parsing Strategy

- **Lenient**: Require only top-level envelope and core keys
- **Tolerant**: Accept extra fields and minor formatting differences
- **Fallback**: If YAML parsing fails, fall back to unstructured parsing

### Multi-turn Exchange

The protocol supports two independent iteration modes:

#### Planning Exchange (`exchange.*`)

Iterative discussion during planning phase:

**Flow Control:**
- `next_action: continue` - Request further exchange
- `next_action: stop` - Exchange complete
- `type: action_request` - Implies `next_action: continue`

**Settings:**
- `exchange.enabled: true` - Global kill-switch
- `exchange.max_iterations: 3` - Max rounds
- `exchange.user_confirm: on_important` - User confirmation timing
- `exchange.history_mode: summarize` - History management

**Termination Conditions:**
1. `next_action: stop` received
2. `exchange.max_iterations` reached
3. Repeated same question detected

#### Review Iteration (`review.*`)

Auto-iterate on review findings:

**Flow:**
1. Codex reviews → CONDITIONAL/FAIL
2. Claude fixes issues
3. Re-request review
4. Repeat until PASS or max reached

**Settings:**
- `review.enabled: true` - Enable auto-iteration
- `review.max_iterations: 5` - Higher than exchange (goal is clear, diff is small)
- `review.user_confirm: never` - Auto-iterate without confirmation

**Note:** `exchange.*` and `review.*` are completely independent (no inheritance).

## References

Detailed documentation in `references/`:

- **`protocol-cheatsheet.yaml`** - Minimal protocol header for prompts
- **`protocol-schema.yaml`** - Full protocol schema with examples
- **`planning-prompt.md`** - Template for requesting plans
- **`review-prompt.md`** - Template for requesting reviews
- **`codex-options.md`** - Codex CLI configuration options
- **`workflow-patterns.md`** - Alternative workflow patterns