Help us improve
Share bugs, ideas, or general feedback.
From codex-bridge
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.
npx claudepluginhub evgenygurin/codex-bridge --plugin codex-bridgeHow this skill is triggered — by the user, by Claude, or both
Slash command
/codex-bridge:codex-collabThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Claude Code and Codex CLI (via the `codex-bridge` MCP plugin) split work
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Designs test strategies and plans with testing pyramid. Covers APIs, frontend, data pipelines, infrastructure; outputs plans including coverage targets, examples, and gaps.
Share bugs, ideas, or general feedback.
Claude Code and Codex CLI (via the codex-bridge MCP plugin) split work
by role, not by file:
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.
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.
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.
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).
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.
Codex never edits code. Only documentation via
codex_update_docs. All code edits are performed by Claude Code via
Edit/Write.
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.
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.
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.Makefile,
package.json scripts, pyproject.toml, or a CLAUDE.md section if
unsure what to run.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.
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.
type(scope): summary ≤72
chars, body explains WHY not WHAT.git add . / git add -A.Skip codex-collab entirely and work directly if:
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.
codex-bridge tools: read the error
carefully. If it rejects a kwarg, you almost certainly passed task.
Remove it and retry.cwd-related failures (Codex cannot see files): verify the
absolute path points at the repo root, not a subdirectory.