@indianaprado/claude-code-companion 0.1.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "claude-code-companion",
+  "version": "0.1.0",
+  "description": "Use Claude Code from Codex for review, rescue, and delegated tasks.",
+  "author": {
+    "name": "Local developer"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Claude Code Companion",
+    "shortDescription": "Delegate Codex work to Claude Code.",
+    "longDescription": "A local companion plugin that lets Codex call the installed Claude Code CLI for read-only reviews, adversarial reviews, write-capable rescue tasks, and background jobs.",
+    "developerName": "Local developer",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Read", "Write"],
+    "defaultPrompt": [
+      "Ask Claude to review my current changes.",
+      "Delegate this UI task to Claude Code.",
+      "Check Claude task status."
+    ]
+  },
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "claude-code-companion": {
+      "command": "node",
+      "args": [
+        "./scripts/claude-mcp-server.mjs"
+      ]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,113 @@
+# Claude Code Companion
+
+Use the installed Claude Code CLI from Codex through a local MCP server.
+
+This plugin mirrors the mode-driven shape of `openai/codex-plugin-cc` in reverse:
+
+- read-only `review`
+- read-only `adversarial_review`
+- write-capable `rescue`
+- foreground or background execution
+- `status`, `result`, and `cancel` job control
+
+## Requirements
+
+- Node.js
+- Claude Code CLI available as `claude`
+- Claude Code authenticated in the same terminal environment
+
+## One-line Codex MCP Install
+
+After publishing this package to npm:
+
+```bash
+codex mcp add claude-code-companion npx -y @indianaprado/claude-code-companion
+```
+
+That command adds a global Codex MCP server entry named `claude-code-companion`.
+Codex will start the MCP server with `npx` when needed.
+
+For a local unpublished checkout:
+
+```bash
+codex mcp add claude-code-companion node /Users/pranaybindela/Desktop/work/claude-mcp/claude-code-companion/scripts/claude-mcp-server.mjs
+```
+
+Confirm the entry:
+
+```bash
+codex mcp list
+codex mcp get claude-code-companion
+```
+
+## Publish To npm
+
+The package name is scoped because the unscoped `claude-code-companion` name is already taken on npm.
+The package intentionally has no npm dependencies, no install lifecycle scripts, and no external
+package imports. Check that before publishing:
+
+```bash
+npm run supply-chain:check
+```
+
+```bash
+npm login
+npm publish --access public
+```
+
+Dry-run before publishing:
+
+```bash
+npm publish --dry-run
+```
+
+Check setup:
+
+```bash
+node scripts/claude-companion.mjs setup
+```
+
+## Manual CLI
+
+```bash
+node scripts/claude-companion.mjs review
+node scripts/claude-companion.mjs adversarial-review "focus on UX and frontend state bugs"
+node scripts/claude-companion.mjs rescue --read-only "investigate why the dashboard is slow"
+node scripts/claude-companion.mjs rescue --resume --session-id <uuid> "continue this Claude session"
+node scripts/claude-companion.mjs rescue --background "implement the mock frontend"
+node scripts/claude-companion.mjs status
+node scripts/claude-companion.mjs result <job-id>
+node scripts/claude-companion.mjs cancel <job-id>
+```
+
+When installed from npm, the helper CLI is available as:
+
+```bash
+npx -y -p @indianaprado/claude-code-companion claude-code-companion-cli setup
+```
+
+## MCP Tools
+
+The bundled MCP server exposes:
+
+- `setup`
+- `review`
+- `adversarial_review`
+- `rescue`
+- `status`
+- `result`
+- `cancel`
+
+`rescue` is write-capable by default. Pass `readOnly: true` for investigation-only delegation.
+
+`model` is optional. When omitted, the plugin does not pass `--model`, so Claude CLI chooses its
+current default/latest model. On this machine, that currently selected `claude-opus-4-5-20251101`.
+When provided, `model` is forwarded to `claude --model`, so aliases such as `sonnet` and full model
+names such as `claude-sonnet-4-5-20250929` work when supported by the installed Claude CLI.
+
+Session controls:
+
+- `resume: true` resumes the most recent Claude conversation in the current directory.
+- `resume: true` plus `sessionId` resumes that exact Claude session.
+- `sessionId` without `resume` starts or uses that exact session id.
+- `forkSession: true` is passed through to Claude CLI with resume; behavior depends on the installed CLI.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@indianaprado/claude-code-companion",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Claude Code Companion MCP server for Codex.",
+  "type": "module",
+  "bin": {
+    "claude-code-companion": "scripts/claude-mcp-server.mjs",
+    "claude-code-companion-cli": "scripts/claude-companion.mjs"
+  },
+  "files": [
+    ".codex-plugin/",
+    ".mcp.json",
+    "README.md",
+    "scripts/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "codex",
+    "mcp",
+    "claude-code",
+    "claude",
+    "agent"
+  ],
+  "author": "Local developer",
+  "license": "MIT",
+  "scripts": {
+    "setup": "node scripts/claude-companion.mjs setup",
+    "status": "node scripts/claude-companion.mjs status",
+    "test:syntax": "find scripts -name '*.mjs' -exec node --check {} \\;",
+    "supply-chain:check": "node scripts/audit-package.mjs",
+    "test": "npm run supply-chain:check && npm run test:syntax",
+    "pack:dry": "npm pack --dry-run"
+  }
+}

package/scripts/audit-package.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(new URL("..", import.meta.url).pathname);
+const PACKAGE_JSON = path.join(ROOT, "package.json");
+const FORBIDDEN_DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+  "bundledDependencies",
+  "bundleDependencies"
+];
+const FORBIDDEN_LIFECYCLE_SCRIPTS = [
+  "preinstall",
+  "install",
+  "postinstall",
+  "prepare",
+  "prepublish",
+  "prepublishOnly",
+  "prepack",
+  "postpack"
+];
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function readPackageJson() {
+  return JSON.parse(fs.readFileSync(PACKAGE_JSON, "utf8"));
+}
+
+function walk(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walk(fullPath));
+    } else if (entry.isFile() && fullPath.endsWith(".mjs")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function extractBareImports(source) {
+  const matches = [];
+  const patterns = [
+    /\bimport\s+[^'"]*from\s+['"]([^'"]+)['"]/g,
+    /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+  ];
+  for (const pattern of patterns) {
+    for (const match of source.matchAll(pattern)) {
+      const specifier = match[1];
+      if (!specifier.startsWith("node:") && !specifier.startsWith("./") && !specifier.startsWith("../")) {
+        matches.push(specifier);
+      }
+    }
+  }
+  return matches;
+}
+
+const pkg = readPackageJson();
+
+for (const field of FORBIDDEN_DEP_FIELDS) {
+  if (pkg[field] && Object.keys(pkg[field]).length > 0) {
+    fail(`Forbidden dependency field is populated: ${field}`);
+  }
+}
+
+for (const scriptName of FORBIDDEN_LIFECYCLE_SCRIPTS) {
+  if (pkg.scripts?.[scriptName]) {
+    fail(`Forbidden npm lifecycle script present: ${scriptName}`);
+  }
+}
+
+for (const file of walk(path.join(ROOT, "scripts"))) {
+  const bareImports = extractBareImports(fs.readFileSync(file, "utf8"));
+  if (bareImports.length > 0) {
+    fail(`${path.relative(ROOT, file)} imports external package(s): ${bareImports.join(", ")}`);
+  }
+}
+
+if (!process.exitCode) {
+  process.stdout.write("Supply-chain check passed: no npm dependencies, no install lifecycle scripts, no external package imports.\n");
+}

package/scripts/claude-companion.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { parseArgs } from "./lib/args.mjs";
+import { getClaudeAuthStatus, getClaudeVersion, runClaude } from "./lib/claude.mjs";
+import { binaryStatus } from "./lib/process.mjs";
+import { buildRescuePrompt, buildReviewPrompt } from "./lib/prompts.mjs";
+import { cancelJob, createJob, findJob, launchWorker, markJob, recentJobs } from "./lib/jobs.mjs";
+import { appendLog, now, readJob, resolveStateDir } from "./lib/state.mjs";
+import { renderQueued, renderSetup, renderStatus, renderStoredResult, renderTaskResult } from "./lib/render.mjs";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+
+function isDirectRun() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  try {
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(SCRIPT_PATH);
+  } catch {
+    return path.resolve(process.argv[1]) === path.resolve(SCRIPT_PATH);
+  }
+}
+
+function output(value, asJson = false) {
+  process.stdout.write(asJson ? `${JSON.stringify(value, null, 2)}\n` : String(value));
+}
+
+function cwdFrom(options) {
+  return options.cwd ? path.resolve(process.cwd(), options.cwd) : process.cwd();
+}
+
+function summarize(prompt) {
+  const text = String(prompt ?? "").replace(/\s+/g, " ").trim();
+  return text.length > 96 ? `${text.slice(0, 93)}...` : text;
+}
+
+export async function setupCommand(input = {}) {
+  const cwd = path.resolve(input.cwd ?? process.cwd());
+  const node = binaryStatus("node", ["--version"], { cwd });
+  const claude = getClaudeVersion(cwd);
+  const auth = getClaudeAuthStatus(cwd);
+  const authExplicitlyMissing = auth.parsed?.loggedIn === false;
+  return {
+    ready: node.available && claude.available && !authExplicitlyMissing,
+    node,
+    claude,
+    auth,
+    stateDir: resolveStateDir(cwd)
+  };
+}
+
+async function executeClaudeJob(cwd, job, request) {
+  markJob(cwd, job.id, {
+    status: "running",
+    phase: "running",
+    startedAt: now(),
+    request
+  });
+  const result = await runClaude(request.prompt, {
+    cwd,
+    readOnly: request.readOnly,
+    resume: request.resume,
+    sessionId: request.sessionId,
+    model: request.model,
+    effort: request.effort,
+    maxBudgetUsd: request.maxBudgetUsd,
+    permissionMode: request.permissionMode,
+    onStart: (pid) => {
+      markJob(cwd, job.id, { pid, phase: "claude-running" });
+      appendLog(job.logFile, `[${now()}] Claude process started pid=${pid}.\n`);
+    },
+    onStdout: (chunk) => appendLog(job.logFile, chunk),
+    onStderr: (chunk) => appendLog(job.logFile, chunk)
+  });
+  const rendered = renderTaskResult(job, result);
+  markJob(cwd, job.id, {
+    status: result.status === 0 ? "completed" : "failed",
+    phase: result.status === 0 ? "done" : "failed",
+    pid: null,
+    completedAt: now(),
+    sessionId: result.sessionId,
+    costUsd: result.costUsd,
+    result: {
+      status: result.status,
+      signal: result.signal,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      finalText: result.finalText,
+      parsed: result.parsed
+    },
+    rendered
+  });
+  return { job: readJob(cwd, job.id), rendered, result };
+}
+
+async function runJobRequest(cwd, request, options = {}) {
+  const job = createJob(cwd, {
+    prefix: request.kind === "review" ? "review" : "task",
+    kind: request.kind,
+    title: request.title,
+    summary: request.summary,
+    readOnly: request.readOnly,
+    background: request.background
+  });
+  markJob(cwd, job.id, { request });
+
+  if (request.background) {
+    const child = launchWorker(SCRIPT_PATH, cwd, job.id);
+    markJob(cwd, job.id, { pid: child.pid ?? null, phase: "queued" });
+    return { job: readJob(cwd, job.id), rendered: renderQueued(job), queued: true };
+  }
+
+  return executeClaudeJob(cwd, job, request, options);
+}
+
+export async function reviewCommand(input = {}) {
+  const cwd = path.resolve(input.cwd ?? process.cwd());
+  const prompt = buildReviewPrompt(cwd, { scope: input.scope, base: input.base, focus: input.focus });
+  return runJobRequest(cwd, {
+    kind: input.adversarial ? "adversarial-review" : "review",
+    title: input.adversarial ? "Claude Adversarial Review" : "Claude Review",
+    summary: input.adversarial ? summarize(input.focus || "Adversarial review") : "Review current git state",
+    prompt,
+    readOnly: true,
+    background: Boolean(input.background),
+    model: input.model,
+    effort: input.effort,
+    maxBudgetUsd: input.maxBudgetUsd
+  });
+}
+
+export async function rescueCommand(input = {}) {
+  const cwd = path.resolve(input.cwd ?? process.cwd());
+  if (!input.prompt || !String(input.prompt).trim()) {
+    throw new Error("Provide a task prompt for Claude.");
+  }
+  const readOnly = Boolean(input.readOnly);
+  const prompt = buildRescuePrompt(input.prompt, { readOnly });
+  return runJobRequest(cwd, {
+    kind: "task",
+    title: input.resume ? "Claude Resume" : "Claude Task",
+    summary: summarize(input.prompt),
+    prompt,
+    readOnly,
+    background: Boolean(input.background),
+    resume: Boolean(input.resume),
+    sessionId: input.sessionId,
+    forkSession: input.forkSession,
+    model: input.model,
+    effort: input.effort,
+    maxBudgetUsd: input.maxBudgetUsd,
+    permissionMode: input.permissionMode
+  });
+}
+
+export function statusCommand(input = {}) {
+  const cwd = path.resolve(input.cwd ?? process.cwd());
+  return recentJobs(cwd, Boolean(input.all));
+}
+
+export function resultCommand(input = {}) {
+  const cwd = path.resolve(input.cwd ?? process.cwd());
+  const job = findJob(cwd, input.jobId ?? "");
+  return { job, stored: job ? readJob(cwd, job.id) : null };
+}
+
+export function cancelCommand(input = {}) {
+  const cwd = path.resolve(input.cwd ?? process.cwd());
+  return cancelJob(cwd, input.jobId ?? "");
+}
+
+async function handleWorker(argv) {
+  const { options } = parseArgs(argv, {
+    valueOptions: ["cwd", "job-id"]
+  });
+  const cwd = cwdFrom(options);
+  const job = readJob(cwd, options["job-id"]);
+  if (!job?.request) {
+    throw new Error(`No queued Claude job found for ${options["job-id"]}.`);
+  }
+  await executeClaudeJob(cwd, job, job.request);
+}
+
+async function main() {
+  const [command, ...argv] = process.argv.slice(2);
+  const common = {
+    valueOptions: ["cwd", "job-id", "base", "scope", "model", "effort", "max-budget-usd", "session-id", "permission-mode"],
+    booleanOptions: ["json", "background", "read-only", "write", "resume", "fresh", "all", "adversarial", "fork-session"]
+  };
+  const { options, positionals } = parseArgs(argv, common);
+  const cwd = cwdFrom(options);
+  const asJson = Boolean(options.json);
+
+  if (command === "worker") {
+    await handleWorker(argv);
+    return;
+  }
+  if (command === "setup") {
+    const report = await setupCommand({ cwd });
+    output(asJson ? report : renderSetup(report), asJson);
+    return;
+  }
+  if (command === "review" || command === "adversarial-review") {
+    const response = await reviewCommand({
+      cwd,
+      scope: options.scope,
+      base: options.base,
+      focus: positionals.join(" "),
+      adversarial: command === "adversarial-review" || options.adversarial,
+      background: options.background,
+      model: options.model,
+      effort: options.effort,
+      maxBudgetUsd: options["max-budget-usd"]
+    });
+    output(asJson ? response : response.rendered, asJson);
+    return;
+  }
+  if (command === "rescue" || command === "task") {
+    const response = await rescueCommand({
+      cwd,
+      prompt: positionals.join(" "),
+      readOnly: Boolean(options["read-only"]) && !options.write,
+      background: options.background,
+      resume: Boolean(options.resume),
+      sessionId: options["session-id"],
+      forkSession: Boolean(options["fork-session"]),
+      model: options.model,
+      effort: options.effort,
+      maxBudgetUsd: options["max-budget-usd"],
+      permissionMode: options["permission-mode"]
+    });
+    output(asJson ? response : response.rendered, asJson);
+    return;
+  }
+  if (command === "status") {
+    const jobs = statusCommand({ cwd, all: options.all });
+    output(asJson ? jobs : renderStatus(jobs), asJson);
+    return;
+  }
+  if (command === "result") {
+    const response = resultCommand({ cwd, jobId: options["job-id"] ?? positionals[0] });
+    output(asJson ? response : renderStoredResult(response.job, response.stored), asJson);
+    return;
+  }
+  if (command === "cancel") {
+    const response = cancelCommand({ cwd, jobId: options["job-id"] ?? positionals[0] });
+    output(asJson ? response : `Cancelled ${response.id}.\n`, asJson);
+    return;
+  }
+
+  throw new Error("Usage: claude-companion.mjs setup|review|adversarial-review|rescue|status|result|cancel");
+}
+
+if (isDirectRun()) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}