codex-collab

Codex Collaboration Workflow

Claude Code and Codex CLI (via the codex-bridge MCP plugin) split work by role, not by file:

• Claude Code — planner + implementer. Reads key files, writes code, runs tests, commits.
• Codex — analyst + reviewer. Read-only via codex_research with access to its own MCP toolbox (in-memoria, context7, exa) and the repo sandbox. Cannot edit code. Can edit documentation only via codex_update_docs.

The goal: keep Claude Code's context window narrow by delegating deep multi-file exploration to Codex, while Claude Code focuses on the 3-5 files that actually need changes.

Critical rules

1. Never pass task as a tool argument to codex_run, codex_research, or codex_update_docs. task=True is a server-side FastMCP decorator flag, NOT a client parameter. Pydantic will reject it with unexpected_keyword_argument. Background execution from tool-using clients (like Claude Code) requires a separate FastMCP subscribe API and is not available via normal tool calls — foreground mode still streams internally and returns the aggregated final result, which is what you want.

2. Always pass an absolute cwd pointing at the repo root. Without it, Codex operates from the MCP server's own cwd and cannot read project files. Detect the cwd from the current working directory at the start of the task — do not hardcode paths across projects.

3. Reuse session_id across all Codex calls within a single task. Capture it from the first response and pass it to every subsequent codex_research / codex_run / codex_update_docs call. This preserves Codex's context and reuses cached prompt tokens (~50% cache hits from turn 2 onwards).

4. Do not pre-read the whole codebase before delegating research. That defeats the purpose. The Grep/Read budget starts only after Phase 1 returns a concrete file list.

5. Codex never edits code. Only documentation via codex_update_docs. All code edits are performed by Claude Code via Edit/Write.

6. Checkpoint after each phase. Send a short summary (5-10 lines) to the user and wait for confirmation before moving to the next phase. Never chain all phases in one monologue.

Phases

Phase 1 — Research (delegate to Codex)

One codex_research call. Ask for a structured map of the area, not a solution.

mcp__plugin_codex-bridge_codex-bridge__codex_research
  cwd:      "<absolute path to repo root>"
  question: |
    Investigate <area> for the task: <one-line task description>.
    Return:
      1. File map with roles (component / hook / service / repo / test
         / config / style)
      2. Data flow: where data enters, transforms, exits
      3. State management (where state lives, how it is persisted,
         how it is restored)
      4. Existing conventions and patterns in this area
      5. Relevant documentation files and whether they match current
         code
      6. For the task above — a split into:
         - MUST-EDIT files (touch to implement)
         - CONTEXT files (read for understanding, do not edit)
         - OUT-OF-SCOPE files (ignore)

    Format: structured, with file:line anchors. No generalities.

Capture the returned session_id and keep it for the remainder of the task. Summarize the map to the user in ~10 lines and stop.

Phase 2 — Plan

• Read ONLY the MUST-EDIT files plus 1-2 CONTEXT files flagged as critical by Phase 1. Resist reading more.
• Produce a 3-7 step plan in prose. Identify risks (hydration, SSR/client boundaries, migration ordering, test gaps, race conditions) surfaced by Phase 1.
• Present the plan to the user. Wait for explicit confirmation before any edit. If the user adjusts — revise and re-present.

Phase 3 — Implement

• Edit files via Edit/Write. Keep the diff focused on the task; never batch unrelated changes.
• If you hit an unknown piece of code mid-implementation, do a targeted codex_research call with the same session_id: "briefly: what does X at file:line do and does it affect my current change?". Do not start a new session.
• Run language-specific verification after each logical chunk: use the project's own lint / typecheck / test commands. Check Makefile, package.json scripts, pyproject.toml, or a CLAUDE.md section if unsure what to run.
• Fix all errors before proceeding. Never hand a broken state to Phase 4.

Phase 4 — Verify (delegate to Codex, same session_id)

One codex_research call:

mcp__plugin_codex-bridge_codex-bridge__codex_research
  cwd:        "<absolute path to repo root>"
  session_id: "<id from Phase 1>"
  question: |
    I just implemented <task> with changes in <list of files with a
    one-line summary of what changed in each>. Cross-check against the
    map you produced earlier:
      1. Consistency with existing patterns you described in Phase 1
      2. Regressions — anything I might have broken in adjacent code
      3. Convention violations (check project conventions in CLAUDE.md,
         .claude/rules/, or equivalent)
      4. Framework-specific risks relevant to this area (hydration,
         async boundaries, migration safety, test coverage gaps)
      5. Whether documentation files need updating

    Report findings as a list with severity:
      - BLOCKER (must fix before commit)
      - SHOULD-FIX (strong recommendation, explain why)
      - NIT (style/polish, optional)
    If clean, say "LGTM".

Relay findings to the user in compressed form. On BLOCKER → Phase 5. On LGTM or only NITs → Phase 6.

Phase 5 — Fix & docs (if needed)

• Fix BLOCKER and SHOULD-FIX items. Re-run verification commands.
• If Phase 4 found docs out of sync, delegate the doc update:

mcp__plugin_codex-bridge_codex-bridge__codex_update_docs
  cwd:         "<absolute path to repo root>"
  session_id:  "<same session>"
  instruction: |
    Update <doc path> to reflect the current state of <files>.
    Preserve existing structure; update only sections affected by this
    change. Do not rewrite unchanged paragraphs.

codex_update_docs runs in writable mode — Codex edits the markdown directly. Claude Code does not need to read the doc file manually.

Phase 6 — Commit

• Follow the project's commit conventions. If no specific rules are documented, use Conventional Commits: type(scope): summary ≤72 chars, body explains WHY not WHAT.
• Stage specific files by name, never git add . / git add -A.
• Ask the user before pushing or opening a PR — shipping is the user's decision.

When NOT to use this workflow

Skip codex-collab entirely and work directly if:

• The task touches 1-2 files and you already know where.
• The fix is a one-liner or a typo.
• The user asks a question (not a task) answerable by reading one file.
• The user is debugging a specific error and has already localized it.

In those cases, direct Grep/Read/Edit is faster and more transparent. codex-collab pays off when the area is unfamiliar OR the change spans more files than you want to hold in context simultaneously.

Output discipline during collab

• Per-phase summary ≤10 lines. Quote only key findings from Codex, not the full transcript.
• Name the current phase in every summary so the user can track progress ("Phase 3 done — Phase 4 starts now").
• On Pydantic errors from codex-bridge tools: read the error carefully. If it rejects a kwarg, you almost certainly passed task. Remove it and retry.
• On cwd-related failures (Codex cannot see files): verify the absolute path points at the repo root, not a subdirectory.