codex-bridge

Start a codex-bridge collaboration flow — research → implement → verify on a feature

Delegate a documentation update to Codex CLI (writable)

Delegate a deep-research question to Codex CLI (read-only)

Run a task via Codex CLI

Delegates research, investigation, analysis, and documentation tasks to Codex CLI. Use when the user asks to research code, investigate patterns, analyze dependencies, trace call chains, find all uses of something, update docs, or document the API — any task scanning many files or requiring deep codebase understanding. Since codex-bridge v0.2.0 all tools stream Codex output live (agent messages, reasoning, tool calls) via MCP log notifications, so long-running research no longer blocks the orchestrator in silence. <example> Context: User wants a cross-file pattern analysis. user: "How is error handling implemented across the codebase?" assistant: "I'll delegate this to the codex-researcher subagent — it needs to scan many files, so a Codex call will save my context window and stream progress back as it goes." <commentary> Scanning many files for a pattern is exactly what codex_research is for. The streaming pipeline means the assistant can see Codex's reasoning and intermediate findings live instead of waiting in silence for the full turn to complete. </commentary> </example> <example> Context: User requests a doc update that depends on understanding nearby code. user: "Update the README with current API endpoints." assistant: "I'll use the codex-researcher subagent to call codex_update_docs on README.md — Codex gets write access and can read surrounding files for context." <commentary> Documentation updates that require reading the code they describe are a good fit for codex_update_docs, because Codex sees the whole repo and can cross-reference while editing. </commentary> </example> <example> Context: Dependency trace across many modules. user: "Find all files that import the auth module and explain the dependency chain." assistant: "I'll delegate to the codex-researcher subagent to run a codex_research call — this is a classic whole-repo trace." <commentary> Dependency analysis is a perfect fit for Codex: one deep call is cheaper than dozens of inline Grep+Read cycles and keeps the orchestrator's context clean. </commentary> </example> <example> Context: Multi-turn investigation where the follow-up question builds on the previous answer. user: "First tell me how auth works, then show me every file that would need to change if we switched to OAuth2." assistant: "I'll use codex-researcher to run two codex_research calls — the first answers the 'how', then I'll pass its session_id to the second call so Codex keeps the context and trivially answers the follow-up." <commentary> Multi-turn Codex sessions via session_id are much cheaper than re-loading context from scratch — the second call benefits from the first turn's cached input tokens. </commentary> </example> <example> Context: User wants several large investigations to run at once. user: "Figure out the error-handling story, the logging story, and the telemetry story — all of them." assistant: "I'll delegate to codex-researcher and run three codex_research calls in parallel as FastMCP background tasks, then collect the results." <commentary> Background-task mode (`task=True` on the client) lets the orchestrator fire off N independent Codex calls concurrently instead of sequentially. Use this whenever the investigations don't depend on each other. </commentary> </example>

Use when collaborating with Codex CLI (via codex-bridge) on a non-trivial feature, refactor, or investigation — typically triggered by /codex-collab, "работай с codex", "делегируй исследование codex", "codex + ты над X", or any phrasing that requests shared work between Claude Code and Codex. Enforces a research → plan → implement → verify → fix/docs → commit workflow with session_id continuity so Codex serves as analyst/reviewer while Claude Code remains the sole code editor. Delegates multi-file exploration to Codex to keep Claude Code's context window narrow.