AEcru/codex-capability-bridge

Use Codex Capabilities

Use the codex-capability-bridge MCP tools to route work into Codex. Do not guess that a discovered capability is executable: inspect its runtime status first.

Routing workflow

1. Call search_codex_capabilities with the user's wording and required output type.
2. If the top result is ambiguous or reports a runtime limitation, call describe_codex_capability.
3. Call run_codex_capability with:
   • the selected capability ID;
   • the complete user task;
   • the current working directory when files should be created there.
4. If Codex requests clarification or additional work, call continue_codex_task with the returned thread ID.
5. Report actual artifact paths returned by the bridge. Never claim that an image or file exists unless the bridge returned it or it is present on disk.

Selection rules

• Prefer exact capability-name matches such as imagegen, browser, documents, or spreadsheets.
• Prefer capabilities marked executable over metadata-only discoveries.
• Treat host-only capabilities as unavailable from Claude Code unless the bridge reports a tested backend.
• Do not install extra Codex plugins, authenticate accounts, elevate permissions, or change Codex configuration without explicit user approval.
• For file-producing work, use workspace-write; otherwise default to the least privilege that can complete the task.

Example requests

• “使用 codex 的 imagegen 插件生成一张猫咪的图片”
• “使用 codex 的插件生成一张猫咪的图片”
• “让 codex 自动选择合适的能力完成这个 Word 文档”

For the second example, search with both the task text and outputKind: image. Select imagegen only when the doctor/runtime status says it can be executed in the current environment.

Failure handling — self-repair loop

Bridge errors include recovery steps in their text. Read the error, execute the suggested verification, then retry. Follow this decision table before asking the user for help:

Error pattern	Recovery action
Unknown capability with Did you mean: <ids>	Retry with one of the suggested ids, preferring an executable match.
Unknown capability without suggestions	Call search_codex_capabilities with the task wording to obtain real ids, then describe_codex_capability to confirm before running.
Capability name is ambiguous	Use one of the full ids listed in the error.
discoverable but not executable	Call describe_codex_capability and check enabled/backend; if it comes from a disabled plugin cache, tell the user which plugin to enable in Codex, or pick an executable alternative from search results.
No runnable Codex CLI / missing required tool	Call codex_bridge_doctor, report the probe result, and relay the suggested environment fix (CODEX_CLI_PATH, update Codex) to the user.
Working directory is outside the allowed project roots	Retry with a cwd inside the current project; only suggest CODEX_BRIDGE_ALLOWED_ROOTS to the user for paths that must stay outside.
timed out	Retry once with a smaller or more specific task; if it still times out, tell the user the task needs CODEX_BRIDGE_TIMEOUT_MS raised.
continue_codex_task fails on an old threadId	Start a fresh run_codex_capability with the full task context instead.

Attempt at most two self-repair rounds per user request; after that, report what was tried and what is still missing. Never silently substitute an unrelated provider, and never present a catalog entry as a successful invocation.