@tonyclaw/agent-inspector 2.0.38 → 2.0.40

package/src/cli/onboard.ts

@@ -36,6 +36,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const DEFAULT_PORT = 25947;
+const DEFAULT_MCP_URL = `http://localhost:${DEFAULT_PORT}/api/mcp`;
 const SKILL_DIR_NAME = "agent-inspector-onboard";
 const SKILL_FILE_NAME = "SKILL.md";
 // Windows reserves `:` for NTFS alternate data streams, so a file named
@@ -57,6 +58,11 @@ export type OnboardFlags = {
   skipToolWire: boolean;
   codexOnly: boolean;
   skipCodexSkill: boolean;
+  opencode: boolean;
+  opencodeOnly: boolean;
+  opencodeConfig: string | null;
+  opencodeTransport: OpenCodeTransport;
+  opencodeMcpUrl: string;
   uninstall: boolean;
   status: boolean;
   json: boolean;
@@ -64,6 +70,40 @@ export type OnboardFlags = {
   codexSkillDir: string | null;
 };
 
+type OpenCodeTransport = "local" | "remote";
+type OpenCodeStatusTransport = OpenCodeTransport | "unknown";
+type OpenCodeConfigState = "missing" | "configured" | "custom" | "disabled" | "invalid";
+
+type OpenCodeConfigStatus = {
+  label: "OpenCode MCP config";
+  path: string;
+  state: OpenCodeConfigState;
+  transport: OpenCodeStatusTransport;
+  endpoint: string;
+  action: string;
+  detail: string;
+};
+
+type OpenCodeConfigPlan = {
+  status: OpenCodeConfigStatus;
+  body: string | null;
+  shouldWrite: boolean;
+  shouldRemove: boolean;
+  blockedMessage: string | null;
+};
+
+type OpenCodeReadResult =
+  | {
+      ok: true;
+      exists: boolean;
+      config: Record<string, unknown>;
+    }
+  | {
+      ok: false;
+      exists: boolean;
+      message: string;
+    };
+
 type OnboardTargets = {
   claudeSkillFile: string;
   claudeCommandFile: string;
@@ -126,6 +166,11 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
     skipToolWire: false,
     codexOnly: false,
     skipCodexSkill: false,
+    opencode: false,
+    opencodeOnly: false,
+    opencodeConfig: null,
+    opencodeTransport: "local",
+    opencodeMcpUrl: DEFAULT_MCP_URL,
     uninstall: false,
     status: false,
     json: false,
@@ -155,6 +200,57 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
       case "--skip-codex-skill":
         flags.skipCodexSkill = true;
         break;
+      case "--opencode":
+        flags.opencode = true;
+        break;
+      case "--opencode-only":
+        flags.opencode = true;
+        flags.opencodeOnly = true;
+        break;
+      case "--opencode-config": {
+        const next = argv[i + 1];
+        if (next === undefined) {
+          process.stderr.write(
+            "agent-inspector onboard: --opencode-config requires a path argument\n",
+          );
+          process.exit(2);
+        }
+        flags.opencodeConfig = next;
+        i++;
+        break;
+      }
+      case "--opencode-transport": {
+        const next = argv[i + 1];
+        if (next === undefined) {
+          process.stderr.write(
+            "agent-inspector onboard: --opencode-transport requires local or remote\n",
+          );
+          process.exit(2);
+        }
+        switch (next) {
+          case "local":
+          case "remote":
+            flags.opencodeTransport = next;
+            break;
+          default:
+            process.stderr.write(
+              `agent-inspector onboard: invalid --opencode-transport: ${next}\n`,
+            );
+            process.exit(2);
+        }
+        i++;
+        break;
+      }
+      case "--opencode-mcp-url": {
+        const next = argv[i + 1];
+        if (next === undefined) {
+          process.stderr.write("agent-inspector onboard: --opencode-mcp-url requires a URL\n");
+          process.exit(2);
+        }
+        flags.opencodeMcpUrl = next;
+        i++;
+        break;
+      }
       case "--uninstall":
         flags.uninstall = true;
         break;
@@ -212,6 +308,12 @@ Options:
   --skip-tool-wire         Skip the wire-tool phase in the Claude skill body
   --skip-codex-skill       Install only the Claude Code skill and slash command
   --codex-only             Install only the Codex skill
+  --opencode               Also configure OpenCode MCP in opencode.json/jsonc
+  --opencode-only          Configure only OpenCode MCP
+  --opencode-config <path> Override OpenCode config path (default: ~/.config/opencode/opencode.json)
+  --opencode-transport <local|remote>
+                           OpenCode MCP transport to write (default: local)
+  --opencode-mcp-url <url> Agent Inspector MCP endpoint for OpenCode
   --uninstall              Remove generated files whose version matches this package
   --status                 Show installed onboarding file versions and suggested action
   --json                   Emit machine-readable JSON with --status
@@ -243,6 +345,429 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
+function isOpenCodeEnabled(flags: OnboardFlags): boolean {
+  return flags.opencode || flags.opencodeOnly;
+}
+
+function resolveOpenCodeConfigPath(flags: OnboardFlags): string {
+  if (flags.opencodeConfig !== null) {
+    return flags.opencodeConfig;
+  }
+
+  const configDir = join(homedir(), ".config", "opencode");
+  const jsoncPath = join(configDir, "opencode.jsonc");
+  if (existsSync(jsoncPath)) {
+    return jsoncPath;
+  }
+  return join(configDir, "opencode.json");
+}
+
+function stripJsoncComments(raw: string): string {
+  let result = "";
+  let index = 0;
+  let inString = false;
+  let stringChar = "";
+
+  while (index < raw.length) {
+    const ch = raw[index];
+    const next = raw[index + 1];
+
+    if (inString) {
+      if (ch === "\\" && next !== undefined) {
+        result += ch + next;
+        index += 2;
+        continue;
+      }
+      if (ch === stringChar) {
+        inString = false;
+        stringChar = "";
+      }
+      result += ch;
+      index += 1;
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      result += ch;
+      index += 1;
+      continue;
+    }
+
+    if (ch === "/" && next === "/") {
+      while (index < raw.length && raw[index] !== "\n") {
+        index += 1;
+      }
+      continue;
+    }
+
+    if (ch === "/" && next === "*") {
+      index += 2;
+      while (index < raw.length - 1 && !(raw[index] === "*" && raw[index + 1] === "/")) {
+        index += 1;
+      }
+      index += 2;
+      continue;
+    }
+
+    result += ch;
+    index += 1;
+  }
+
+  return result;
+}
+
+function readOpenCodeConfig(path: string): OpenCodeReadResult {
+  if (!existsSync(path)) {
+    return { ok: true, exists: false, config: {} };
+  }
+
+  try {
+    const raw = readFileSync(path, "utf8");
+    if (raw.trim().length === 0) {
+      return { ok: true, exists: true, config: {} };
+    }
+    const parsed: unknown = JSON.parse(stripJsoncComments(raw));
+    if (isObject(parsed)) {
+      return { ok: true, exists: true, config: parsed };
+    }
+    return {
+      ok: false,
+      exists: true,
+      message: "OpenCode config root must be a JSON object",
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      exists: true,
+      message,
+    };
+  }
+}
+
+function buildOpenCodeMcpEntry(
+  transport: OpenCodeTransport,
+  endpoint: string,
+): Record<string, unknown> {
+  switch (transport) {
+    case "local":
+      return {
+        type: "local",
+        command: ["agent-inspector-mcp", "stdio", "--url", endpoint],
+        enabled: true,
+      };
+    case "remote":
+      return {
+        type: "remote",
+        url: endpoint,
+        enabled: true,
+      };
+    default:
+      return {
+        type: "local",
+        command: ["agent-inspector-mcp", "stdio", "--url", endpoint],
+        enabled: true,
+      };
+  }
+}
+
+function stringArrayEquals(value: unknown, expected: readonly string[]): boolean {
+  if (!Array.isArray(value) || value.length !== expected.length) {
+    return false;
+  }
+
+  return value.every((item, index) => item === expected[index]);
+}
+
+function isOpenCodeLocalEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  const enabled = value["enabled"];
+  if (!ignoreEnabled && enabled === false) {
+    return false;
+  }
+
+  const env = value["environment"];
+  const usesUrlArg = stringArrayEquals(value["command"], [
+    "agent-inspector-mcp",
+    "stdio",
+    "--url",
+    endpoint,
+  ]);
+  const usesEnv =
+    stringArrayEquals(value["command"], ["agent-inspector-mcp", "stdio"]) &&
+    isObject(env) &&
+    env["AGENT_INSPECTOR_MCP_URL"] === endpoint;
+
+  return value["type"] === "local" && (usesUrlArg || usesEnv);
+}
+
+function isOpenCodeRemoteEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  const enabled = value["enabled"];
+  if (!ignoreEnabled && enabled === false) {
+    return false;
+  }
+
+  return value["type"] === "remote" && value["url"] === endpoint;
+}
+
+function isKnownOpenCodeEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {
+  return (
+    isOpenCodeLocalEntry(value, endpoint, ignoreEnabled) ||
+    isOpenCodeRemoteEntry(value, endpoint, ignoreEnabled)
+  );
+}
+
+function detectOpenCodeTransport(value: unknown): OpenCodeStatusTransport {
+  if (!isObject(value)) {
+    return "unknown";
+  }
+
+  switch (value["type"]) {
+    case "local":
+      return "local";
+    case "remote":
+      return "remote";
+    default:
+      return "unknown";
+  }
+}
+
+function openCodeActionForStatus(status: OpenCodeConfigStatus): string {
+  switch (status.state) {
+    case "missing":
+      return "agent-inspector onboard --opencode-only";
+    case "configured":
+      return "opencode mcp list";
+    case "disabled":
+    case "custom":
+      return "agent-inspector onboard --opencode-only --force";
+    case "invalid":
+      return "fix OpenCode JSON/JSONC, then rerun agent-inspector onboard --opencode-only";
+    default:
+      return "agent-inspector onboard --opencode-only";
+  }
+}
+
+function makeOpenCodeStatus(
+  path: string,
+  state: OpenCodeConfigState,
+  transport: OpenCodeStatusTransport,
+  endpoint: string,
+  detail: string,
+): OpenCodeConfigStatus {
+  const status: OpenCodeConfigStatus = {
+    label: "OpenCode MCP config",
+    path,
+    state,
+    transport,
+    endpoint,
+    action: "agent-inspector onboard --opencode-only",
+    detail,
+  };
+
+  return {
+    ...status,
+    action: openCodeActionForStatus(status),
+  };
+}
+
+function getOpenCodeEntry(config: Record<string, unknown>): unknown {
+  const mcp = config["mcp"];
+  if (!isObject(mcp)) {
+    return undefined;
+  }
+  return mcp["agent-inspector"];
+}
+
+function buildOpenCodeConfig(
+  config: Record<string, unknown>,
+  transport: OpenCodeTransport,
+  endpoint: string,
+): Record<string, unknown> {
+  const schema =
+    typeof config["$schema"] === "string" ? config["$schema"] : "https://opencode.ai/config.json";
+  const nextConfig: Record<string, unknown> = {
+    $schema: schema,
+  };
+
+  for (const [key, value] of Object.entries(config)) {
+    if (key !== "$schema" && key !== "mcp") {
+      nextConfig[key] = value;
+    }
+  }
+
+  const currentMcp = config["mcp"];
+  const nextMcp: Record<string, unknown> = isObject(currentMcp) ? { ...currentMcp } : {};
+  nextMcp["agent-inspector"] = buildOpenCodeMcpEntry(transport, endpoint);
+  nextConfig["mcp"] = nextMcp;
+  return nextConfig;
+}
+
+function formatOpenCodeConfig(config: Record<string, unknown>): string {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+function removeOpenCodeEntry(config: Record<string, unknown>): Record<string, unknown> {
+  const nextConfig: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (key !== "mcp") {
+      nextConfig[key] = value;
+    }
+  }
+
+  const currentMcp = config["mcp"];
+  if (!isObject(currentMcp)) {
+    return nextConfig;
+  }
+
+  const nextMcp: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(currentMcp)) {
+    if (key !== "agent-inspector") {
+      nextMcp[key] = value;
+    }
+  }
+
+  if (Object.keys(nextMcp).length > 0) {
+    nextConfig["mcp"] = nextMcp;
+  }
+  return nextConfig;
+}
+
+function readOpenCodeStatus(flags: OnboardFlags): OpenCodeConfigStatus {
+  const path = resolveOpenCodeConfigPath(flags);
+  const read = readOpenCodeConfig(path);
+  if (!read.ok) {
+    return makeOpenCodeStatus(path, "invalid", "unknown", flags.opencodeMcpUrl, read.message);
+  }
+
+  const entry = getOpenCodeEntry(read.config);
+  if (entry === undefined) {
+    const detail = read.exists
+      ? "OpenCode config has no mcp.agent-inspector entry"
+      : "Missing file";
+    return makeOpenCodeStatus(path, "missing", "unknown", flags.opencodeMcpUrl, detail);
+  }
+
+  const transport = detectOpenCodeTransport(entry);
+  if (isObject(entry) && entry["enabled"] === false) {
+    return makeOpenCodeStatus(
+      path,
+      "disabled",
+      transport,
+      flags.opencodeMcpUrl,
+      "mcp.agent-inspector is present but disabled",
+    );
+  }
+
+  if (isKnownOpenCodeEntry(entry, flags.opencodeMcpUrl, false)) {
+    return makeOpenCodeStatus(
+      path,
+      "configured",
+      transport,
+      flags.opencodeMcpUrl,
+      "mcp.agent-inspector points at Agent Inspector MCP",
+    );
+  }
+
+  return makeOpenCodeStatus(
+    path,
+    "custom",
+    transport,
+    flags.opencodeMcpUrl,
+    "mcp.agent-inspector exists but does not match Agent Inspector defaults",
+  );
+}
+
+function buildOpenCodePlan(flags: OnboardFlags): OpenCodeConfigPlan {
+  const path = resolveOpenCodeConfigPath(flags);
+  const read = readOpenCodeConfig(path);
+  if (!read.ok) {
+    return {
+      status: makeOpenCodeStatus(path, "invalid", "unknown", flags.opencodeMcpUrl, read.message),
+      body: null,
+      shouldWrite: false,
+      shouldRemove: false,
+      blockedMessage: `OpenCode config is invalid: ${read.message}`,
+    };
+  }
+
+  const status = readOpenCodeStatus(flags);
+  const entry = getOpenCodeEntry(read.config);
+  const nextBody = formatOpenCodeConfig(
+    buildOpenCodeConfig(read.config, flags.opencodeTransport, flags.opencodeMcpUrl),
+  );
+
+  if (flags.uninstall) {
+    const shouldRemove =
+      entry !== undefined && isKnownOpenCodeEntry(entry, flags.opencodeMcpUrl, true);
+    const removeBody = shouldRemove ? formatOpenCodeConfig(removeOpenCodeEntry(read.config)) : null;
+    return {
+      status,
+      body: removeBody,
+      shouldWrite: false,
+      shouldRemove,
+      blockedMessage: shouldRemove
+        ? null
+        : "OpenCode mcp.agent-inspector is missing or custom; preserved",
+    };
+  }
+
+  switch (status.state) {
+    case "configured":
+      return {
+        status,
+        body: nextBody,
+        shouldWrite: flags.force,
+        shouldRemove: false,
+        blockedMessage: null,
+      };
+    case "missing":
+      return {
+        status,
+        body: nextBody,
+        shouldWrite: true,
+        shouldRemove: false,
+        blockedMessage: null,
+      };
+    case "custom":
+    case "disabled":
+      return {
+        status,
+        body: nextBody,
+        shouldWrite: flags.force,
+        shouldRemove: false,
+        blockedMessage: flags.force
+          ? null
+          : "OpenCode mcp.agent-inspector is custom or disabled; use --force to replace",
+      };
+    case "invalid":
+      return {
+        status,
+        body: null,
+        shouldWrite: false,
+        shouldRemove: false,
+        blockedMessage: "OpenCode config is invalid",
+      };
+    default:
+      return {
+        status,
+        body: null,
+        shouldWrite: false,
+        shouldRemove: false,
+        blockedMessage: "OpenCode config state is unknown",
+      };
+  }
+}
+
 function buildDetectedSummary(): string {
   const entries = detectAll();
   const present = entries.filter((e) => e.result.found);
@@ -448,8 +973,8 @@ function buildPlannedFiles(
   targets: OnboardTargets,
   version: string,
 ): PlannedFile[] {
-  const installClaude = !flags.codexOnly;
-  const installCodex = !flags.skipCodexSkill;
+  const installClaude = !flags.codexOnly && !flags.opencodeOnly;
+  const installCodex = !flags.skipCodexSkill && !flags.opencodeOnly;
   const detectedSummary = installClaude ? buildDetectedSummary() : "";
   const claudeSkillBody = installClaude
     ? renderSkillOnboard({
@@ -525,6 +1050,7 @@ function runUninstall(
   plannedFiles: readonly PlannedFile[],
   currentVersion: string,
   dryRun: boolean,
+  openCodePlan: OpenCodeConfigPlan | null,
 ): number {
   const enabledFiles = plannedFiles.filter((file) => file.enabled);
   const filesToRemove = enabledFiles.filter((file) => shouldUninstall(file, currentVersion));
@@ -535,14 +1061,27 @@ function runUninstall(
       const status = shouldUninstall(file, currentVersion) ? "matching" : "skipped";
       process.stdout.write(`${file.label}: ${file.path} (${status})\n`);
     }
+    if (openCodePlan !== null) {
+      const status = openCodePlan.shouldRemove ? "matching" : "skipped";
+      process.stdout.write(
+        `${openCodePlan.status.label}: ${openCodePlan.status.path} (${status})\n`,
+      );
+      if (openCodePlan.blockedMessage !== null) {
+        process.stdout.write(`  ${openCodePlan.blockedMessage}\n`);
+      }
+    }
     process.stdout.write(`\nNo files were removed.\n`);
     return 0;
   }
 
-  if (filesToRemove.length === 0) {
+  const removeOpenCode = openCodePlan !== null && openCodePlan.shouldRemove;
+  if (filesToRemove.length === 0 && !removeOpenCode) {
     process.stdout.write(
       "agent-inspector onboard: no generated onboarding files match this package version\n",
     );
+    if (openCodePlan !== null && openCodePlan.blockedMessage !== null) {
+      process.stdout.write(`${openCodePlan.blockedMessage}\n`);
+    }
     return 0;
   }
 
@@ -552,6 +1091,11 @@ function runUninstall(
       removeEmptyDirectory(dirname(file.path));
       process.stdout.write(`Removed ${file.label}: ${file.path}\n`);
     }
+    if (openCodePlan !== null && openCodePlan.shouldRemove && openCodePlan.body !== null) {
+      mkdirSync(dirname(openCodePlan.status.path), { recursive: true });
+      writeFileSync(openCodePlan.status.path, openCodePlan.body, "utf8");
+      process.stdout.write(`Removed OpenCode MCP entry from: ${openCodePlan.status.path}\n`);
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`agent-inspector onboard: failed to remove files: ${msg}\n`);
@@ -565,13 +1109,28 @@ function formatStatusVersion(status: GeneratedFileStatus): string {
   return status.version ?? "-";
 }
 
-function summarizeStatusAction(statuses: readonly GeneratedFileStatus[]): string {
+function summarizeStatusAction(
+  statuses: readonly GeneratedFileStatus[],
+  openCodeStatus: OpenCodeConfigStatus | null,
+): string {
   const actionable = statuses.filter(
     (status) => status.state === "missing" || status.state === "outdated",
   );
-  if (actionable.length > 0) {
-    const actions = Array.from(new Set(actionable.map((status) => status.action)));
-    return `Run: ${actions.join(" && ")}`;
+  const actions = actionable.map((status) => status.action);
+  if (openCodeStatus !== null && openCodeStatus.state === "missing") {
+    actions.push(openCodeStatus.action);
+  }
+  if (actions.length > 0) {
+    const uniqueActions = Array.from(new Set(actions));
+    return `Run: ${uniqueActions.join(" && ")}`;
+  }
+  if (
+    openCodeStatus !== null &&
+    (openCodeStatus.state === "custom" ||
+      openCodeStatus.state === "disabled" ||
+      openCodeStatus.state === "invalid")
+  ) {
+    return `OpenCode config needs review: ${openCodeStatus.action}`;
   }
   if (statuses.some((status) => status.state === "custom")) {
     return "Custom files are preserved. Use --force only if you want to replace them.";
@@ -586,10 +1145,11 @@ function runStatus(
   plannedFiles: readonly PlannedFile[],
   currentVersion: string,
   json: boolean,
+  openCodeStatus: OpenCodeConfigStatus | null,
 ): number {
   const enabledFiles = plannedFiles.filter((file) => file.enabled);
   const statuses = enabledFiles.map((file) => readGeneratedFileStatus(file, currentVersion));
-  const summary = summarizeStatusAction(statuses);
+  const summary = summarizeStatusAction(statuses, openCodeStatus);
 
   if (json) {
     process.stdout.write(
@@ -597,6 +1157,7 @@ function runStatus(
         {
           packageVersion: currentVersion,
           files: statuses,
+          opencodeConfig: openCodeStatus,
           suggestedAction: summary,
         },
         null,
@@ -616,6 +1177,15 @@ function runStatus(
     process.stdout.write(`  Action: ${status.action}\n`);
   }
 
+  if (openCodeStatus !== null) {
+    process.stdout.write(`${openCodeStatus.label}: ${openCodeStatus.state}`);
+    process.stdout.write(`, transport ${openCodeStatus.transport}\n`);
+    process.stdout.write(`  ${openCodeStatus.path}\n`);
+    process.stdout.write(`  Endpoint: ${openCodeStatus.endpoint}\n`);
+    process.stdout.write(`  Detail: ${openCodeStatus.detail}\n`);
+    process.stdout.write(`  Action: ${openCodeStatus.action}\n`);
+  }
+
   process.stdout.write(`\nSuggested action: ${summary}\n`);
   return 0;
 }
@@ -638,23 +1208,25 @@ function runOnboardSync(argv: readonly string[]): number {
   const version = readPackageVersion();
   const plannedFiles = buildPlannedFiles(flags, targets, version);
   const enabledFiles = plannedFiles.filter((file) => file.enabled);
+  const openCodePlan = isOpenCodeEnabled(flags) ? buildOpenCodePlan(flags) : null;
+  const openCodeStatus = openCodePlan === null ? null : openCodePlan.status;
 
   if (flags.json && !flags.status) {
     process.stderr.write("agent-inspector onboard: --json is only supported with --status\n");
     return 2;
   }
 
-  if (enabledFiles.length === 0) {
+  if (enabledFiles.length === 0 && openCodePlan === null) {
     process.stderr.write("agent-inspector onboard: no onboarding target selected\n");
     return 2;
   }
 
   if (flags.status) {
-    return runStatus(plannedFiles, version, flags.json);
+    return runStatus(plannedFiles, version, flags.json, openCodeStatus);
   }
 
   if (flags.uninstall) {
-    return runUninstall(plannedFiles, version, flags.dryRun);
+    return runUninstall(plannedFiles, version, flags.dryRun, openCodePlan);
   }
 
   if (flags.dryRun) {
@@ -663,23 +1235,34 @@ function runOnboardSync(argv: readonly string[]): number {
       const status = existsSync(file.path) ? "exists" : "missing";
       process.stdout.write(`${file.label}: ${file.path} (${status})\n`);
     }
+    if (openCodePlan !== null) {
+      process.stdout.write(
+        `${openCodePlan.status.label}: ${openCodePlan.status.path} (${openCodePlan.status.state})\n`,
+      );
+      process.stdout.write(`  Transport: ${flags.opencodeTransport}\n`);
+      process.stdout.write(`  Endpoint: ${openCodePlan.status.endpoint}\n`);
+      process.stdout.write(`  Action: ${openCodePlan.status.action}\n`);
+      if (openCodePlan.blockedMessage !== null) {
+        process.stdout.write(`  ${openCodePlan.blockedMessage}\n`);
+      }
+    }
     process.stdout.write(`\nClaude skill headings:\n`);
-    if (!flags.codexOnly) {
+    if (!flags.codexOnly && !flags.opencodeOnly) {
       for (const heading of REQUIRED_PHASE_HEADINGS) {
         process.stdout.write(`  - ${heading}\n`);
       }
     } else {
-      process.stdout.write(`  (disabled by --codex-only)\n`);
+      process.stdout.write(`  (disabled by selected targets)\n`);
     }
     process.stdout.write(`\nCodex skill headings:\n`);
-    if (!flags.skipCodexSkill) {
+    if (!flags.skipCodexSkill && !flags.opencodeOnly) {
       for (const heading of REQUIRED_CODEX_PHASE_HEADINGS) {
         process.stdout.write(`  - ${heading}\n`);
       }
     } else {
-      process.stdout.write(`  (disabled by --skip-codex-skill)\n`);
+      process.stdout.write(`  (disabled by selected targets)\n`);
     }
-    if (!flags.codexOnly) {
+    if (!flags.codexOnly && !flags.opencodeOnly) {
       process.stdout.write(`\nDetected tools:\n${buildDetectedSummary()}\n`);
     }
     process.stdout.write(`\nNo files were written.\n`);
@@ -687,10 +1270,19 @@ function runOnboardSync(argv: readonly string[]): number {
   }
 
   const filesToWrite = plannedFiles.filter((file) => shouldWrite(file, flags.force, version));
-  if (filesToWrite.length === 0) {
+  const shouldWriteOpenCode =
+    openCodePlan !== null && openCodePlan.shouldWrite && openCodePlan.body !== null;
+  if (openCodePlan !== null && openCodePlan.status.state === "invalid") {
+    process.stderr.write(`agent-inspector onboard: ${openCodePlan.blockedMessage ?? "invalid"}\n`);
+    return 1;
+  }
+  if (filesToWrite.length === 0 && !shouldWriteOpenCode) {
     process.stdout.write(
       "agent-inspector onboard: all selected onboarding files are already up to date\n",
     );
+    if (openCodePlan !== null && openCodePlan.blockedMessage !== null) {
+      process.stdout.write(`${openCodePlan.blockedMessage}\n`);
+    }
     process.stdout.write("Re-run with --force to refresh.\n");
     return 0;
   }
@@ -700,6 +1292,10 @@ function runOnboardSync(argv: readonly string[]): number {
       mkdirSync(dirname(file.path), { recursive: true });
       writeFileSync(file.path, file.body, "utf8");
     }
+    if (shouldWriteOpenCode && openCodePlan !== null && openCodePlan.body !== null) {
+      mkdirSync(dirname(openCodePlan.status.path), { recursive: true });
+      writeFileSync(openCodePlan.status.path, openCodePlan.body, "utf8");
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`agent-inspector onboard: failed to write files: ${msg}\n`);
@@ -712,14 +1308,26 @@ function runOnboardSync(argv: readonly string[]): number {
   for (const file of filesToWrite) {
     process.stdout.write(`Installed/updated ${file.label} to: ${file.path}\n`);
   }
+  if (shouldWriteOpenCode && openCodePlan !== null) {
+    process.stdout.write(`Installed/updated OpenCode MCP config: ${openCodePlan.status.path}\n`);
+  }
   process.stdout.write(`\nNext steps:\n`);
-  if (!flags.codexOnly) {
+  if (!flags.codexOnly && !flags.opencodeOnly) {
     process.stdout.write(`  - Open Claude Code and run: /agent-inspector:onboard\n`);
   }
-  if (!flags.skipCodexSkill) {
+  if (!flags.skipCodexSkill && !flags.opencodeOnly) {
     process.stdout.write(`  - Open Codex and ask to use the agent-inspector-onboard skill\n`);
   }
-  process.stdout.write(`  - Refresh later: agent-inspector onboard --force\n`);
-  process.stdout.write(`  - Detected primary tool: ${toolHint}\n`);
+  if (openCodePlan !== null) {
+    process.stdout.write(`  - Verify OpenCode MCP: opencode mcp list\n`);
+  }
+  if (flags.opencodeOnly) {
+    process.stdout.write(
+      `  - Refresh OpenCode later: agent-inspector onboard --opencode-only --force\n`,
+    );
+  } else {
+    process.stdout.write(`  - Refresh later: agent-inspector onboard --force\n`);
+    process.stdout.write(`  - Detected primary tool: ${toolHint}\n`);
+  }
   return 0;
 }