@indianaprado/claude-code-companion 0.1.0

package/scripts/lib/render.mjs

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+
+function elapsed(job) {
+  const start = Date.parse(job.startedAt ?? job.createdAt ?? "");
+  const end = Date.parse(job.completedAt ?? new Date().toISOString());
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    return "";
+  }
+  const seconds = Math.max(0, Math.round((end - start) / 1000));
+  return `${seconds}s`;
+}
+
+export function renderSetup(report) {
+  return [
+    "# Claude Code Companion Setup",
+    "",
+    `Node: ${report.node.available ? "available" : "missing"} ${report.node.stdout || report.node.detail || ""}`.trim(),
+    `Claude CLI: ${report.claude.available ? "available" : "missing"} ${report.claude.stdout || report.claude.detail || ""}`.trim(),
+    `Claude auth: ${
+      report.auth.parsed?.loggedIn
+        ? "logged in"
+        : report.auth.parsed?.loggedIn === false
+          ? "not logged in"
+          : "unknown; auth probe timed out or returned no JSON"
+    }`,
+    `State directory: ${report.stateDir}`,
+    "",
+    report.ready
+      ? "Ready. If auth is shown as unknown, run a tiny `claude -p` command to confirm the CLI can use your logged-in session."
+      : "Not ready. Run `claude auth login` if auth is missing, then retry."
+  ].join("\n") + "\n";
+}
+
+export function renderTaskResult(job, result) {
+  const lines = [
+    `# ${job.title}`,
+    "",
+    `Job: ${job.id}`,
+    `Status: ${result.status === 0 ? "completed" : "failed"}`,
+    `Mode: ${job.readOnly ? "read-only" : "write-capable"}`,
+    result.sessionId ? `Claude session: ${result.sessionId}` : "",
+    result.costUsd != null ? `Cost: $${result.costUsd}` : "",
+    "",
+    result.finalText || "(Claude returned no final text.)"
+  ].filter(Boolean);
+  if (result.stderr?.trim()) {
+    lines.push("", "## stderr", "", result.stderr.trim());
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function renderQueued(job) {
+  return `${job.title} started in the background as ${job.id}. Use \`status\` or \`result\` with this job id.\n`;
+}
+
+export function renderStatus(jobs) {
+  if (jobs.length === 0) {
+    return "No Claude jobs found for this workspace.\n";
+  }
+  const rows = ["| Job | Kind | Status | Phase | Mode | Elapsed | Summary |", "| --- | --- | --- | --- | --- | --- | --- |"];
+  for (const job of jobs) {
+    rows.push(
+      `| ${job.id} | ${job.kind ?? ""} | ${job.status ?? ""} | ${job.phase ?? ""} | ${job.readOnly ? "read-only" : "write"} | ${elapsed(job)} | ${(job.summary ?? "").replaceAll("|", "\\|")} |`
+    );
+  }
+  return `${rows.join("\n")}\n`;
+}
+
+export function renderStoredResult(job, stored) {
+  if (!job || !stored) {
+    return "No stored Claude result found.\n";
+  }
+  if (stored.rendered) {
+    return stored.rendered;
+  }
+  let log = "";
+  if (stored.logFile && fs.existsSync(stored.logFile)) {
+    log = fs.readFileSync(stored.logFile, "utf8");
+  }
+  return [`# ${stored.title ?? "Claude Job"}`, "", `Job: ${stored.id}`, `Status: ${stored.status}`, "", log || "(No output stored.)"].join("\n") + "\n";
+}

package/scripts/lib/state.mjs

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const STATE_VERSION = 1;
+const MAX_JOBS = 50;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export function resolveWorkspaceRoot(cwd) {
+  let current = path.resolve(cwd ?? process.cwd());
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(cwd ?? process.cwd());
+    }
+    current = parent;
+  }
+}
+
+function stateRoot() {
+  return (
+    process.env.CLAUDE_CODE_COMPANION_DATA ||
+    process.env.CODEX_PLUGIN_DATA ||
+    process.env.PLUGIN_DATA ||
+    path.join(os.tmpdir(), "claude-code-companion")
+  );
+}
+
+export function resolveStateDir(cwd) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  let canonical = workspaceRoot;
+  try {
+    canonical = fs.realpathSync.native(workspaceRoot);
+  } catch {
+    canonical = workspaceRoot;
+  }
+  const slug = (path.basename(workspaceRoot) || "workspace")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "workspace";
+  const hash = createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+  return path.join(stateRoot(), `${slug}-${hash}`);
+}
+
+export function resolveStateFile(cwd) {
+  return path.join(resolveStateDir(cwd), "state.json");
+}
+
+export function resolveJobsDir(cwd) {
+  return path.join(resolveStateDir(cwd), "jobs");
+}
+
+export function ensureStateDir(cwd) {
+  fs.mkdirSync(resolveJobsDir(cwd), { recursive: true });
+}
+
+function defaultState() {
+  return { version: STATE_VERSION, jobs: [] };
+}
+
+export function loadState(cwd) {
+  const file = resolveStateFile(cwd);
+  if (!fs.existsSync(file)) {
+    return defaultState();
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return {
+      ...defaultState(),
+      ...parsed,
+      jobs: Array.isArray(parsed.jobs) ? parsed.jobs : []
+    };
+  } catch {
+    return defaultState();
+  }
+}
+
+export function saveState(cwd, state) {
+  ensureStateDir(cwd);
+  const jobs = [...(state.jobs ?? [])]
+    .sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")))
+    .slice(0, MAX_JOBS);
+  const nextState = { version: STATE_VERSION, jobs };
+  fs.writeFileSync(resolveStateFile(cwd), `${JSON.stringify(nextState, null, 2)}\n`, "utf8");
+  return nextState;
+}
+
+export function updateState(cwd, mutate) {
+  const state = loadState(cwd);
+  mutate(state);
+  return saveState(cwd, state);
+}
+
+export function generateJobId(prefix = "job") {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function upsertJob(cwd, patch) {
+  const timestamp = nowIso();
+  return updateState(cwd, (state) => {
+    const index = state.jobs.findIndex((job) => job.id === patch.id);
+    if (index === -1) {
+      state.jobs.unshift({ createdAt: timestamp, updatedAt: timestamp, ...patch });
+      return;
+    }
+    state.jobs[index] = { ...state.jobs[index], ...patch, updatedAt: timestamp };
+  });
+}
+
+export function listJobs(cwd) {
+  return loadState(cwd).jobs;
+}
+
+export function resolveJobFile(cwd, jobId) {
+  ensureStateDir(cwd);
+  return path.join(resolveJobsDir(cwd), `${jobId}.json`);
+}
+
+export function resolveJobLogFile(cwd, jobId) {
+  ensureStateDir(cwd);
+  return path.join(resolveJobsDir(cwd), `${jobId}.log`);
+}
+
+export function readJob(cwd, jobId) {
+  const file = resolveJobFile(cwd, jobId);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function writeJob(cwd, jobId, payload) {
+  ensureStateDir(cwd);
+  fs.writeFileSync(resolveJobFile(cwd, jobId), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+export function appendLog(logFile, message) {
+  const text = String(message ?? "");
+  if (!logFile || !text) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(logFile), { recursive: true });
+  fs.appendFileSync(logFile, text, "utf8");
+}
+
+export function now() {
+  return nowIso();
+}

package/skills/claude-code-runtime/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: claude-code-runtime
+description: Use when Codex should delegate a review, diagnosis, implementation task, or background job to Claude Code through the local Claude Code Companion MCP server.
+---
+
+# Claude Code Runtime
+
+Use the `claude-code-companion` MCP tools as a thin runtime bridge to the installed `claude` CLI.
+
+## Tools
+
+- `setup`: Check whether Node and Claude Code CLI are available and whether Claude auth appears usable.
+- `review`: Run a read-only Claude review over the current git state.
+- `adversarial_review`: Run a read-only Claude critique with custom focus text.
+- `rescue`: Delegate an arbitrary task to Claude Code. Use `readOnly: true` for investigation-only work; otherwise it is write-capable.
+- `status`: Show active and recent Claude jobs.
+- `result`: Show stored output for a completed job.
+- `cancel`: Terminate an active background job.
+
+## Operating Rules
+
+- Keep delegation fluid. Do not impose frontend/backend ownership policy unless the user asks for it.
+- Use `background: true` for open-ended or long-running Claude work; use `status` and `result` later.
+- Use read-only review tools when the user asks for critique, planning, diagnosis, or a second opinion without edits.
+- Use write-capable `rescue` when the user explicitly wants Claude to implement or fix something.
+- Omit `model` when the user wants Claude CLI's current default/latest model. Pass `model` only when the user asks for a specific alias or full model name.
+- Claude runs in the same checkout. Do not assume worktree isolation.
+- Preserve the user's task text. Add only minimal context needed to make the delegation clear.