⬡ CLAUDE × CODEX Workflow Hooks Benefits Cautions Progress Commands
claude-sonnet-4-6 codex-cli@latest
Navigation
[Tab] cycle panels
[Enter] expand node
[/] search
[q] quit
Pipeline Overview Plan → Review → Refine → Execute
C
① Claude Code — Plan claude
Receives task. Enters plan mode. Decomposes into specs, milestones, file structure, dependencies. Produces structured plan doc.
$ claude --plan "implement OAuth2 with refresh tokens"
X
② Codex — Review codex
Reads Claude's plan. Reviews for gaps, implementation risk, security issues, missing edge cases. Returns structured critique.
$ codex --review --input plan.md --output review.md
③ Iterative Dialogue both
Claude & Codex exchange structured JSON messages via hook bridge. PostToolUse hook triggers Codex critique; SubagentStop hook returns refined plan to Claude.
hook: PostToolUse → codex-bridge.sh → SubagentStop
④ Stakeholder Gate human
Plan surfaced to dev / stakeholder for approval. Interactive diff view. Annotate, reject, or approve. Locked plan saved to plan.approved.md.
→ Awaiting: /approve /reject /edit
⑤ /go — Launch execute
Claude reads approved plan and spawns sub-agents per task cluster. Each sub-agent gets isolated context, tools, and scope.
$ /go → spawning 3 sub-agents...
⑥ Sub-agents + Codex Delegation optional
Claude sub-agents handle task clusters. Independent tasks can be delegated to Codex CLI for true parallelism. User approves delegation.
[?] Delegate task-3 to Codex? [y/N]
⑦ /progress-report opt-in
Slash command queries all active sub-agents via SubagentStop hooks. Aggregates completion, blockers, estimated time. Renders TUI progress bar.
$ /progress-report → ████████░░ 78% [3/4 tasks]
Hook Configuration .claude/settings.json
// .claude/settings.json — team project hooks
{
  "hooks": {

    // Fire when Claude finishes generating a plan
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "bash .claude/hooks/codex-review.sh"
      }]
    }],

    // Codex review complete → inject back into Claude
    "SubagentStop": [{
      "hooks": [{
        "type": "agent",
        "prompt": "Read codex-review.md and refine plan.md. Output plan.refined.md",
        "timeout": 120
      }]
    }],

    // Block execution until plan is approved
    "Stop": [{
      "hooks": [{
        "type": "agent",
        "prompt": "Check if plan.approved.md exists. If not, return ok=false with reason='Awaiting stakeholder approval'.",
        "timeout": 60
      }]
    }],

    // Log all tool use for audit trail
    "PreToolUse": [{
      "hooks": [{
        "type": "http",
        "url": "http://localhost:9000/audit"
      }]
    }],

    // Inject session context at start
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "cat .claude/context/team-context.md"
      }]
    }]
  }
}
Codex Bridge Script .claude/hooks/codex-review.sh
#!/bin/bash
# Reads Claude's written plan, passes to Codex for review
INPUT=$(cat /dev/stdin)
PLAN_FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')

if [[ "$PLAN_FILE" == *"plan.md"* ]]; then
  codex "Review this plan for gaps, risks, missing edge cases. Be concise." \
    --input "$PLAN_FILE" \
    --output .claude/tmp/codex-review.md \
    --approval-mode auto-edit
  echo '{"continue": true, "reason": "Codex review complete"}'
else
  echo '{"continue": true}'
fi
15 Available Hook Events Claude Code
SessionStartInject team context into every session
SessionEndCommit checkpoint, notify team
PreToolUseBlock dangerous commands, audit log
PostToolUseTrigger Codex review after file write
StopBlock until approval gate is met
SubagentStopAggregate sub-agent results for /progress-report
SubagentStartLog sub-agent spawn for tracking
UserPromptSubmitDetect /go, /progress-report slash commands
TaskCompletedUpdate progress tracker, ping stakeholder
NotificationDesktop / Slack alerts on important events
Why This Pipeline Works
Claude Strength
Long-horizon planning, deep codebase reasoning, multi-file coordination
Codex Strength
Repo-scale review, sandboxed execution, parallel async task delegation
Hook System
15 lifecycle events, deterministic control, not just "suggestions"
Sub-agents
Isolated contexts, parallel execution, scope-limited tool access
Claude Code Benefits planner
Best-in-class planning — Decomposes complex tasks into specs with dependencies, milestones, and file-level detail.Excels at multi-file coordinated changes and reasoning about entire codebases
Hooks are deterministic — Unlike prompt rules in CLAUDE.md, hooks always fire. Plan gates are enforced, not suggested.PreToolUse / Stop hooks cannot be bypassed by the model
Sub-agent orchestration — Native support for spawning isolated sub-agents with their own context windows and tool scopes.
Terminal-native — Lives in your workflow. No context switching. Deep file system and git integration.
SessionStart stdout = context — Your hook's stdout becomes Claude's starting context. Team-wide context injection built-in.
Codex Benefits reviewer + parallel worker
Sandboxed execution — macOS Seatbelt / Linux Landlock OS-level isolation. Safe to run autonomously.Network blocked by default; explicit opt-in required
Async cloud tasks — Delegate long-running tasks to cloud sandboxes. Your terminal stays responsive.
AGENTS.md + MCP — Codex is configurable via AGENTS.md and extensible via MCP servers, same protocol as Claude.
Runs as MCP server — Codex CLI can act as an MCP server, letting Claude orchestrate it natively via tool calls.
GPT-5.2-Codex — Current default model. Optimized for repo-scale reasoning, refactors, and iterative test-driven execution.
Together — Emergent Benefits
Plan-Review loop — Claude plans optimistically, Codex reviews defensively. Tension produces better output than either alone.
True parallelism — Claude handles context-heavy tasks locally; Codex handles independent tasks in cloud sandboxes simultaneously.
Human stays in control — The gate hook means nothing executes without explicit /approve. Autonmous but accountable.
⚠ Known Risks & Mitigations
Context window loss between agents — Agents share no memory. Decisions made in Claude's plan may not be visible to Codex reviewer without explicit file passing.Mitigation: Always write plan to plan.md before triggering Codex hook. Pass file path, not inline text.
Conflicting suggestions — Claude and Codex may suggest contradictory implementations. No automatic resolution.Mitigation: Define a priority rule in CLAUDE.md: "Claude's plan is source of truth; Codex review is advisory only."
Token cost escalation — Dialogue loops (Phase 3) can run many turns. Each review pass costs tokens from both APIs.Mitigation: Set max_turns on agent hooks (default 50). Add early-exit condition if plan passes quality threshold.
Rate limiting — Concurrent sub-agents + Codex reviews may hit API rate limits under heavy load.Mitigation: Add jitter/backoff in codex-bridge.sh. Stagger hook-triggered Codex calls with a short sleep.
Data transmission to external services — Both tools send code to Anthropic and OpenAI respectively. Your IP and code leave your machine.Mitigation: Review both data handling policies. Do not use with code under NDA without legal sign-off.
Security vulnerabilities in agentic flows — Late-Feb 2026 reports flagged RCE risk scenarios in Claude Code agentic workflows on developer machines. Fixes were issued but the attack surface is real.Mitigation: Always run claude --dangerously-skip-permissions only in CI sandboxes. Use PreToolUse hooks to block rm, curl | bash, etc.
Sub-agent scope creep — Sub-agents with broad tool access can modify files outside their assigned scope.Mitigation: Restrict sub-agent system prompts: "You may only modify files under src/auth/. Do not touch other directories."
Security Checklist
PreToolUse hook blocks rm -rf, curl | bash, sudo
Codex sandbox has network disabled by default
plan.approved.md checked before any execution
HTTP audit hook logs all tool events to local service
.env files excluded from all agent file access via PreToolUse
Sub-agents given minimum required file scope in system prompt
Team Progress Tracker /progress-report
Integration Pipeline — Sprint 1 0%
How /progress-report Works UltraThink
SubagentStop hook — Every sub-agent writes a status JSON to .claude/tmp/progress/{agent-id}.json on stop. Contains: completed_tasks, blocked, est_remaining_ms.
UserPromptSubmit hook — Detects /progress-report. Intercepts before reaching the model. Runs progress-agg.sh which reads all JSON files and renders TUI output.
TaskCompleted hook — Fires when an agent marks a task done. Increments counter. Optionally sends Slack notification via HTTP hook.
No polling — Event-driven, not interval-based. Zero overhead when agents are idle. Instant update on completion.
Git checkpoint per task — SessionEnd hook auto-commits with agent's prompt as commit message. Full rollback history at each stage.
Slash Commands Claude Code
/plan <task>Enter planning mode. Claude decomposes task and writes plan.md
/reviewManually trigger Codex review hook on current plan
/approveWrite plan.approved.md, unblock the Stop hook, enable /go
/reject <reason>Append rejection reason to plan.md, restart dialogue loop
/goRead approved plan, spawn sub-agents per task cluster
/delegate <task-id>Prompt to delegate specific task to Codex CLI [y/N]
/progress-reportAggregate all sub-agent status files, render TUI progress bar
/agentsList active sub-agents, their scope, and current status
/auditShow all PreToolUse log entries for current session
Codex CLI Flags @openai/codex
--reviewReview mode: read input file, produce structured critique
--approval-mode auto-editAuto-apply safe edits, prompt on destructive ops
--input / --outputFile-based I/O for hook bridge integration
--sandboxForce sandbox (macOS Seatbelt / Linux Landlock)
mcp startRun Codex as an MCP server for Claude to call as a tool
--full-autoNo prompts — use only in CI with pre-approved scripts
Quick Start team setup
# 1. Install both tools
npm i -g @openai/codex
# Claude Code: install from anthropic.com/claude-code

# 2. Start Codex as MCP server (lets Claude call it as a tool)
codex mcp start &
claude mcp add codex -- npx @openai/codex mcp start

# 3. Place hook config in your project
cp .claude/settings.json.template .claude/settings.json

# 4. Start a session — hooks auto-load
claude

# 5. Begin the pipeline
/plan "add payment module with Stripe webhooks"
Tab switch panel Enter expand node Esc close modal Click any node for detail Progress tab click stages to toggle
Claude Code × Codex v1.0 — team workflow