@indianaprado/claude-code-companion 0.1.0

package/scripts/claude-mcp-server.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+import {
+  cancelCommand,
+  rescueCommand,
+  resultCommand,
+  reviewCommand,
+  setupCommand,
+  statusCommand
+} from "./claude-companion.mjs";
+import { renderSetup, renderStatus, renderStoredResult } from "./lib/render.mjs";
+
+const PROTOCOL_VERSION = "2024-11-05";
+
+const tools = [
+  {
+    name: "setup",
+    description: "Check local Claude Code CLI availability, auth status, and companion state directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string", description: "Workspace directory. Defaults to the MCP server cwd." }
+      }
+    }
+  },
+  {
+    name: "review",
+    description: "Run a read-only Claude Code review over the current git state.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        scope: { type: "string", enum: ["working-tree", "branch"], default: "working-tree" },
+        base: { type: "string", description: "Base ref when scope is branch." },
+        background: { type: "boolean", default: false },
+        model: { type: "string", description: "Optional Claude model alias or full model name. Omit to let Claude CLI choose its current default/latest model." },
+        effort: { type: "string", enum: ["low", "medium", "high", "xhigh", "max"] },
+        maxBudgetUsd: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "adversarial_review",
+    description: "Run a read-only Claude Code review with explicit critique/focus text.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        focus: { type: "string", description: "Additional review framing or critique focus." },
+        scope: { type: "string", enum: ["working-tree", "branch"], default: "working-tree" },
+        base: { type: "string" },
+        background: { type: "boolean", default: false },
+        model: { type: "string", description: "Optional Claude model alias or full model name. Omit to let Claude CLI choose its current default/latest model." },
+        effort: { type: "string", enum: ["low", "medium", "high", "xhigh", "max"] },
+        maxBudgetUsd: { type: "number" }
+      },
+      required: ["focus"]
+    }
+  },
+  {
+    name: "rescue",
+    description: "Delegate an arbitrary task to Claude Code. Defaults to write-capable unless readOnly is true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        prompt: { type: "string" },
+        readOnly: { type: "boolean", default: false },
+        background: { type: "boolean", default: false },
+        resume: { type: "boolean", default: false },
+        sessionId: { type: "string", description: "With resume=true, resume this Claude session id. With resume=false, create/use this exact new session id." },
+        forkSession: { type: "boolean", default: false, description: "Pass through Claude CLI --fork-session when resuming. Behavior depends on the installed Claude CLI." },
+        model: { type: "string", description: "Optional Claude model alias or full model name. Omit to let Claude CLI choose its current default/latest model." },
+        effort: { type: "string", enum: ["low", "medium", "high", "xhigh", "max"] },
+        maxBudgetUsd: { type: "number" },
+        permissionMode: { type: "string", enum: ["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"] }
+      },
+      required: ["prompt"]
+    }
+  },
+  {
+    name: "status",
+    description: "List active and recent Claude Code companion jobs for this workspace.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        all: { type: "boolean", default: false }
+      }
+    }
+  },
+  {
+    name: "result",
+    description: "Show stored output for a completed Claude Code companion job.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        jobId: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "cancel",
+    description: "Cancel an active background Claude Code companion job.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        jobId: { type: "string" }
+      }
+    }
+  }
+];
+
+let buffer = Buffer.alloc(0);
+let transportMode = null;
+
+function encodeMessage(message) {
+  const body = Buffer.from(JSON.stringify(message), "utf8");
+  return Buffer.concat([
+    Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "utf8"),
+    body
+  ]);
+}
+
+function send(message) {
+  if (transportMode === "line") {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+    return;
+  }
+  process.stdout.write(encodeMessage(message));
+}
+
+function textResult(text) {
+  return { content: [{ type: "text", text: String(text ?? "") }] };
+}
+
+function errorResult(message) {
+  return { content: [{ type: "text", text: String(message ?? "") }], isError: true };
+}
+
+function tryReadMessage() {
+  const firstNonWhitespace = buffer.findIndex((byte) => byte !== 0x20 && byte !== 0x09 && byte !== 0x0d && byte !== 0x0a);
+  if (firstNonWhitespace > 0) {
+    buffer = buffer.slice(firstNonWhitespace);
+  }
+  if (buffer.length === 0) {
+    return null;
+  }
+
+  if (buffer[0] === 0x7b || transportMode === "line") {
+    const newline = buffer.indexOf("\n");
+    if (newline === -1) {
+      return null;
+    }
+    const line = buffer.slice(0, newline).toString("utf8").trim();
+    buffer = buffer.slice(newline + 1);
+    if (!line) {
+      return tryReadMessage();
+    }
+    transportMode = "line";
+    return JSON.parse(line);
+  }
+
+  const separator = buffer.indexOf("\r\n\r\n");
+  if (separator === -1) {
+    return null;
+  }
+  const header = buffer.slice(0, separator).toString("utf8");
+  const match = /Content-Length:\s*(\d+)/i.exec(header);
+  if (!match) {
+    buffer = buffer.slice(separator + 4);
+    return null;
+  }
+  transportMode = "header";
+  const length = Number(match[1]);
+  const start = separator + 4;
+  const end = start + length;
+  if (buffer.length < end) {
+    return null;
+  }
+  const body = buffer.slice(start, end).toString("utf8");
+  buffer = buffer.slice(end);
+  return JSON.parse(body);
+}
+
+async function callTool(name, args = {}) {
+  if (name === "setup") {
+    return textResult(renderSetup(await setupCommand(args)));
+  }
+  if (name === "review") {
+    const response = await reviewCommand(args);
+    return textResult(response.rendered);
+  }
+  if (name === "adversarial_review") {
+    const response = await reviewCommand({ ...args, adversarial: true });
+    return textResult(response.rendered);
+  }
+  if (name === "rescue") {
+    const response = await rescueCommand(args);
+    return textResult(response.rendered);
+  }
+  if (name === "status") {
+    return textResult(renderStatus(statusCommand(args)));
+  }
+  if (name === "result") {
+    const response = resultCommand(args);
+    return textResult(renderStoredResult(response.job, response.stored));
+  }
+  if (name === "cancel") {
+    const response = cancelCommand(args);
+    return textResult(`Cancelled ${response.id}.\n`);
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+async function handle(message) {
+  if (message.id === undefined) {
+    return;
+  }
+  try {
+    if (message.method === "initialize") {
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: "claude-code-companion", version: "0.1.0" }
+        }
+      });
+      return;
+    }
+    if (message.method === "tools/list") {
+      send({ jsonrpc: "2.0", id: message.id, result: { tools } });
+      return;
+    }
+    if (message.method === "tools/call") {
+      const result = await callTool(message.params?.name, message.params?.arguments ?? {});
+      send({ jsonrpc: "2.0", id: message.id, result });
+      return;
+    }
+    if (message.method === "ping") {
+      send({ jsonrpc: "2.0", id: message.id, result: {} });
+      return;
+    }
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32601, message: `Method not found: ${message.method}` }
+    });
+  } catch (error) {
+    if (message.method === "tools/call") {
+      send({ jsonrpc: "2.0", id: message.id, result: errorResult(error instanceof Error ? error.message : String(error)) });
+      return;
+    }
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32000, message: error instanceof Error ? error.message : String(error) }
+    });
+  }
+}
+
+process.stdin.on("data", async (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const message = tryReadMessage();
+    if (!message) {
+      break;
+    }
+    await handle(message);
+  }
+});

package/scripts/lib/args.mjs

@@ -0,0 +1,55 @@
+export function parseArgs(argv, config = {}) {
+  const valueOptions = new Set(config.valueOptions ?? []);
+  const booleanOptions = new Set(config.booleanOptions ?? []);
+  const aliasMap = config.aliasMap ?? {};
+  const options = {};
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    if (raw === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!raw.startsWith("-") || raw === "-") {
+      positionals.push(raw);
+      continue;
+    }
+
+    const withoutPrefix = raw.replace(/^-+/, "");
+    const equalsIndex = withoutPrefix.indexOf("=");
+    const keyRaw = equalsIndex === -1 ? withoutPrefix : withoutPrefix.slice(0, equalsIndex);
+    const key = aliasMap[keyRaw] ?? keyRaw;
+    const inlineValue = equalsIndex === -1 ? null : withoutPrefix.slice(equalsIndex + 1);
+
+    if (booleanOptions.has(key)) {
+      options[key] = inlineValue == null ? true : inlineValue !== "false";
+      continue;
+    }
+
+    if (valueOptions.has(key)) {
+      if (inlineValue != null) {
+        options[key] = inlineValue;
+        continue;
+      }
+      index += 1;
+      if (index >= argv.length) {
+        throw new Error(`Missing value for --${key}.`);
+      }
+      options[key] = argv[index];
+      continue;
+    }
+
+    if (inlineValue != null) {
+      options[key] = inlineValue;
+    } else {
+      options[key] = true;
+    }
+  }
+
+  return { options, positionals };
+}
+
+export function stringArg(value, fallback = "") {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}

package/scripts/lib/claude.mjs

@@ -0,0 +1,106 @@
+import { binaryStatus, spawnCapture } from "./process.mjs";
+
+const READ_ONLY_TOOLS = "Read,Glob,Grep,Bash(git *)";
+const EDIT_TOOLS = "Edit,MultiEdit,Write,NotebookEdit";
+
+export function getClaudeVersion(cwd) {
+  return binaryStatus("claude", ["--version"], { cwd });
+}
+
+export function getClaudeAuthStatus(cwd) {
+  const result = binaryStatus("claude", ["auth", "status"], { cwd, timeoutMs: 8000 });
+  let parsed = null;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    parsed = null;
+  }
+  return {
+    available: result.available || Boolean(result.stdout),
+    timedOut: result.detail?.includes("ETIMEDOUT") || result.signal === "SIGTERM",
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    detail: result.detail,
+    parsed
+  };
+}
+
+function normalizeEffort(effort) {
+  if (!effort) {
+    return null;
+  }
+  const value = String(effort).trim();
+  const allowed = new Set(["low", "medium", "high", "xhigh", "max"]);
+  if (!allowed.has(value)) {
+    throw new Error(`Unsupported Claude effort "${effort}". Use low, medium, high, xhigh, or max.`);
+  }
+  return value;
+}
+
+function parseClaudeJson(stdout) {
+  const text = String(stdout ?? "").trim();
+  if (!text) {
+    return { parsed: null, finalText: "" };
+  }
+  try {
+    const parsed = JSON.parse(text);
+    const finalText =
+      parsed.result ??
+      parsed.response ??
+      parsed.message?.content?.map?.((part) => part.text ?? "").join("\n") ??
+      parsed.content?.map?.((part) => part.text ?? "").join("\n") ??
+      text;
+    return { parsed, finalText: String(finalText ?? "").trim() };
+  } catch {
+    return { parsed: null, finalText: text };
+  }
+}
+
+export async function runClaude(prompt, options = {}) {
+  const args = ["-p", prompt, "--output-format", "json"];
+  if (options.resume) {
+    if (options.sessionId) {
+      args.push("--resume", options.sessionId);
+    } else {
+      args.push("--continue");
+    }
+    if (options.forkSession) {
+      args.push("--fork-session");
+    }
+  } else if (options.sessionId) {
+    args.push("--session-id", options.sessionId);
+  }
+  if (options.model) {
+    args.push("--model", options.model);
+  }
+  const effort = normalizeEffort(options.effort);
+  if (effort) {
+    args.push("--effort", effort);
+  }
+  if (options.maxBudgetUsd) {
+    args.push("--max-budget-usd", String(options.maxBudgetUsd));
+  }
+  if (options.readOnly) {
+    args.push("--permission-mode", "plan");
+    args.push("--allowedTools", READ_ONLY_TOOLS);
+    args.push("--disallowedTools", EDIT_TOOLS);
+  } else {
+    args.push("--permission-mode", options.permissionMode || "acceptEdits");
+  }
+
+  const result = await spawnCapture("claude", args, {
+    cwd: options.cwd,
+    onStart: options.onStart,
+    onStdout: options.onStdout,
+    onStderr: options.onStderr
+  });
+  const parsed = parseClaudeJson(result.stdout);
+  return {
+    ...result,
+    parsed: parsed.parsed,
+    finalText: parsed.finalText,
+    sessionId: parsed.parsed?.session_id ?? parsed.parsed?.sessionId ?? null,
+    costUsd: parsed.parsed?.total_cost_usd ?? parsed.parsed?.cost_usd ?? null
+  };
+}

package/scripts/lib/git.mjs

@@ -0,0 +1,52 @@
+import { spawnSync } from "node:child_process";
+
+function runGit(cwd, args) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 10000 });
+  return {
+    ok: result.status === 0,
+    stdout: String(result.stdout ?? "").trim(),
+    stderr: String(result.stderr ?? "").trim()
+  };
+}
+
+export function gitAvailable(cwd) {
+  return runGit(cwd, ["rev-parse", "--is-inside-work-tree"]).ok;
+}
+
+export function collectGitContext(cwd, options = {}) {
+  if (!gitAvailable(cwd)) {
+    return {
+      available: false,
+      label: "workspace files",
+      content: "This directory is not inside a git repository. Review the workspace directly."
+    };
+  }
+
+  const status = runGit(cwd, ["status", "--short", "--untracked-files=all"]).stdout;
+  const branch = runGit(cwd, ["branch", "--show-current"]).stdout || "detached";
+  const scope = options.scope ?? "working-tree";
+  const base = options.base ?? "";
+  let diff = "";
+  let label = "working tree";
+
+  if (scope === "branch" && base) {
+    diff = runGit(cwd, ["diff", `${base}...HEAD`]).stdout;
+    label = `branch diff against ${base}`;
+  } else {
+    const staged = runGit(cwd, ["diff", "--cached"]).stdout;
+    const unstaged = runGit(cwd, ["diff"]).stdout;
+    diff = [staged && "Staged diff:\n" + staged, unstaged && "Unstaged diff:\n" + unstaged]
+      .filter(Boolean)
+      .join("\n\n");
+  }
+
+  return {
+    available: true,
+    label,
+    content: [
+      `Branch: ${branch}`,
+      `Status:\n${status || "(clean)"}`,
+      `Diff:\n${diff || "(no tracked diff; inspect untracked files listed in status if relevant)"}`
+    ].join("\n\n")
+  };
+}

package/scripts/lib/jobs.mjs

@@ -0,0 +1,67 @@
+import { appendLog, generateJobId, listJobs, now, readJob, resolveJobLogFile, upsertJob, writeJob } from "./state.mjs";
+import { spawnDetached, terminateProcessTree } from "./process.mjs";
+
+export function createJob(cwd, values) {
+  const id = generateJobId(values.prefix ?? "claude");
+  const logFile = resolveJobLogFile(cwd, id);
+  const job = {
+    id,
+    kind: values.kind ?? "task",
+    title: values.title ?? "Claude Task",
+    summary: values.summary ?? "",
+    cwd,
+    status: "queued",
+    phase: "queued",
+    pid: null,
+    logFile,
+    readOnly: Boolean(values.readOnly),
+    background: Boolean(values.background),
+    createdAt: now()
+  };
+  writeJob(cwd, id, job);
+  upsertJob(cwd, job);
+  appendLog(logFile, `[${now()}] Queued ${job.title}.\n`);
+  return job;
+}
+
+export function markJob(cwd, jobId, patch) {
+  const existing = readJob(cwd, jobId) ?? { id: jobId, cwd };
+  const next = { ...existing, ...patch, updatedAt: now() };
+  writeJob(cwd, jobId, next);
+  upsertJob(cwd, next);
+  return next;
+}
+
+export function recentJobs(cwd, includeAll = false) {
+  const jobs = listJobs(cwd);
+  return includeAll ? jobs : jobs.slice(0, 10);
+}
+
+export function findJob(cwd, reference = "") {
+  const jobs = listJobs(cwd);
+  if (!reference) {
+    return jobs[0] ?? null;
+  }
+  return jobs.find((job) => job.id === reference || job.id.startsWith(reference)) ?? null;
+}
+
+export function launchWorker(scriptPath, cwd, jobId) {
+  return spawnDetached(process.execPath, [scriptPath, "worker", "--cwd", cwd, "--job-id", jobId], { cwd });
+}
+
+export function cancelJob(cwd, reference = "") {
+  const job = findJob(cwd, reference);
+  if (!job) {
+    throw new Error(reference ? `No Claude job found for ${reference}.` : "No Claude job found.");
+  }
+  const killed = terminateProcessTree(job.pid);
+  const next = markJob(cwd, job.id, {
+    status: "cancelled",
+    phase: "cancelled",
+    pid: null,
+    completedAt: now(),
+    errorMessage: "Cancelled by user."
+  });
+  appendLog(job.logFile, `[${now()}] Cancel requested. killed=${killed}\n`);
+  return next;
+}

package/scripts/lib/process.mjs

@@ -0,0 +1,74 @@
+import { spawn, spawnSync } from "node:child_process";
+
+export function binaryStatus(binary, args = ["--version"], options = {}) {
+  const result = spawnSync(binary, args, {
+    cwd: options.cwd ?? process.cwd(),
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? 5000
+  });
+  return {
+    available: !result.error && result.status === 0,
+    status: result.status,
+    stdout: String(result.stdout ?? "").trim(),
+    stderr: String(result.stderr ?? "").trim(),
+    detail: result.error ? result.error.message : null
+  };
+}
+
+export function spawnCapture(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+      options.onStdout?.(chunk.toString(), child.pid);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+      options.onStderr?.(chunk.toString(), child.pid);
+    });
+    child.on("error", (error) => {
+      resolve({ status: 1, stdout, stderr, error });
+    });
+    child.on("close", (status, signal) => {
+      resolve({ status: status ?? 1, signal, stdout, stderr, error: null });
+    });
+    options.onStart?.(child.pid);
+  });
+}
+
+export function spawnDetached(command, args, options = {}) {
+  const child = spawn(command, args, {
+    cwd: options.cwd ?? process.cwd(),
+    env: options.env ?? process.env,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.unref();
+  return child;
+}
+
+export function terminateProcessTree(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isFinite(numericPid) || numericPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(-numericPid, "SIGTERM");
+    return true;
+  } catch {
+    try {
+      process.kill(numericPid, "SIGTERM");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/scripts/lib/prompts.mjs

@@ -0,0 +1,25 @@
+import { collectGitContext } from "./git.mjs";
+
+export function buildReviewPrompt(cwd, options = {}) {
+  const context = collectGitContext(cwd, options);
+  return [
+    "You are Claude Code acting as a read-only reviewer for Codex.",
+    "Do not modify files. Do not run commands that write files. Focus on bugs, regressions, UX issues, missing tests, and maintainability risks.",
+    "Return findings first, ordered by severity. Include file paths and line references when you can infer them.",
+    options.focus ? `Additional focus: ${options.focus}` : "",
+    `Review target: ${context.label}`,
+    "Local git context:",
+    context.content
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function buildRescuePrompt(prompt, options = {}) {
+  const mode = options.readOnly
+    ? "Read-only mode: investigate, reason, and report. Do not edit files."
+    : "Write-capable mode: you may edit files in this checkout when needed to satisfy the task.";
+  return [mode, "You are Claude Code being called by Codex as a companion agent.", "Task:", prompt]
+    .filter(Boolean)
+    .join("\n\n");
+}