@dhrupo/codex-claude-bridge 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,25 @@
+[![npm version](https://img.shields.io/npm/v/%40dhrupo%2Fcodex-claude-bridge)](https://www.npmjs.com/package/@dhrupo/codex-claude-bridge)
+[![CI](https://github.com/dhrupo/codex-claude-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/dhrupo/codex-claude-bridge/actions/workflows/ci.yml)
+[![npm publish](https://github.com/dhrupo/codex-claude-bridge/actions/workflows/publish.yml/badge.svg)](https://github.com/dhrupo/codex-claude-bridge/actions/workflows/publish.yml)
+
 # codex-claude-bridge
 
 Use Claude Code from inside Codex.
 
-This package exposes Claude Code as MCP tools that Codex can call, and also ships a small `codex-claude` command for common flows.
+`@dhrupo/codex-claude-bridge` exposes Claude Code as MCP tools that Codex can call, and also ships a `codex-claude` helper command for common workflows.
 
 ## What You Get
 
 - `codex-claude-mcp`: an MCP server that wraps the local `claude` CLI
-- `codex-claude`: a helper command that drives Codex to call the Claude MCP tools
+- `codex-claude`: a helper command that asks Codex to call Claude tools
 - Three MCP tools:
   - `claude_ask`
   - `claude_review`
   - `claude_delegate`
+- Extra helper workflows:
+  - `codex-claude status`
+  - `codex-claude doctor`
+  - `codex-claude compare`
 
 ## Requirements
 
@@ -19,7 +27,7 @@ This package exposes Claude Code as MCP tools that Codex can call, and also ship
 - `codex` installed and authenticated
 - `claude` installed and authenticated
 
-Check both CLIs first:
+Quick checks:
 
 ```bash
 codex --version
@@ -35,37 +43,34 @@ Install the package:
 npm install -g @dhrupo/codex-claude-bridge
 ```
 
-Register the MCP server in Codex:
+Register the MCP bridge in Codex:
 
 ```bash
 codex-claude install
 ```
 
-That adds a global Codex MCP server named `claude-bridge`.
+That creates a global Codex MCP server named `claude-bridge`.
 
-You can also register it manually:
+Manual alternatives:
 
 ```bash
 codex mcp add claude-bridge -- codex-claude-mcp
-```
-
-Or without a global npm install:
-
-```bash
 codex mcp add claude-bridge -- npx -y @dhrupo/codex-claude-bridge
 ```
 
-Confirm registration:
+Verify:
 
 ```bash
 codex mcp list
+codex-claude status
+codex-claude doctor
 ```
 
 ## Usage
 
-### Run Through The Helper Command
+### Helper Commands
 
-Ask Claude a question through Codex:
+Ask Claude through Codex:
 
 ```bash
 codex-claude ask "Summarize the current repository."
@@ -78,12 +83,40 @@ codex-claude review
 codex-claude review "Review the current workspace for bugs and missing tests."
 ```
 
+Run a review and compare Claude vs Codex side by side:
+
+```bash
+codex-claude review --compare "Review the current workspace for bugs and missing tests."
+```
+
 Delegate an implementation task:
 
 ```bash
 codex-claude delegate "Fix the failing tests with the smallest safe patch."
 ```
 
+Compare Claude and Codex on the same prompt in one readable report:
+
+```bash
+codex-claude compare "Review this architecture and suggest the safest refactor."
+```
+
+Use separate model choices when comparing:
+
+```bash
+codex-claude compare \
+  --codex-model gpt-5.4 \
+  --claude-model sonnet \
+  "Summarize the tradeoffs in this module."
+```
+
+Write reports to disk:
+
+```bash
+codex-claude compare --out compare.md "Review this change and compare results."
+codex-claude status --json --out status.json
+```
+
 If you are outside a git repository, add:
 
 ```bash
@@ -96,7 +129,16 @@ Example:
 codex-claude ask --cwd /path/to/project --skip-git-repo-check "Reply with exactly OK."
 ```
 
-### Run Through Codex Directly
+You can also pass through Claude-focused options when using `ask`, `review`, or `delegate`:
+
+```bash
+codex-claude review \
+  --model sonnet \
+  --permission-mode dontAsk \
+  --append-system-prompt "Focus on reliability and regression risk."
+```
+
+### Direct Codex MCP Usage
 
 Once installed, Codex can call these tools directly:
 
@@ -104,7 +146,7 @@ Once installed, Codex can call these tools directly:
 - `claude_review`: stricter review pass
 - `claude_delegate`: writable implementation/delegation flow
 
-Example `codex exec` prompt:
+Example:
 
 ```bash
 codex exec --cd /path/to/project --skip-git-repo-check \
@@ -116,10 +158,34 @@ codex exec --cd /path/to/project --skip-git-repo-check \
 - Codex discovers the `claude-bridge` MCP server
 - Codex calls one of the bridge tools
 - The bridge runs the local `claude --print` command
-- The Claude response is returned back through MCP to Codex
+- Claude output is returned through MCP back to Codex
 
 This is an MCP bridge, not a native Codex slash-command plugin.
 
+## Status And Comparison
+
+`codex-claude status` checks:
+
+- whether `codex` is installed
+- whether `claude` is installed
+- whether Claude auth is available
+- whether the `claude-bridge` MCP server is registered in Codex
+
+`codex-claude doctor` adds a simple pass/fail diagnostic summary and suggested fixes.
+
+`codex-claude compare` runs both tools on the same prompt:
+
+- Claude runs directly through `claude --print`
+- Codex runs directly through `codex exec`
+- the command returns a single report with:
+  - Claude output
+  - Codex output
+  - a line-by-line diff block for quick human review
+
+`--json` returns machine-readable report data for `status`, `doctor`, and `compare`.
+
+`--out <file>` writes the rendered or JSON report to disk and also prints it to stdout.
+
 ## Development
 
 Install dependencies:
@@ -140,6 +206,20 @@ Start the MCP server directly:
 npm start
 ```
 
+## Publishing
+
+This package is published on npm as:
+
+```bash
+@dhrupo/codex-claude-bridge
+```
+
+The repo includes a GitHub Actions publish workflow. To publish a new version:
+
+1. Bump `package.json`
+2. Commit and push to `main`
+3. Create and push a matching tag like `v0.1.1`
+
 ## Troubleshooting
 
 If the bridge works but Claude returns an auth or access error, test Claude directly first:

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@dhrupo/codex-claude-bridge",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Expose Claude Code as MCP tools for Codex.",
   "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
   "bin": {
-    "codex-claude": "./bin/codex-claude.mjs",
-    "codex-claude-mcp": "./bin/codex-claude-mcp.mjs"
+    "codex-claude": "bin/codex-claude.mjs",
+    "codex-claude-mcp": "bin/codex-claude-mcp.mjs"
   },
   "engines": {
     "node": ">=18.18.0"

package/src/claude-cli.mjs

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { runCommand } from "./process-utils.mjs";
 
 function pushListOption(args, flag, values) {
   if (!Array.isArray(values) || values.length === 0) {
@@ -50,53 +50,19 @@ export async function runClaude(input, options = {}) {
   const cwd = input.cwd || options.cwd || process.cwd();
   const args = buildClaudeArgs(input, options.defaults);
   const outputFormat = input.outputFormat || options.defaults?.outputFormat || "text";
-
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      env: {
-        ...process.env,
-        ...options.env
-      },
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-
-    let stdout = "";
-    let stderr = "";
-
-    child.stdout.on("data", (chunk) => {
-      stdout += String(chunk);
-    });
-
-    child.stderr.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-
-    child.on("error", (error) => {
-      reject(
-        new Error(`Failed to start Claude CLI. Ensure \`claude\` is installed and on PATH. ${error.message}`)
-      );
-    });
-
-    child.on("close", (code) => {
-      const trimmedStdout = stdout.trim();
-      const trimmedStderr = stderr.trim();
-
-      if (code !== 0) {
-        reject(
-          new Error(trimmedStderr || trimmedStdout || `Claude CLI exited with status ${code ?? "unknown"}.`)
-        );
-        return;
-      }
-
-      resolve({
-        command,
-        cwd,
-        args,
-        outputFormat,
-        stdout: normalizeStdout(trimmedStdout, outputFormat),
-        stderr: trimmedStderr
-      });
-    });
+  const result = await runCommand(command, args, {
+    cwd,
+    env: options.env
+  }).catch((error) => {
+    throw new Error(`Failed to start Claude CLI. Ensure \`claude\` is installed and on PATH. ${error.message}`);
   });
+
+  return {
+    command,
+    cwd,
+    args,
+    outputFormat,
+    stdout: normalizeStdout(result.stdout, outputFormat),
+    stderr: result.stderr
+  };
 }

package/src/codex-claude-command.mjs

@@ -1,8 +1,12 @@
 import path from "node:path";
+import { writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 import { DEFAULT_MCP_SERVER_NAME } from "./constants.mjs";
+import { runClaude } from "./claude-cli.mjs";
 import { buildCodexExecArgs, buildCodexMcpAddArgs, runCodex } from "./codex-cli.mjs";
+import { runCommand } from "./process-utils.mjs";
+import { formatCompareReport, formatDoctorReport, formatStatusReport, toJsonReport } from "./render.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const serverScript = path.resolve(__dirname, "../bin/codex-claude-mcp.mjs");
@@ -11,9 +15,12 @@ function usage() {
   return [
     "Usage:",
     "  codex-claude install [--name <server-name>]",
-    "  codex-claude ask [--cwd <dir>] [--model <model>] [--skip-git-repo-check] <prompt>",
-    "  codex-claude review [--cwd <dir>] [--model <model>] [--skip-git-repo-check] [prompt]",
-    "  codex-claude delegate [--cwd <dir>] [--model <model>] [--skip-git-repo-check] <prompt>"
+    "  codex-claude status [--name <server-name>] [--json] [--out <file>]",
+    "  codex-claude doctor [--name <server-name>] [--json] [--out <file>]",
+    "  codex-claude ask [--cwd <dir>] [--model <model>] [--permission-mode <mode>] [--skip-git-repo-check] <prompt>",
+    "  codex-claude review [--compare] [--cwd <dir>] [--model <model>] [--permission-mode <mode>] [--skip-git-repo-check] [prompt]",
+    "  codex-claude delegate [--cwd <dir>] [--model <model>] [--permission-mode <mode>] [--skip-git-repo-check] <prompt>",
+    "  codex-claude compare [--cwd <dir>] [--codex-model <model>] [--claude-model <model>] [--skip-git-repo-check] [--json] [--out <file>] <prompt>"
   ].join("\n");
 }
 
@@ -27,6 +34,15 @@ function parseCommand(argv) {
     command,
     cwd: undefined,
     model: undefined,
+    claudeModel: undefined,
+    codexModel: undefined,
+    permissionMode: undefined,
+    appendSystemPrompt: undefined,
+    outputFormat: "text",
+    maxBudgetUsd: undefined,
+    json: false,
+    out: undefined,
+    compare: false,
     skipGitRepoCheck: false,
     serverName: DEFAULT_MCP_SERVER_NAME,
     prompt: ""
@@ -44,15 +60,58 @@ function parseCommand(argv) {
       options.model = rest[index];
       continue;
     }
+    if (token === "--claude-model") {
+      index += 1;
+      options.claudeModel = rest[index];
+      continue;
+    }
+    if (token === "--codex-model") {
+      index += 1;
+      options.codexModel = rest[index];
+      continue;
+    }
     if (token === "--name") {
       index += 1;
       options.serverName = rest[index];
       continue;
     }
+    if (token === "--permission-mode") {
+      index += 1;
+      options.permissionMode = rest[index];
+      continue;
+    }
+    if (token === "--append-system-prompt") {
+      index += 1;
+      options.appendSystemPrompt = rest[index];
+      continue;
+    }
+    if (token === "--output-format") {
+      index += 1;
+      options.outputFormat = rest[index];
+      continue;
+    }
+    if (token === "--max-budget-usd") {
+      index += 1;
+      options.maxBudgetUsd = Number(rest[index]);
+      continue;
+    }
     if (token === "--skip-git-repo-check") {
       options.skipGitRepoCheck = true;
       continue;
     }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--compare") {
+      options.compare = true;
+      continue;
+    }
+    if (token === "--out") {
+      index += 1;
+      options.out = rest[index];
+      continue;
+    }
     options.prompt = rest.slice(index).join(" ");
     break;
   }
@@ -81,9 +140,22 @@ export function buildCodexClaudePrompt(input) {
   const call = {
     prompt,
     cwd: input.cwd || process.cwd(),
-    outputFormat: "text"
+    outputFormat: input.outputFormat || "text"
   };
 
+  if (input.model) {
+    call.model = input.model;
+  }
+  if (input.permissionMode) {
+    call.permissionMode = input.permissionMode;
+  }
+  if (input.appendSystemPrompt) {
+    call.appendSystemPrompt = input.appendSystemPrompt;
+  }
+  if (typeof input.maxBudgetUsd === "number" && !Number.isNaN(input.maxBudgetUsd)) {
+    call.maxBudgetUsd = input.maxBudgetUsd;
+  }
+
   return [
     `Use the MCP tool \`${toolName}\` exactly once.`,
     "Do not solve this task yourself.",
@@ -93,21 +165,40 @@ export function buildCodexClaudePrompt(input) {
   ].join("\n");
 }
 
-async function installBridge(input) {
+async function installBridge(input, options = {}) {
+  const cwd = input.cwd || process.cwd();
+  const codexBinary = options.codexCommand || "codex";
+  const existing = await runCommand(codexBinary, ["mcp", "list"], {
+    cwd,
+    rejectOnNonZero: false
+  });
+
+  const serverName = input.serverName || DEFAULT_MCP_SERVER_NAME;
+  const alreadyInstalled = (existing.stdout || "")
+    .split("\n")
+    .some((line) => line.trim().startsWith(serverName));
+
+  if (alreadyInstalled) {
+    await runCommand(codexBinary, ["mcp", "remove", serverName], {
+      cwd,
+      rejectOnNonZero: false
+    });
+  }
+
   const args = buildCodexMcpAddArgs({
-    serverName: input.serverName,
+    serverName,
     serverScript
   });
 
   return runCodex(args, {
-    cwd: input.cwd || process.cwd()
+    cwd
   });
 }
 
 async function runViaCodex(input) {
   const args = buildCodexExecArgs({
     cwd: input.cwd,
-    model: input.model,
+    model: input.codexModel || input.model,
     skipGitRepoCheck: input.skipGitRepoCheck,
     prompt: buildCodexClaudePrompt(input)
   });
@@ -117,6 +208,156 @@ async function runViaCodex(input) {
   });
 }
 
+export async function collectStatus(input, options = {}) {
+  const cwd = input.cwd || process.cwd();
+  const serverName = input.serverName || DEFAULT_MCP_SERVER_NAME;
+  const notes = [];
+
+  const codexVersion = await runCommand(options.codexCommand || "codex", ["--version"], {
+    cwd,
+    rejectOnNonZero: false
+  });
+  const claudeVersion = await runCommand(options.claudeCommand || "claude", ["--version"], {
+    cwd,
+    rejectOnNonZero: false
+  });
+  const claudeAuth = await runCommand(options.claudeCommand || "claude", ["auth", "status"], {
+    cwd,
+    rejectOnNonZero: false
+  });
+  const mcpList = await runCommand(options.codexCommand || "codex", ["mcp", "list"], {
+    cwd,
+    rejectOnNonZero: false
+  });
+
+  if (codexVersion.code !== 0) {
+    notes.push("Codex CLI is not available or not executable.");
+  }
+  if (claudeVersion.code !== 0) {
+    notes.push("Claude CLI is not available or not executable.");
+  }
+  if (claudeAuth.code !== 0) {
+    notes.push("Claude auth check failed. Run `claude auth login`.");
+  }
+
+  const mcpLine = (mcpList.stdout || "")
+    .split("\n")
+    .find((line) => line.trim().startsWith(serverName));
+
+  return {
+    codex: {
+      version: codexVersion.stdout || codexVersion.stderr || "missing"
+    },
+    claude: {
+      version: claudeVersion.stdout || claudeVersion.stderr || "missing",
+      auth: claudeAuth.stdout || claudeAuth.stderr || "unknown"
+    },
+    mcp: {
+      serverName,
+      installed: Boolean(mcpLine),
+      command: mcpLine || ""
+    },
+    notes
+  };
+}
+
+export async function collectDoctorReport(input, options = {}) {
+  const status = await collectStatus(input, options);
+  const checks = [
+    {
+      name: "codex cli",
+      ok: !/missing|not available/i.test(status.codex.version),
+      detail: status.codex.version
+    },
+    {
+      name: "claude cli",
+      ok: !/missing|not available/i.test(status.claude.version),
+      detail: status.claude.version
+    },
+    {
+      name: "claude auth",
+      ok: /loggedIn|logged in|subscriptionType/i.test(status.claude.auth),
+      detail: status.claude.auth.split("\n")[0]
+    },
+    {
+      name: "mcp server",
+      ok: status.mcp.installed,
+      detail: status.mcp.serverName
+    }
+  ];
+
+  const nextSteps = [];
+  if (!checks[0].ok) {
+    nextSteps.push("Install or fix the Codex CLI, then rerun `codex-claude doctor`.");
+  }
+  if (!checks[1].ok) {
+    nextSteps.push("Install or fix the Claude CLI, then rerun `codex-claude doctor`.");
+  }
+  if (!checks[2].ok) {
+    nextSteps.push("Run `claude auth login` and verify direct Claude access with `claude -p --output-format text \"Reply with exactly OK.\"`.");
+  }
+  if (!checks[3].ok) {
+    nextSteps.push("Run `codex-claude install` to register the MCP bridge in Codex.");
+  }
+
+  return {
+    ok: checks.every((check) => check.ok),
+    checks,
+    nextSteps,
+    status
+  };
+}
+
+export async function compareCodexAndClaude(input) {
+  const cwd = input.cwd || process.cwd();
+  const prompt = input.prompt;
+
+  if (!prompt) {
+    throw new Error(usage());
+  }
+
+  const [claudeResult, codexResult] = await Promise.allSettled([
+    runClaude({
+      prompt,
+      cwd,
+      outputFormat: "text",
+      model: input.claudeModel || input.model,
+      permissionMode: input.permissionMode,
+      appendSystemPrompt: input.appendSystemPrompt,
+      maxBudgetUsd: input.maxBudgetUsd
+    }),
+    runCodex(
+      buildCodexExecArgs({
+        cwd,
+        model: input.codexModel || input.model,
+        skipGitRepoCheck: input.skipGitRepoCheck,
+        prompt
+      }),
+      { cwd }
+    )
+  ]);
+
+  return {
+    prompt,
+    cwd,
+    claudeOutput:
+      claudeResult.status === "fulfilled"
+        ? claudeResult.value.stdout
+        : `ERROR: ${claudeResult.reason instanceof Error ? claudeResult.reason.message : String(claudeResult.reason)}`,
+    codexOutput:
+      codexResult.status === "fulfilled"
+        ? codexResult.value.stdout
+        : `ERROR: ${codexResult.reason instanceof Error ? codexResult.reason.message : String(codexResult.reason)}`
+  };
+}
+
+async function emitOutput(output, input) {
+  if (input.out) {
+    await writeFile(path.resolve(input.cwd || process.cwd(), input.out), output, "utf8");
+  }
+  console.log(output);
+}
+
 export async function runCodexClaudeCli(argv) {
   const input = parseCommand(argv);
 
@@ -133,11 +374,41 @@ export async function runCodexClaudeCli(argv) {
     return;
   }
 
+  if (input.command === "status") {
+    const report = await collectStatus(input);
+    const output = input.json ? toJsonReport(report) : formatStatusReport(report);
+    await emitOutput(output, input);
+    return;
+  }
+
+  if (input.command === "doctor") {
+    const report = await collectDoctorReport(input);
+    const output = input.json ? toJsonReport(report) : formatDoctorReport(report);
+    await emitOutput(output, input);
+    return;
+  }
+
+  if (input.command === "compare") {
+    const report = await compareCodexAndClaude(input);
+    const output = input.json ? toJsonReport(report) : formatCompareReport(report);
+    await emitOutput(output, input);
+    return;
+  }
+
+  if (input.command === "review" && input.compare) {
+    const report = await compareCodexAndClaude({
+      ...input,
+      prompt:
+        input.prompt || "Review the current repository for bugs, regressions, and missing tests."
+    });
+    const output = input.json ? toJsonReport(report) : formatCompareReport(report);
+    await emitOutput(output, input);
+    return;
+  }
+
   if (input.command === "ask" || input.command === "review" || input.command === "delegate") {
     const result = await runViaCodex(input);
-    if (result.stdout) {
-      console.log(result.stdout);
-    }
+    await emitOutput(result.stdout || "", input);
     return;
   }
 

package/src/codex-cli.mjs

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { runCommand } from "./process-utils.mjs";
 
 export function buildCodexExecArgs(input) {
   const args = ["exec"];
@@ -33,46 +33,10 @@ export function buildCodexMcpAddArgs(input) {
 
 export async function runCodex(args, options = {}) {
   const command = options.command || "codex";
-  const cwd = options.cwd || process.cwd();
-
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      env: {
-        ...process.env,
-        ...options.env
-      },
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-
-    let stdout = "";
-    let stderr = "";
-
-    child.stdout.on("data", (chunk) => {
-      stdout += String(chunk);
-    });
-
-    child.stderr.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-
-    child.on("error", (error) => {
-      reject(new Error(`Failed to start Codex CLI. Ensure \`codex\` is installed and on PATH. ${error.message}`));
-    });
-
-    child.on("close", (code) => {
-      if (code !== 0) {
-        reject(new Error(stderr.trim() || stdout.trim() || `Codex CLI exited with status ${code ?? "unknown"}.`));
-        return;
-      }
-
-      resolve({
-        command,
-        args,
-        cwd,
-        stdout: stdout.trim(),
-        stderr: stderr.trim()
-      });
-    });
+  return runCommand(command, args, {
+    cwd: options.cwd,
+    env: options.env
+  }).catch((error) => {
+    throw new Error(`Failed to start Codex CLI. Ensure \`codex\` is installed and on PATH. ${error.message}`);
   });
 }

package/src/process-utils.mjs

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+
+export async function runCommand(command, args, options = {}) {
+  if (typeof globalThis.__runCommandForTest === "function") {
+    return globalThis.__runCommandForTest(command, args, options);
+  }
+
+  const cwd = options.cwd || process.cwd();
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: {
+        ...process.env,
+        ...options.env
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("error", (error) => {
+      reject(new Error(`Failed to start \`${command}\`. ${error.message}`));
+    });
+
+    child.on("close", (code) => {
+      const result = {
+        command,
+        args,
+        cwd,
+        code: code ?? 1,
+        stdout: stdout.trim(),
+        stderr: stderr.trim()
+      };
+
+      if (result.code !== 0 && options.rejectOnNonZero !== false) {
+        reject(new Error(result.stderr || result.stdout || `\`${command}\` exited with status ${result.code}.`));
+        return;
+      }
+
+      resolve(result);
+    });
+  });
+}

package/src/render.mjs

@@ -0,0 +1,104 @@
+function normalizeForDiff(text) {
+  return String(text || "")
+    .replace(/\r\n/g, "\n")
+    .replace(/[ \t]+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function makeSection(title, body) {
+  return [`## ${title}`, "", body || "_No output_", ""].join("\n");
+}
+
+function diffLines(left, right) {
+  const leftLines = normalizeForDiff(left).split("\n");
+  const rightLines = normalizeForDiff(right).split("\n");
+  const max = Math.max(leftLines.length, rightLines.length);
+  const lines = [];
+
+  for (let index = 0; index < max; index += 1) {
+    const leftLine = leftLines[index];
+    const rightLine = rightLines[index];
+    if (leftLine === rightLine) {
+      if (leftLine !== undefined) {
+        lines.push(`  ${leftLine}`);
+      }
+      continue;
+    }
+    if (leftLine !== undefined) {
+      lines.push(`- ${leftLine}`);
+    }
+    if (rightLine !== undefined) {
+      lines.push(`+ ${rightLine}`);
+    }
+  }
+
+  return lines.join("\n").trim() || "Outputs are identical.";
+}
+
+export function formatStatusReport(report) {
+  const lines = [
+    "# codex-claude status",
+    "",
+    `- codex cli: ${report.codex.version}`,
+    `- claude cli: ${report.claude.version}`,
+    `- claude auth: ${report.claude.auth}`,
+    `- mcp server (${report.mcp.serverName}): ${report.mcp.installed ? "installed" : "missing"}`
+  ];
+
+  if (report.mcp.installed && report.mcp.command) {
+    lines.push(`- mcp command: ${report.mcp.command}`);
+  }
+
+  if (report.notes.length) {
+    lines.push("", "Notes:");
+    for (const note of report.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function toJsonReport(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+export function formatCompareReport(report) {
+  const lines = [
+    "# codex-claude compare",
+    "",
+    `Prompt: ${report.prompt}`,
+    `Working directory: \`${report.cwd}\``,
+    ""
+  ];
+
+  lines.push(makeSection("Claude", ["```text", report.claudeOutput, "```"].join("\n")));
+  lines.push(makeSection("Codex", ["```text", report.codexOutput, "```"].join("\n")));
+  lines.push(makeSection("Diff", ["```diff", diffLines(report.claudeOutput, report.codexOutput), "```"].join("\n")));
+
+  return lines.join("\n").trimEnd();
+}
+
+export function formatDoctorReport(report) {
+  const lines = [
+    "# codex-claude doctor",
+    "",
+    `- overall: ${report.ok ? "ok" : "needs attention"}`,
+    ""
+  ];
+
+  lines.push("Checks:");
+  for (const check of report.checks) {
+    lines.push(`- ${check.name}: ${check.ok ? "ok" : "failed"}${check.detail ? ` (${check.detail})` : ""}`);
+  }
+
+  if (report.nextSteps.length) {
+    lines.push("", "Next steps:");
+    for (const step of report.nextSteps) {
+      lines.push(`- ${step}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/tests/claude-cli.test.mjs

@@ -1,57 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { buildClaudeArgs } from "../src/claude-cli.mjs";
-
-test("buildClaudeArgs creates the expected Claude CLI invocation", () => {
-  const args = buildClaudeArgs({
-    prompt: "Review the current diff",
-    outputFormat: "json",
-    model: "sonnet",
-    permissionMode: "dontAsk",
-    allowedTools: ["Read", "Bash(git:*)"],
-    disallowedTools: ["Edit"],
-    appendSystemPrompt: "Be strict.",
-    maxBudgetUsd: 1.5
-  });
-
-  assert.deepEqual(args, [
-    "--print",
-    "--output-format",
-    "json",
-    "--model",
-    "sonnet",
-    "--permission-mode",
-    "dontAsk",
-    "--max-budget-usd",
-    "1.5",
-    "--append-system-prompt",
-    "Be strict.",
-    "--allowedTools",
-    "Read Bash(git:*)",
-    "--disallowedTools",
-    "Edit",
-    "Review the current diff"
-  ]);
-});
-
-test("buildClaudeArgs falls back to text output when unspecified", () => {
-  const args = buildClaudeArgs(
-    {
-      prompt: "Summarize the repo"
-    },
-    {
-      outputFormat: "text",
-      permissionMode: "default"
-    }
-  );
-
-  assert.deepEqual(args, [
-    "--print",
-    "--output-format",
-    "text",
-    "--permission-mode",
-    "default",
-    "Summarize the repo"
-  ]);
-});

package/tests/codex-cli.test.mjs

@@ -1,52 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { buildCodexExecArgs, buildCodexMcpAddArgs } from "../src/codex-cli.mjs";
-import { buildCodexClaudePrompt } from "../src/codex-claude-command.mjs";
-
-test("buildCodexExecArgs creates the expected codex exec invocation", () => {
-  const args = buildCodexExecArgs({
-    cwd: "/repo",
-    model: "gpt-5.4",
-    skipGitRepoCheck: true,
-    prompt: "Use the tool."
-  });
-
-  assert.deepEqual(args, [
-    "exec",
-    "--cd",
-    "/repo",
-    "--model",
-    "gpt-5.4",
-    "--skip-git-repo-check",
-    "Use the tool."
-  ]);
-});
-
-test("buildCodexMcpAddArgs registers the local bridge server", () => {
-  const args = buildCodexMcpAddArgs({
-    serverName: "claude-bridge",
-    serverScript: "/tmp/codex-claude-mcp.mjs"
-  });
-
-  assert.deepEqual(args, [
-    "mcp",
-    "add",
-    "claude-bridge",
-    "--",
-    "node",
-    "/tmp/codex-claude-mcp.mjs"
-  ]);
-});
-
-test("buildCodexClaudePrompt targets the review tool with a default review request", () => {
-  const prompt = buildCodexClaudePrompt({
-    command: "review",
-    cwd: "/repo"
-  });
-
-  assert.match(prompt, /claude_review/);
-  assert.match(prompt, /Return only the tool result/);
-  assert.match(prompt, /Review the current repository for bugs, regressions, and missing tests/);
-  assert.match(prompt, /"cwd":"\/repo"/);
-});

package/tests/server.test.mjs

@@ -1,12 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { createServer } from "../src/server.mjs";
-
-test("createServer registers the expected Claude bridge tools", async () => {
-  const server = await createServer();
-  assert.deepEqual(
-    Object.keys(server._registeredTools).sort(),
-    ["claude_ask", "claude_delegate", "claude_review"]
-  );
-});

package/tests/tools.test.mjs

@@ -1,19 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { handleClaudeAsk } from "../src/tools.mjs";
-
-test("handleClaudeAsk renders a Codex-friendly text block", async () => {
-  const originalPath = process.env.PATH;
-  process.env.PATH = "/tmp";
-
-  const response = await handleClaudeAsk({
-    prompt: "Summarize",
-    outputFormat: "text"
-  }).catch((error) => error);
-
-  process.env.PATH = originalPath;
-
-  assert.equal(response instanceof Error, true);
-  assert.match(response.message, /Failed to start Claude CLI|Ensure `claude` is installed/);
-});