claude-codex-bridge 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# claude-codex-bridge
+
+[![npm version](https://img.shields.io/npm/v/claude-codex-bridge?color=f97316)](https://www.npmjs.com/package/claude-codex-bridge)
+[![npm downloads](https://img.shields.io/npm/dm/claude-codex-bridge?color=3b82f6)](https://www.npmjs.com/package/claude-codex-bridge)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+Bidirectional [MCP](https://modelcontextprotocol.io/) server bridge between **Claude Code** and **OpenAI Codex CLI**.
+
+Let Claude and Codex work as partners — each can ask the other for help, review code, explain logic, and plan performance improvements.
+
+```
+┌──────────────┐         MCP          ┌──────────────┐
+│              │ ◄──────────────────► │              │
+│  Claude Code │    claude-codex      │  Codex CLI   │
+│              │ ◄───── bridge ─────► │              │
+└──────────────┘                      └──────────────┘
+```
+
+## Prerequisites
+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) — installed and authenticated
+- [Codex CLI](https://developers.openai.com/codex/cli/) — installed and authenticated
+- [Node.js](https://nodejs.org) >= 18
+
+## Quick Start
+
+No install needed — use directly via `npx`:
+
+```bash
+npx -p claude-codex-bridge ccb-codex   # Start the Codex server
+npx -p claude-codex-bridge ccb-claude  # Start the Claude server
+```
+
+## Setup
+
+### Automatic (recommended)
+
+Run `/setup` inside Claude Code to automatically configure both directions:
+
+```
+/setup          # Set up both Claude Code and Codex
+/setup claude   # Only set up Claude Code → Codex
+/setup codex    # Only set up Codex → Claude
+```
+
+Or, if you don't have the repo cloned, just ask Claude Code:
+
+> Please help me set up claude-codex-bridge MCP for both Claude Code and Codex according to https://github.com/Dunqing/claude-codex-bridge/blob/main/.claude/skills/setup/SKILL.md
+
+### Manual
+
+<details>
+<summary><strong>Claude Code → Codex</strong> (let Claude call Codex)</summary>
+
+Add to your Claude Code MCP config:
+
+```bash
+claude mcp add codex -- npx -p claude-codex-bridge ccb-codex
+```
+
+Or add to `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "codex": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-p", "claude-codex-bridge", "ccb-codex"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Codex → Claude</strong> (let Codex call Claude)</summary>
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.claude]
+command = "npx"
+args = ["-p", "claude-codex-bridge", "ccb-claude"]
+tool_timeout_sec = 300
+```
+
+</details>
+
+## Tools
+
+### `ccb-codex` — Claude calls Codex
+
+| Tool | Description |
+|------|-------------|
+| `codex_query` | Ask Codex a question or give it a task |
+| `codex_review_code` | Ask Codex to review code changes |
+| `codex_review_plan` | Ask Codex to critique an implementation plan |
+| `codex_explain_code` | Ask Codex to explain code / logic / architecture |
+| `codex_plan_perf` | Ask Codex to plan performance improvements |
+| `codex_implement` | Ask Codex to write or modify code |
+
+### `ccb-claude` — Codex calls Claude
+
+| Tool | Description |
+|------|-------------|
+| `claude_query` | Ask Claude a question or give it a task |
+| `claude_review_code` | Ask Claude to review code changes |
+| `claude_review_plan` | Ask Claude to critique an implementation plan |
+| `claude_explain_code` | Ask Claude to explain code / logic / architecture |
+| `claude_plan_perf` | Ask Claude to plan performance improvements |
+| `claude_implement` | Ask Claude to write or modify code |
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BRIDGE_TIMEOUT_MS` | Subprocess timeout in milliseconds | `300000` (5 min) |
+| `BRIDGE_DEBUG` | Enable debug logging to stderr | — |
+| `BRIDGE_DEPTH` | Current recursion depth (set automatically) | `0` |
+
+### Anti-Recursion Guard
+
+The bridge automatically prevents infinite loops. If Claude calls Codex which tries to call Claude again, the second call is blocked (`BRIDGE_DEPTH >= 2`).
+
+## Development
+
+```bash
+git clone https://github.com/Dunqing/claude-codex-bridge.git
+cd claude-codex-bridge
+pnpm install
+
+pnpm build         # Compile to dist/
+pnpm test          # Run tests
+pnpm lint          # Lint and type check
+
+# Dev mode (no build needed)
+pnpm dev:codex-server
+pnpm dev:claude-server
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/claude-server.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/claude-server.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { i as logger, n as buildPlanPerfPrompt, r as execCommand, t as buildExplainCodePrompt } from "./prompt-builder-CQ2IGDTq.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+//#region src/lib/claude-output-parser.ts
+/**
+* Parses the JSON output from `claude -p --output-format json`.
+* The output is a single JSON object with a `result` field containing
+* the response content.
+*/
+function parseClaudeOutput(jsonOutput) {
+	const result = {
+		resultText: "",
+		sessionId: null,
+		costUsd: null,
+		errors: []
+	};
+	const trimmed = jsonOutput.trim();
+	if (!trimmed) {
+		result.errors.push("Empty output from Claude CLI");
+		return result;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		logger.debug("Failed to parse Claude output as JSON, using raw text");
+		result.resultText = trimmed;
+		return result;
+	}
+	const resultField = parsed["result"];
+	if (typeof resultField === "string") result.resultText = resultField;
+	else if (resultField && typeof resultField === "object") {
+		const content = resultField["content"];
+		if (Array.isArray(content)) result.resultText = content.filter((c) => c["type"] === "text").map((c) => c["text"]).join("\n");
+	}
+	if (!result.resultText) {
+		const message = parsed["message"];
+		const text = parsed["text"];
+		const output = parsed["output"];
+		result.resultText = message ?? text ?? output ?? "";
+	}
+	if (!result.resultText && Object.keys(parsed).length > 0) result.resultText = JSON.stringify(parsed, null, 2);
+	result.sessionId = parsed["session_id"] ?? parsed["sessionId"] ?? null;
+	result.costUsd = parsed["cost_usd"] ?? parsed["costUsd"] ?? null;
+	const error = parsed["error"];
+	if (error) {
+		const msg = typeof error === "string" ? error : error["message"] ?? JSON.stringify(error);
+		result.errors.push(msg);
+	}
+	return result;
+}
+
+//#endregion
+//#region src/claude-server.ts
+const server = new McpServer({
+	name: "claude-bridge",
+	version: "0.1.0"
+});
+async function runClaude(prompt, options = {}) {
+	const args = [
+		"-p",
+		"--output-format",
+		"json"
+	];
+	if (options.model) args.push("--model", options.model);
+	if (options.maxTurns) args.push("--max-turns", String(options.maxTurns));
+	if (options.allowedTools && options.allowedTools.length > 0) for (const tool of options.allowedTools) args.push("--allowedTools", tool);
+	args.push(prompt);
+	const result = await execCommand({
+		command: "claude",
+		args,
+		cwd: options.workingDirectory
+	});
+	if (result.timedOut) return {
+		resultText: "",
+		sessionId: null,
+		costUsd: null,
+		errors: ["Claude timed out. Increase BRIDGE_TIMEOUT_MS if needed."]
+	};
+	const parsed = parseClaudeOutput(result.stdout);
+	if (result.exitCode !== 0 && !parsed.resultText) {
+		const stderr = result.stderr.toLowerCase();
+		if (stderr.includes("api key") || stderr.includes("authentication") || stderr.includes("unauthorized")) parsed.errors.push("Claude API key issue. Ensure ANTHROPIC_API_KEY is set.");
+		else if (result.stderr.trim()) parsed.errors.push(result.stderr.trim());
+	}
+	return parsed;
+}
+function formatClaudeResponse(parsed) {
+	if (parsed.errors.length > 0 && !parsed.resultText) return {
+		content: [{
+			type: "text",
+			text: `Error: ${parsed.errors.join("; ")}`
+		}],
+		isError: true
+	};
+	return { content: [{
+		type: "text",
+		text: parsed.resultText
+	}] };
+}
+const READ_ONLY_TOOLS = [
+	"Read",
+	"Grep",
+	"Glob",
+	"Bash(git diff *)",
+	"Bash(git log *)",
+	"Bash(git show *)"
+];
+server.registerTool("claude_query", {
+	title: "Ask Claude",
+	description: "Ask Claude Code a question or give it a task. Claude will use its full toolset (file reading, code search, web search, etc.) to answer.",
+	inputSchema: {
+		prompt: z.string().describe("The question or task for Claude"),
+		workingDirectory: z.string().optional().describe("Working directory (defaults to server cwd)"),
+		model: z.string().optional().describe("Model alias: sonnet, opus, or haiku"),
+		maxTurns: z.number().optional().default(10).describe("Maximum agentic turns (limits runtime)"),
+		allowedTools: z.array(z.string()).optional().describe("Restrict tools (e.g., [\"Read\", \"Grep\", \"Glob\"])")
+	}
+}, async ({ prompt, workingDirectory, model, maxTurns, allowedTools }) => {
+	return formatClaudeResponse(await runClaude(prompt, {
+		workingDirectory,
+		model,
+		maxTurns,
+		allowedTools
+	}));
+});
+server.registerTool("claude_review_code", {
+	title: "Claude Code Review",
+	description: "Ask Claude to review code for quality, bugs, security issues, and best practices. Provide a git diff range, file paths, or code snippet.",
+	inputSchema: {
+		target: z.string().describe("What to review: git diff range, file paths, or code snippet"),
+		focusAreas: z.string().optional().describe("Focus on: bugs, performance, style, security, etc."),
+		context: z.string().optional().describe("Additional context about the changes"),
+		workingDirectory: z.string().optional(),
+		maxTurns: z.number().optional().default(5)
+	}
+}, async ({ target, focusAreas, context, workingDirectory, maxTurns }) => {
+	let prompt = `Review the following code changes. Provide specific, actionable feedback with line references.\n\nTarget: ${target}`;
+	if (focusAreas) prompt += `\n\nFocus areas: ${focusAreas}`;
+	if (context) prompt += `\n\nContext: ${context}`;
+	return formatClaudeResponse(await runClaude(prompt, {
+		workingDirectory,
+		maxTurns,
+		allowedTools: READ_ONLY_TOOLS
+	}));
+});
+server.registerTool("claude_review_plan", {
+	title: "Claude Plan Review",
+	description: "Ask Claude to critique an implementation plan. Claude will examine the actual codebase to validate feasibility and consistency with existing patterns.",
+	inputSchema: {
+		plan: z.string().describe("The implementation plan to review"),
+		codebasePath: z.string().optional().describe("Path to relevant codebase for context"),
+		constraints: z.string().optional().describe("Known constraints"),
+		workingDirectory: z.string().optional(),
+		maxTurns: z.number().optional().default(8)
+	}
+}, async ({ plan, codebasePath, constraints, workingDirectory, maxTurns }) => {
+	let prompt = `Critique this implementation plan. Evaluate feasibility against the actual codebase, check consistency with existing patterns, identify gaps and risks.\n\nPlan:\n${plan}`;
+	if (codebasePath) prompt += `\n\nRelevant codebase: ${codebasePath}`;
+	if (constraints) prompt += `\n\nConstraints: ${constraints}`;
+	return formatClaudeResponse(await runClaude(prompt, {
+		workingDirectory,
+		maxTurns,
+		allowedTools: READ_ONLY_TOOLS
+	}));
+});
+server.registerTool("claude_explain_code", {
+	title: "Claude Explain Code",
+	description: "Ask Claude to deeply explain code, logic, or architecture. Claude will read the actual source files to give grounded explanations.",
+	inputSchema: {
+		target: z.string().describe("What to explain: file path, function name, module, or code snippet"),
+		depth: z.enum([
+			"overview",
+			"detailed",
+			"trace"
+		]).optional().default("detailed").describe("Depth: overview, detailed, or full execution trace"),
+		context: z.string().optional().describe("Additional context about the codebase"),
+		workingDirectory: z.string().optional(),
+		maxTurns: z.number().optional().default(8)
+	}
+}, async ({ target, depth, context, workingDirectory, maxTurns }) => {
+	return formatClaudeResponse(await runClaude(buildExplainCodePrompt({
+		target,
+		depth,
+		context
+	}), {
+		workingDirectory,
+		maxTurns,
+		allowedTools: READ_ONLY_TOOLS
+	}));
+});
+server.registerTool("claude_plan_perf", {
+	title: "Claude Performance Plan",
+	description: "Ask Claude to analyze performance and create an improvement plan. Claude reads the actual code to identify bottlenecks and propose optimizations.",
+	inputSchema: {
+		target: z.string().describe("What to optimize: function, module, or pipeline path"),
+		metrics: z.array(z.enum([
+			"latency",
+			"throughput",
+			"memory",
+			"binary-size"
+		])).optional().describe("Performance metrics to focus on"),
+		constraints: z.string().optional().describe("Constraints"),
+		context: z.string().optional().describe("Additional context about usage patterns"),
+		workingDirectory: z.string().optional(),
+		maxTurns: z.number().optional().default(10)
+	}
+}, async ({ target, metrics, constraints, context, workingDirectory, maxTurns }) => {
+	return formatClaudeResponse(await runClaude(buildPlanPerfPrompt({
+		target,
+		metrics,
+		constraints,
+		context
+	}), {
+		workingDirectory,
+		maxTurns,
+		allowedTools: READ_ONLY_TOOLS
+	}));
+});
+server.registerTool("claude_implement", {
+	title: "Claude Implement",
+	description: "Ask Claude to implement a feature, fix a bug, or make code changes. WARNING: This modifies your codebase.",
+	inputSchema: {
+		task: z.string().describe("What to implement or fix"),
+		workingDirectory: z.string().optional(),
+		model: z.string().optional(),
+		maxTurns: z.number().optional().default(15)
+	}
+}, async ({ task, workingDirectory, model, maxTurns }) => {
+	return formatClaudeResponse(await runClaude(task, {
+		workingDirectory,
+		model,
+		maxTurns
+	}));
+});
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	logger.info("claude-bridge MCP server started on stdio");
+}
+main().catch((err) => {
+	logger.error("Failed to start claude-bridge:", err);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/dist/codex-server.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/codex-server.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { i as logger, n as buildPlanPerfPrompt, r as execCommand, t as buildExplainCodePrompt } from "./prompt-builder-CQ2IGDTq.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+//#region src/lib/codex-output-parser.ts
+/**
+* Parses the JSONL output from `codex exec --json`.
+* Each line is a JSON event with a `type` field.
+* We extract the final agent message, file changes, commands, and usage.
+*/
+function parseCodexOutput(jsonlOutput) {
+	const result = {
+		threadId: null,
+		agentMessage: "",
+		fileChanges: [],
+		commandsExecuted: [],
+		usage: null,
+		errors: []
+	};
+	const lines = jsonlOutput.split("\n").filter((l) => l.trim().length > 0);
+	for (const line of lines) {
+		let event;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			logger.debug(`Skipping non-JSON line: ${line.slice(0, 100)}`);
+			continue;
+		}
+		const type = event["type"];
+		if (!type) continue;
+		switch (type) {
+			case "thread.started":
+				result.threadId = event["threadId"] ?? null;
+				break;
+			case "item.completed": {
+				const itemType = event["itemType"];
+				if (itemType === "agent_message" || itemType === "message") {
+					const text = event["text"] ?? event["content"] ?? "";
+					if (text) result.agentMessage = text;
+				} else if (itemType === "file_change") {
+					const path = event["path"] ?? "";
+					const kind = event["kind"] ?? "update";
+					if (path) result.fileChanges.push({
+						path,
+						kind
+					});
+				} else if (itemType === "command_execution") result.commandsExecuted.push({
+					command: event["command"] ?? "",
+					exitCode: event["exitCode"] ?? null,
+					output: event["output"] ?? ""
+				});
+				break;
+			}
+			case "turn.completed": {
+				const usage = event["usage"];
+				if (usage) result.usage = {
+					inputTokens: usage["input_tokens"] ?? usage["inputTokens"] ?? 0,
+					outputTokens: usage["output_tokens"] ?? usage["outputTokens"] ?? 0
+				};
+				break;
+			}
+			case "turn.failed":
+			case "error": {
+				const msg = event["error"] ?? event["message"] ?? JSON.stringify(event);
+				result.errors.push(msg);
+				break;
+			}
+		}
+	}
+	if (!result.agentMessage && jsonlOutput.trim()) result.agentMessage = jsonlOutput.trim();
+	return result;
+}
+
+//#endregion
+//#region src/codex-server.ts
+const server = new McpServer({
+	name: "codex-bridge",
+	version: "0.1.0"
+});
+async function runCodex(prompt, options = {}) {
+	const args = ["exec", "--json"];
+	if (options.model) args.push("--model", options.model);
+	if (options.sandbox) args.push("--sandbox", options.sandbox);
+	if (options.fullAuto) args.push("--full-auto");
+	args.push(prompt);
+	const result = await execCommand({
+		command: "codex",
+		args,
+		cwd: options.workingDirectory
+	});
+	if (result.timedOut) return {
+		threadId: null,
+		agentMessage: "",
+		fileChanges: [],
+		commandsExecuted: [],
+		usage: null,
+		errors: ["Codex timed out. Increase BRIDGE_TIMEOUT_MS if needed."]
+	};
+	const parsed = parseCodexOutput(result.stdout);
+	if (result.exitCode !== 0 && !parsed.agentMessage) {
+		const stderr = result.stderr.toLowerCase();
+		if (stderr.includes("api key") || stderr.includes("authentication") || stderr.includes("unauthorized")) parsed.errors.push("Codex API key issue. Ensure OPENAI_API_KEY is set.");
+		else if (result.stderr.trim()) parsed.errors.push(result.stderr.trim());
+	}
+	return parsed;
+}
+function formatCodexResponse(parsed) {
+	if (parsed.errors.length > 0 && !parsed.agentMessage) return {
+		content: [{
+			type: "text",
+			text: `Error: ${parsed.errors.join("; ")}`
+		}],
+		isError: true
+	};
+	let text = parsed.agentMessage;
+	if (parsed.fileChanges.length > 0) {
+		text += "\n\n**Files changed:**\n";
+		for (const fc of parsed.fileChanges) text += `- ${fc.kind}: ${fc.path}\n`;
+	}
+	if (parsed.commandsExecuted.length > 0) {
+		text += "\n\n**Commands executed:**\n";
+		for (const cmd of parsed.commandsExecuted) text += `- \`${cmd.command}\` (exit: ${cmd.exitCode})\n`;
+	}
+	return { content: [{
+		type: "text",
+		text
+	}] };
+}
+server.registerTool("codex_query", {
+	title: "Ask Codex",
+	description: "Ask OpenAI Codex a question or give it a task. Use for getting a second opinion, exploring unfamiliar code, or tasks that benefit from a different model's perspective.",
+	inputSchema: {
+		prompt: z.string().describe("The question or task for Codex"),
+		workingDirectory: z.string().optional().describe("Working directory (defaults to server cwd)"),
+		model: z.string().optional().describe("Override the Codex model (e.g., o4-mini, o3)"),
+		sandbox: z.enum([
+			"read-only",
+			"workspace-write",
+			"danger-full-access"
+		]).optional().default("read-only").describe("Sandbox level controlling what Codex can modify")
+	}
+}, async ({ prompt, workingDirectory, model, sandbox }) => {
+	return formatCodexResponse(await runCodex(prompt, {
+		workingDirectory,
+		model,
+		sandbox
+	}));
+});
+server.registerTool("codex_review_code", {
+	title: "Codex Code Review",
+	description: "Ask Codex to review code. Provide a git diff range, file paths, or a code snippet. Returns specific, actionable feedback.",
+	inputSchema: {
+		target: z.string().describe("What to review: git diff range (e.g., \"HEAD~3..HEAD\"), file paths, or code snippet"),
+		focusAreas: z.string().optional().describe("Focus on: bugs, performance, style, security, etc."),
+		context: z.string().optional().describe("Additional context about the codebase or changes"),
+		workingDirectory: z.string().optional()
+	}
+}, async ({ target, focusAreas, context, workingDirectory }) => {
+	let prompt = `Review the following code changes. Provide specific, actionable feedback with line references.\n\nTarget: ${target}`;
+	if (focusAreas) prompt += `\n\nFocus areas: ${focusAreas}`;
+	if (context) prompt += `\n\nContext: ${context}`;
+	return formatCodexResponse(await runCodex(prompt, {
+		workingDirectory,
+		sandbox: "read-only"
+	}));
+});
+server.registerTool("codex_review_plan", {
+	title: "Codex Plan Review",
+	description: "Ask Codex to critique an implementation plan. Identifies gaps, risks, missing edge cases, and suggests improvements.",
+	inputSchema: {
+		plan: z.string().describe("The implementation plan or design to review"),
+		codebasePath: z.string().optional().describe("Path to relevant codebase for context"),
+		constraints: z.string().optional().describe("Known constraints: timeline, tech stack, compatibility"),
+		workingDirectory: z.string().optional()
+	}
+}, async ({ plan, codebasePath, constraints, workingDirectory }) => {
+	let prompt = `Critique this implementation plan. Identify gaps, risks, missing edge cases, and suggest improvements.\n\nPlan:\n${plan}`;
+	if (codebasePath) prompt += `\n\nRelevant codebase: ${codebasePath}`;
+	if (constraints) prompt += `\n\nConstraints: ${constraints}`;
+	return formatCodexResponse(await runCodex(prompt, {
+		workingDirectory,
+		sandbox: "read-only"
+	}));
+});
+server.registerTool("codex_explain_code", {
+	title: "Codex Explain Code",
+	description: "Ask Codex to deeply explain code, logic, or architecture. Useful for understanding unfamiliar code, onboarding, or documenting complex systems.",
+	inputSchema: {
+		target: z.string().describe("What to explain: file path, function name, module, or code snippet"),
+		depth: z.enum([
+			"overview",
+			"detailed",
+			"trace"
+		]).optional().default("detailed").describe("Depth of explanation: overview, detailed, or full execution trace"),
+		context: z.string().optional().describe("Additional context about the codebase"),
+		workingDirectory: z.string().optional()
+	}
+}, async ({ target, depth, context, workingDirectory }) => {
+	return formatCodexResponse(await runCodex(buildExplainCodePrompt({
+		target,
+		depth,
+		context
+	}), {
+		workingDirectory,
+		sandbox: "read-only"
+	}));
+});
+server.registerTool("codex_plan_perf", {
+	title: "Codex Performance Plan",
+	description: "Ask Codex to analyze performance and create an improvement plan. Identifies bottlenecks, proposes ranked optimizations with expected impact.",
+	inputSchema: {
+		target: z.string().describe("What to optimize: function, module, or pipeline path"),
+		metrics: z.array(z.enum([
+			"latency",
+			"throughput",
+			"memory",
+			"binary-size"
+		])).optional().describe("Performance metrics to focus on"),
+		constraints: z.string().optional().describe("Constraints: must not increase binary size, etc."),
+		context: z.string().optional().describe("Additional context about usage patterns"),
+		workingDirectory: z.string().optional()
+	}
+}, async ({ target, metrics, constraints, context, workingDirectory }) => {
+	return formatCodexResponse(await runCodex(buildPlanPerfPrompt({
+		target,
+		metrics,
+		constraints,
+		context
+	}), {
+		workingDirectory,
+		sandbox: "read-only"
+	}));
+});
+server.registerTool("codex_implement", {
+	title: "Codex Implement",
+	description: "Ask Codex to implement a feature, fix a bug, or make code changes. WARNING: This modifies your codebase. Returns a summary of what was changed.",
+	inputSchema: {
+		task: z.string().describe("What to implement or fix"),
+		workingDirectory: z.string().optional(),
+		model: z.string().optional(),
+		sandbox: z.enum(["workspace-write", "danger-full-access"]).optional().default("workspace-write").describe("Sandbox level (must allow writes)")
+	}
+}, async ({ task, workingDirectory, model, sandbox }) => {
+	return formatCodexResponse(await runCodex(task, {
+		workingDirectory,
+		model,
+		sandbox,
+		fullAuto: true
+	}));
+});
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	logger.info("codex-bridge MCP server started on stdio");
+}
+main().catch((err) => {
+	logger.error("Failed to start codex-bridge:", err);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/dist/prompt-builder-CQ2IGDTq.mjs

@@ -0,0 +1,159 @@
+import { spawn } from "node:child_process";
+
+//#region src/lib/errors.ts
+var BridgeError = class extends Error {
+	constructor(message, code, details) {
+		super(message);
+		this.code = code;
+		this.details = details;
+		this.name = "BridgeError";
+	}
+};
+
+//#endregion
+//#region src/lib/logger.ts
+const isDebug = !!process.env["BRIDGE_DEBUG"];
+const logger = {
+	info(msg, ...args) {
+		console.error(`[INFO] ${msg}`, ...args);
+	},
+	warn(msg, ...args) {
+		console.error(`[WARN] ${msg}`, ...args);
+	},
+	error(msg, ...args) {
+		console.error(`[ERROR] ${msg}`, ...args);
+	},
+	debug(msg, ...args) {
+		if (isDebug) console.error(`[DEBUG] ${msg}`, ...args);
+	}
+};
+
+//#endregion
+//#region src/lib/exec-runner.ts
+const DEFAULT_TIMEOUT_MS = 3e5;
+const MAX_BRIDGE_DEPTH = 2;
+function getTimeoutMs() {
+	const env = process.env["BRIDGE_TIMEOUT_MS"];
+	if (env) {
+		const parsed = parseInt(env, 10);
+		if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+	}
+	return DEFAULT_TIMEOUT_MS;
+}
+function checkRecursionDepth() {
+	const depth = parseInt(process.env["BRIDGE_DEPTH"] ?? "0", 10);
+	if (depth >= MAX_BRIDGE_DEPTH) throw new BridgeError(`Maximum bridge nesting depth reached (${depth} >= ${MAX_BRIDGE_DEPTH}). This prevents infinite recursion between Claude and Codex.`, "RECURSION_LIMIT");
+}
+function execCommand(options) {
+	checkRecursionDepth();
+	const timeoutMs = options.timeoutMs ?? getTimeoutMs();
+	const currentDepth = parseInt(process.env["BRIDGE_DEPTH"] ?? "0", 10);
+	const env = {
+		...process.env,
+		...options.env,
+		BRIDGE_DEPTH: String(currentDepth + 1)
+	};
+	return new Promise((resolve, reject) => {
+		logger.debug(`exec: ${options.command} ${options.args.join(" ")} (cwd: ${options.cwd ?? process.cwd()}, timeout: ${timeoutMs}ms)`);
+		let child;
+		try {
+			child = spawn(options.command, options.args, {
+				cwd: options.cwd ?? process.cwd(),
+				env,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			reject(new BridgeError(`Failed to spawn "${options.command}": ${err instanceof Error ? err.message : String(err)}`, "CLI_NOT_FOUND"));
+			return;
+		}
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		let timedOut = false;
+		let settled = false;
+		child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+		child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+		const timer = setTimeout(() => {
+			timedOut = true;
+			logger.warn(`Process timed out after ${timeoutMs}ms, sending SIGTERM`);
+			child.kill("SIGTERM");
+			setTimeout(() => {
+				if (!settled) {
+					logger.warn("Process did not exit after SIGTERM, sending SIGKILL");
+					child.kill("SIGKILL");
+				}
+			}, 5e3);
+		}, timeoutMs);
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			settled = true;
+			if (err.code === "ENOENT") reject(new BridgeError(`"${options.command}" not found. Is it installed and on your PATH?`, "CLI_NOT_FOUND"));
+			else reject(new BridgeError(`Process error: ${err.message}`, "PROCESS_ERROR", err.code));
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			settled = true;
+			resolve({
+				exitCode: code ?? 1,
+				stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+				stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+				timedOut
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/lib/prompt-builder.ts
+/**
+* Builds a prompt for deep code/logic explanation.
+*/
+function buildExplainCodePrompt(options) {
+	const depth = options.depth ?? "detailed";
+	let prompt = `Explain the following code/module/function in depth.\n\nTarget: ${options.target}\n\n${{
+		overview: "Provide a high-level overview: what the code does, its role in the system, and key abstractions. Keep it concise.",
+		detailed: "Provide a detailed explanation: purpose, control flow, data flow, key design decisions, edge cases, and how it interacts with surrounding code.",
+		trace: "Provide a full execution trace: step through the code path, explain each branch, data transformation, and side effect. Include call chains and state mutations."
+	}[depth]}`;
+	if (options.context) prompt += `\n\nAdditional context: ${options.context}`;
+	prompt += `\n\nStructure your response with:
+1. **Purpose** - What this code does and why it exists
+2. **Key Components** - Main functions, types, data structures
+3. **Control Flow** - How execution proceeds
+4. **Data Flow** - How data is transformed and passed
+5. **Design Decisions** - Why it's structured this way
+6. **Dependencies** - What it depends on and what depends on it`;
+	return prompt;
+}
+/**
+* Builds a prompt for planning performance improvements.
+*/
+function buildPlanPerfPrompt(options) {
+	const metricsList = (options.metrics ?? ["latency", "memory"]).join(", ");
+	let prompt = `Analyze the performance of the following code and create a concrete improvement plan.
+
+Target: ${options.target}
+
+Focus metrics: ${metricsList}
+
+Perform the following analysis:
+1. **Current State** - Read and understand the target code
+2. **Hot Path Analysis** - Identify the critical execution path and where time/memory is spent
+3. **Bottleneck Identification** - List specific bottlenecks with evidence (e.g., unnecessary allocations, redundant computations, cache misses, algorithmic complexity)
+4. **Optimization Plan** - For each bottleneck, propose a ranked optimization with:
+   - Description of the change
+   - Expected impact (quantified if possible)
+   - Implementation difficulty (low/medium/high)
+   - Any correctness risks or trade-offs
+5. **Implementation Order** - Recommend which optimizations to apply first (highest impact, lowest risk)
+6. **Measurement Plan** - How to verify each optimization works (benchmarks, profiling commands)`;
+	if (options.constraints) prompt += `\n\nConstraints: ${options.constraints}`;
+	if (options.context) prompt += `\n\nAdditional context: ${options.context}`;
+	return prompt;
+}
+
+//#endregion
+export { logger as i, buildPlanPerfPrompt as n, execCommand as r, buildExplainCodePrompt as t };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "claude-codex-bridge",
+  "version": "0.1.0",
+  "description": "Bidirectional MCP server bridge between Claude Code and Codex CLI",
+  "type": "module",
+  "bin": {
+    "ccb-codex": "./dist/codex-server.mjs",
+    "ccb-claude": "./dist/claude-server.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "claude",
+    "codex",
+    "bridge",
+    "ai"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "bumpp": "^10.4.1",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
+    "publint": "^0.3.17",
+    "tsdown": "^0.20.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev:codex-server": "tsx src/codex-server.ts",
+    "dev:claude-server": "tsx src/claude-server.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint src/ test/ --type-check",
+    "fmt": "oxfmt --write src/ test/",
+    "fmt:check": "oxfmt --check src/ test/",
+    "publint": "publint",
+    "release": "bumpp"
+  }
+}