@alex_moroz/claude-codex-router
v0.3.1
Published
Local macOS control panel for bidirectional Claude Code and Codex task routing.
Downloads
103
Readme
Claudex — Claude × Codex Router
Claudex is a local macOS control panel for routing coding tasks in both directions:
- Claude → Codex: Claude delegates qualifying review or implementation work to Codex through the official Claude plugin.
- Codex → Claude: Codex delegates a read-only review or isolated implementation to Claude through a local MCP server.
Both services use their existing subscription login. Claudex does not require API keys or API billing.
Quick setup
Requirements: macOS, Node.js 18+, Claude Code access, and a ChatGPT/Codex subscription.
Install and open the local control panel:
npm i -g @alex_moroz/claude-codex-router
claude-codex-router installThen open 00 · Connections & setup and complete only the direction(s) you want to use. The two setup flows are independent:
- Connect Claude Code and Codex CLI using their normal SSO/OAuth flows.
- Install the official Claude → Codex bridge plugin.
- Apply the routing policy.
- Run the Claude → Codex self-check.
- In Codex → Claude bridge, register the displayed local MCP server and install Codex routing instructions.
- Run the Codex → Claude self-check. Optionally run its live handshake; it performs one short Claude review and uses tokens.
Each direction reports readiness independently. A Claude-only user does not need the Codex → Claude setup, and vice versa.
Updating an existing installation
After updating the npm package, open 00 · Connections & setup → Codex → Claude. If Codex still points at an older package path, Claudex shows Update required. Select Update / repair Codex → Claude to replace only the router MCP registration, refresh the marked router block in global Codex guidance, and run a token-free self-check. Your other MCP entries and guidance remain unchanged; guidance is backed up first.
Start a new Codex task after an update so it reads the refreshed global AGENTS.md instructions. The optional live handshake remains opt-in because it uses Claude tokens.
Configure routing
- 01 · Claude → Codex: choose when Claude should ask Codex to review or implement.
- 02 · Codex → Claude: choose Claude involvement, reviewer/implementer model, and effort when Codex owns the task.
For Codex → Claude, Claude reviews are read-only. Implementations are made in an isolated router/<task-id> git worktree; Codex keeps ownership and accepts or rejects the result.
When you apply the policy, Claudex also installs the generated Codex → Claude instructions into the global Codex guidance file: ~/.codex/AGENTS.md, or ~/.codex/AGENTS.override.md when that is the active global file. It updates only its marked block, preserves your other instructions, and backs up the prior file under ~/.claude-codex-router/backups/codex-guidance/. Start a new Codex task after applying changes so Codex rebuilds its instruction chain.
Use 03 · Tasks & activity to see every router-managed root, review, implementation, post-review, and validation record, and 04 · Usage limits for local account usage snapshots.
Daily use
Keep using Claude or Codex normally. The applied policy and MCP tools handle the selected delegations.
claude-codex-router open # open the local UI
claude-codex-router doctor # inspect local setup status
claude-codex-router stop # stop the local UI serverThe UI runs locally at http://127.0.0.1:4177. It stores router state and task metadata under ~/.claude-codex-router/; it does not send logs to a separate service.
