@kairyou/agent-tools 0.1.0 → 0.3.0

package/scripts/install.mjs

@@ -1,15 +1,26 @@
 #!/usr/bin/env node
 // agent-tools installer: wires statusline / usage into each agent's config.
-// Skills are NOT handled here — install those with `npx skills add`.
+// Runtime-dependent skills are installed with their capability. Standalone
+// workflow/integration skills are still handled by `npx skills add`.
 //
 // Capabilities (all global for now — they target the user-level config):
 //   statusline  Claude Code statusLine script (claude only).
-//   usage       Active API provider quota/balance (codex + opencode).
+//   usage       Active API provider quota/balance (all agents).
+//   vision      inspect_image MCP server + at-vision skill (all agents).
+//
+// Standalone commands (dispatched before capability parsing):
+//   inspect-image <path|url> --question "..."   Human diagnostic for vision.
+//   mcp-vision                                  Run the vision MCP stdio server.
 //
 // Targets:
 //   claude   -> ~/.claude/settings.json (statusLine key)
+//               + ~/.claude/skills/at-usage
+//               ~/.claude.json (vision MCP) + ~/.claude/skills (at-vision)
 //   codex    -> ~/.codex/hooks.json (standalone hooks file)
-//   opencode -> ~/.config/opencode/ (server + TUI plugins)
+//               + ~/.agents/skills/at-usage
+//               ~/.codex/config.toml (vision MCP) + ~/.agents/skills (at-vision)
+//   opencode -> ~/.config/opencode/ (server + TUI plugins,
+//               vision MCP in opencode.json + skills/at-vision)
 // Runtime scripts are copied into ~/.agent-tools so this installer can be
 // run via npx from GitHub without requiring a persistent local clone.
 //
@@ -25,10 +36,15 @@
 //   --settings <path>         Override the Claude settings.json (for testing).
 //   --codex-hooks <path>      Override the Codex hooks.json (for testing).
 //   --opencode-config-dir <p> Override the opencode config dir (for testing).
+//   --claude-json <path>      Override ~/.claude.json for vision MCP (for testing).
+//   --claude-skills-dir <p>   Override ~/.claude/skills (for testing).
+//   --codex-config <path>     Override ~/.codex/config.toml (for testing).
+//   --codex-skills-dir <p>    Override ~/.agents/skills (for testing).
 //   --uninstall               Remove what this installer added, restoring backups.
 //   --dry-run                 Print planned changes without writing anything.
 //   -h, --help                Show this help.
 
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -41,28 +57,40 @@ const INSTALL_ROOT =
 const META_KEY = "_agentTools";
 const META_VERSION = 1;
 const SOURCE = {
-  codexUsageHook: path.join(REPO_ROOT, "hooks", "codex", "usage-hook.mjs"),
-  usageScript: path.join(REPO_ROOT, "lib", "usage.mjs"),
+  codexUsageHook: path.join(REPO_ROOT, "integrations", "usage", "codex-hook.mjs"),
+  usageScript: path.join(REPO_ROOT, "integrations", "usage", "core.mjs"),
+  usageCli: path.join(REPO_ROOT, "integrations", "usage", "cli.mjs"),
   config: path.join(REPO_ROOT, "config.default.jsonc"),
-  claudeStatusline: path.join(REPO_ROOT, "statusline", "claude", "statusline.mjs"),
-  opencodeUsagePlugin: path.join(REPO_ROOT, "plugins", "opencode", "usage-plugin.mjs"),
-  opencodeUsageTui: path.join(REPO_ROOT, "plugins", "opencode", "usage-tui.mjs"),
+  claudeStatusline: path.join(REPO_ROOT, "integrations", "statusline", "claude-statusline.mjs"),
+  opencodeUsagePlugin: path.join(REPO_ROOT, "integrations", "usage", "opencode-plugin.mjs"),
+  opencodeUsageTui: path.join(REPO_ROOT, "integrations", "usage", "opencode-tui.mjs"),
 };
 const RUNTIME = {
-  codexUsageHook: path.join(INSTALL_ROOT, "hooks", "codex", "usage-hook.mjs"),
-  usageScript: path.join(INSTALL_ROOT, "lib", "usage.mjs"),
+  codexUsageHook: path.join(INSTALL_ROOT, "integrations", "usage", "codex-hook.mjs"),
+  usageScript: path.join(INSTALL_ROOT, "integrations", "usage", "core.mjs"),
+  usageCli: path.join(INSTALL_ROOT, "integrations", "usage", "cli.mjs"),
   config: path.join(INSTALL_ROOT, "config.jsonc"),
-  claudeStatusline: path.join(INSTALL_ROOT, "statusline", "claude", "statusline.mjs"),
-  opencodeUsagePlugin: path.join(INSTALL_ROOT, "plugins", "opencode", "usage-plugin.mjs"),
-  opencodeUsageTui: path.join(INSTALL_ROOT, "plugins", "opencode", "usage-tui.mjs"),
+  claudeStatusline: path.join(INSTALL_ROOT, "integrations", "statusline", "claude-statusline.mjs"),
+  opencodeUsagePlugin: path.join(INSTALL_ROOT, "integrations", "usage", "opencode-plugin.mjs"),
+  opencodeUsageTui: path.join(INSTALL_ROOT, "integrations", "usage", "opencode-tui.mjs"),
 };
-const ALL_CAPS = ["statusline", "usage"];
+const ALL_CAPS = ["statusline", "usage", "vision"];
 const ALL_AGENTS = ["claude", "codex", "opencode"];
 const AGENT_CAPS = {
-  claude: ["statusline"],
-  codex: ["usage"],
-  opencode: ["usage"],
+  claude: ["statusline", "usage", "vision"],
+  codex: ["usage", "vision"],
+  opencode: ["usage", "vision"],
 };
+const VISION_MCP_NAME = "agent-tools-vision";
+const VISION_SKILL_NAME = "at-vision";
+// The at-vision skill ships inside the vision capability dir (integrations/vision),
+// not skills/: it is unusable without the MCP server, so it must not surface
+// as an independently installable skill.
+const VISION_SKILL_SRC = path.join(REPO_ROOT, "integrations", "vision", "skills", VISION_SKILL_NAME);
+const USAGE_SKILL_NAME = "at-usage";
+const USAGE_SKILL_SRC = path.join(REPO_ROOT, "integrations", "usage", "skills", USAGE_SKILL_NAME);
+const VISION_BUNDLED_MCP_SERVER = path.join(REPO_ROOT, "dist", "vision", "mcp-server.mjs");
+const VISION_BUNDLED_CLI = path.join(REPO_ROOT, "dist", "vision", "cli.mjs");
 
 function fwd(p) {
   return p.replace(/\\/g, "/");
@@ -152,7 +180,7 @@ function isOpenCodeUsageTuiEntry(entry) {
   const spec = Array.isArray(entry) ? entry[0] : entry;
   return (
     typeof spec === "string" &&
-    /\/plugins\/opencode\/usage-tui\.mjs$/i.test(spec.replace(/\\/g, "/"))
+    /\/integrations\/usage\/opencode-tui\.mjs$/i.test(spec.replace(/\\/g, "/"))
   );
 }
 
@@ -233,6 +261,7 @@ function installRuntimeAssets(opts) {
       addFile(SOURCE.opencodeUsageTui, RUNTIME.opencodeUsageTui);
     }
     addFile(SOURCE.usageScript, RUNTIME.usageScript);
+    addFile(SOURCE.usageCli, RUNTIME.usageCli);
     addFile(SOURCE.config, RUNTIME.config, { mergeJsonc: true });
   }
   if (files.length === 0) return;
@@ -243,10 +272,14 @@ function installRuntimeAssets(opts) {
 function parseArgs(argv) {
   const opts = {
     agents: [],
-    capabilities: [],
+    integrations: [],
     settings: null,
     codexHooks: null,
     opencodeConfigDir: null,
+    claudeJson: null,
+    claudeSkillsDir: null,
+    codexConfig: null,
+    codexSkillsDir: null,
     uninstall: false,
     dryRun: false,
     help: false,
@@ -277,6 +310,10 @@ function parseArgs(argv) {
       case "--settings": opts.settings = argv[++i]; break;
       case "--codex-hooks": opts.codexHooks = argv[++i]; break;
       case "--opencode-config-dir": opts.opencodeConfigDir = argv[++i]; break;
+      case "--claude-json": opts.claudeJson = argv[++i]; break;
+      case "--claude-skills-dir": opts.claudeSkillsDir = argv[++i]; break;
+      case "--codex-config": opts.codexConfig = argv[++i]; break;
+      case "--codex-skills-dir": opts.codexSkillsDir = argv[++i]; break;
       case "--uninstall": opts.uninstall = true; break;
       case "--dry-run": opts.dryRun = true; break;
       case "-h":
@@ -286,15 +323,15 @@ function parseArgs(argv) {
           console.error(`Unknown option: ${a}`);
           process.exit(2);
         }
-        opts.capabilities.push(a);
+        opts.integrations.push(a);
     }
   }
   if (opts.agents.length === 0) opts.agents = ["claude"];
-  if (!opts.help && opts.capabilities.length === 0) {
+  if (!opts.help && opts.integrations.length === 0) {
     console.error(`Missing capability (available: ${ALL_CAPS.join(", ")})`);
     process.exit(2);
   }
-  for (const name of opts.capabilities) {
+  for (const name of opts.integrations) {
     if (!ALL_CAPS.includes(name)) {
       console.error(`Unknown capability: ${name} (available: ${ALL_CAPS.join(", ")})`);
       process.exit(2);
@@ -304,14 +341,14 @@ function parseArgs(argv) {
 }
 
 function wants(opts, cap) {
-  return opts.capabilities.length === 0 || opts.capabilities.includes(cap);
+  return opts.integrations.length === 0 || opts.integrations.includes(cap);
 }
 
 function validateAgentCapabilities(opts) {
   const invalid = [];
   for (const agent of opts.agents) {
     const supported = AGENT_CAPS[agent] || [];
-    for (const cap of opts.capabilities) {
+    for (const cap of opts.integrations) {
       if (!supported.includes(cap)) invalid.push(`${cap} -a ${agent}`);
     }
   }
@@ -322,7 +359,6 @@ function validateAgentCapabilities(opts) {
   for (const agent of ALL_AGENTS) {
     console.error(`  ${agent}: ${AGENT_CAPS[agent].join(", ")}`);
   }
-  console.error("Claude API usage is refreshed by the statusline capability; use `statusline -a claude`.");
   process.exit(2);
 }
 
@@ -380,7 +416,7 @@ function isOurProviderUsageEntry(entry) {
     entry.hooks.some(
       (h) =>
         typeof h?.command === "string" &&
-        /(?:^|[/\\])(?:usage-hook|usage)\.mjs(?:["\s]|$)/.test(h.command)
+        /(?:^|[/\\])codex-hook\.mjs(?:["\s]|$)/.test(h.command)
     )
   );
 }
@@ -403,9 +439,309 @@ function applyProviderUsage(cfg, { remove }) {
   if (Object.keys(cfg.hooks).length === 0) delete cfg.hooks;
 }
 
+// ---- Vision capability helpers. ----
+
+// The installed tree mirrors the package tree, so the bundled runtime lands in
+// dist/vision just like in the package.
+const VISION_RUNTIME_DIR = path.join(INSTALL_ROOT, "dist", "vision");
+const VISION_RATE_LIMIT_STATE = path.join(INSTALL_ROOT, "cache", "vision-rate-limit.json");
+const VISION_DIST_DIR = path.join(REPO_ROOT, "dist", "vision");
+const VISION_RUNTIME_SERVER = path.join(VISION_RUNTIME_DIR, "mcp-server.mjs");
+const VISION_RUNTIME_CLI = path.join(VISION_RUNTIME_DIR, "cli.mjs");
+const SKILL_MARKER = ".agent-tools-managed.json";
+const VISION_SKILL_MARKER_DATA = Object.freeze({
+  owner: "@kairyou/agent-tools",
+  capability: "vision",
+  artifact: "skill",
+});
+const USAGE_SKILL_MARKER_DATA = Object.freeze({
+  owner: "@kairyou/agent-tools",
+  capability: "usage",
+  artifact: "skill",
+});
+// Vision is bundled at release time. Install atomically swaps two self-contained
+// entry files into ~/.agent-tools/dist/vision, so hosts never run npm and a
+// failed update cannot destroy the previously working runtime.
+function visionMcpCommand() {
+  return { command: "node", args: [fwd(VISION_RUNTIME_SERVER)] };
+}
+
+function sameFilePath(left, right) {
+  function canonical(value) {
+    const resolved = path.resolve(String(value));
+    try {
+      return fs.realpathSync.native(resolved);
+    } catch {
+      return resolved;
+    }
+  }
+  const a = canonical(left);
+  const b = canonical(right);
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+function isVisionServerPath(value) {
+  return sameFilePath(value, VISION_RUNTIME_SERVER);
+}
+
+function isClaudeVisionMcp(value, mcp = visionMcpCommand()) {
+  return Boolean(
+    value &&
+      value.command === mcp.command &&
+      Array.isArray(value.args) &&
+      value.args.length === 1 &&
+      isVisionServerPath(value.args[0])
+  );
+}
+
+function isOpenCodeVisionMcp(value, mcp = visionMcpCommand()) {
+  return Boolean(
+    value &&
+      value.type === "local" &&
+      Array.isArray(value.command) &&
+      value.command.length === 2 &&
+      value.command[0] === mcp.command &&
+      isVisionServerPath(value.command[1])
+  );
+}
+
+function installVisionRuntime(opts) {
+  if (opts.uninstall) return;
+  console.log(`vision runtime: ${VISION_RUNTIME_DIR}`);
+  if (opts.dryRun) {
+    console.log(`  [dry-run] would atomically install ${VISION_DIST_DIR} -> ${VISION_RUNTIME_DIR}`);
+    return;
+  }
+  for (const name of ["mcp-server.mjs", "cli.mjs"]) {
+    if (!fs.existsSync(path.join(VISION_DIST_DIR, name))) {
+      throw new Error(`Missing bundled vision runtime ${path.join(VISION_DIST_DIR, name)}. Run npm run build:vision.`);
+    }
+  }
+
+  fs.mkdirSync(path.dirname(VISION_RUNTIME_DIR), { recursive: true });
+  const suffix = `${process.pid}-${Date.now()}`;
+  const stage = `${VISION_RUNTIME_DIR}.stage-${suffix}`;
+  const backup = `${VISION_RUNTIME_DIR}.backup-${suffix}`;
+  let movedCurrent = false;
+  try {
+    fs.cpSync(VISION_DIST_DIR, stage, { recursive: true });
+    writeText(
+      path.join(stage, "runtime.json"),
+      JSON.stringify({ owner: "@kairyou/agent-tools", capability: "vision", version: 1 }, null, 2) + "\n",
+      false
+    );
+    for (const name of ["mcp-server.mjs", "cli.mjs"]) {
+      const check = spawnSync(process.execPath, ["--check", path.join(stage, name)], {
+        encoding: "utf8",
+      });
+      if (check.status !== 0) {
+        throw new Error(`Bundled vision runtime failed syntax validation (${name}): ${check.stderr || check.stdout}`);
+      }
+    }
+
+    if (fs.existsSync(VISION_RUNTIME_DIR)) {
+      fs.renameSync(VISION_RUNTIME_DIR, backup);
+      movedCurrent = true;
+    }
+    if (process.env.AGENT_TOOLS_VISION_TEST_FAIL_SWAP === "1") {
+      throw new Error("Simulated vision runtime swap failure");
+    }
+    fs.renameSync(stage, VISION_RUNTIME_DIR);
+    fs.rmSync(backup, { recursive: true, force: true });
+    console.log("  installed bundled vision runtime");
+  } catch (error) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    if (movedCurrent && !fs.existsSync(VISION_RUNTIME_DIR) && fs.existsSync(backup)) {
+      fs.renameSync(backup, VISION_RUNTIME_DIR);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+    if (fs.existsSync(VISION_RUNTIME_DIR)) fs.rmSync(backup, { recursive: true, force: true });
+  }
+}
+
+function isManagedSkillDir(dest, markerData) {
+  const marker = path.join(dest, SKILL_MARKER);
+  if (!fs.existsSync(marker)) return false;
+  try {
+    const value = JSON.parse(fs.readFileSync(marker, "utf8"));
+    return Object.entries(markerData).every(([key, expected]) => value?.[key] === expected);
+  } catch {
+    return false;
+  }
+}
+
+function installManagedSkillDir(
+  skillsRoot,
+  { name, source, markerData, replacements, remove, dryRun }
+) {
+  const dest = path.join(skillsRoot, name);
+  const isManaged = () => isManagedSkillDir(dest, markerData);
+  if (remove) {
+    if (!fs.existsSync(dest)) return;
+    if (!isManaged()) {
+      console.log(`  kept unmanaged ${dest}`);
+      return;
+    }
+    if (dryRun) {
+      console.log(`  [dry-run] would remove ${dest}`);
+      return;
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+    console.log(`  removed ${dest}`);
+    return;
+  }
+  if (fs.existsSync(dest) && !isManaged()) {
+    console.error(
+      `  Refusing to overwrite existing unowned skill directory ${dest}. ` +
+        `Move or remove it, then re-run the install.`
+    );
+    process.exit(1);
+  }
+  if (dryRun) {
+    console.log(`  [dry-run] would copy ${source} -> ${dest}`);
+    return;
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.cpSync(source, dest, { recursive: true });
+  const skillFile = path.join(dest, "SKILL.md");
+  let skill = fs.readFileSync(skillFile, "utf8");
+  for (const [token, value] of Object.entries(replacements)) {
+    if (!skill.includes(token)) {
+      fs.rmSync(dest, { recursive: true, force: true });
+      throw new Error(`${name} skill template is missing ${token}`);
+    }
+    skill = skill.replaceAll(token, value);
+  }
+  fs.writeFileSync(skillFile, skill);
+  fs.writeFileSync(
+    path.join(dest, SKILL_MARKER),
+    JSON.stringify(markerData, null, 2) + "\n"
+  );
+  console.log(`  wrote ${dest}`);
+}
+
+function installVisionSkillDir(skillsRoot, { remove, dryRun }) {
+  installManagedSkillDir(skillsRoot, {
+    name: VISION_SKILL_NAME,
+    source: VISION_SKILL_SRC,
+    markerData: VISION_SKILL_MARKER_DATA,
+    replacements: { "{{VISION_CLI_PATH}}": fwd(VISION_RUNTIME_CLI) },
+    remove,
+    dryRun,
+  });
+}
+
+function installUsageSkillDir(skillsRoot, agent, { remove, dryRun }) {
+  installManagedSkillDir(skillsRoot, {
+    name: USAGE_SKILL_NAME,
+    source: USAGE_SKILL_SRC,
+    markerData: USAGE_SKILL_MARKER_DATA,
+    replacements: {
+      "{{USAGE_CLI_PATH}}": fwd(RUNTIME.usageCli),
+      "{{USAGE_AGENT}}": agent,
+    },
+    remove,
+    dryRun,
+  });
+}
+
+const CODEX_VISION_BEGIN = "# >>> agent-tools vision >>>";
+const CODEX_VISION_END = "# <<< agent-tools vision <<<";
+
+// Codex config.toml is user-owned free-form TOML; we manage exactly one
+// marker-delimited block so install/update/uninstall never touch other keys.
+function updateCodexVisionBlock(file, { remove, dryRun, mcp }) {
+  const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const blockRe = new RegExp(
+    `\\r?\\n?${escape(CODEX_VISION_BEGIN)}[\\s\\S]*?${escape(CODEX_VISION_END)}\\r?\\n?`
+  );
+  let next = current.replace(blockRe, "\n").replace(/^\n+/, "");
+  if (!remove) {
+    // A same-named table outside our marker block would make the appended
+    // TOML a duplicate declaration and break the ENTIRE config.toml parse.
+    const manualRe = new RegExp(`^\\s*\\[mcp_servers\\.["']?${escape(VISION_MCP_NAME)}["']?\\]`, "m");
+    if (manualRe.test(next)) {
+      console.error(
+        `  Found an existing [mcp_servers.${VISION_MCP_NAME}] entry in ${file} that was not ` +
+          "written by this installer. Remove or rename that entry, then re-run the install."
+      );
+      process.exit(1);
+    }
+    const args = mcp.args.map((a) => JSON.stringify(a)).join(", ");
+    const block = [
+      CODEX_VISION_BEGIN,
+      `[mcp_servers.${VISION_MCP_NAME}]`,
+      `command = ${JSON.stringify(mcp.command)}`,
+      `args = [${args}]`,
+      CODEX_VISION_END,
+      "",
+    ].join("\n");
+    next = next.trim() === "" ? block : next.replace(/\s*$/, "\n\n") + block;
+  }
+  if (next === current) {
+    console.log(`  kept existing ${file}`);
+    return;
+  }
+  if (remove && next.trim() === "" && fs.existsSync(file) && current.trim() !== "") {
+    // The file only ever contained our block; leave an empty file rather than
+    // deleting config.toml, which Codex may expect to exist.
+    writeText(file, "", dryRun);
+    return;
+  }
+  writeText(file, next, dryRun);
+}
+
 // ---- Claude: statusLine backed up in _agentTools. ----
 
+function runClaudeVision(opts) {
+  const claudeJson = opts.claudeJson || path.join(os.homedir(), ".claude.json");
+  const skillsDir = opts.claudeSkillsDir || path.join(os.homedir(), ".claude", "skills");
+  console.log(`claude vision: ${claudeJson}`);
+  const cfg = readJson(claudeJson);
+  const mcp = visionMcpCommand();
+  const existing = cfg.mcpServers?.[VISION_MCP_NAME];
+  if (opts.uninstall) {
+    if (isClaudeVisionMcp(existing, mcp)) {
+      delete cfg.mcpServers[VISION_MCP_NAME];
+      if (Object.keys(cfg.mcpServers).length === 0) delete cfg.mcpServers;
+      writeJson(claudeJson, cfg, opts.dryRun);
+    } else if (existing) {
+      console.log(`  kept unmanaged ${VISION_MCP_NAME} entry in ${claudeJson}`);
+    } else {
+      console.log(`  no ${VISION_MCP_NAME} MCP entry found; nothing to remove.`);
+    }
+    installVisionSkillDir(skillsDir, { remove: true, dryRun: opts.dryRun });
+    console.log("  - vision");
+    return;
+  }
+  if (existing && !isClaudeVisionMcp(existing, mcp)) {
+    throw new Error(
+      `Found an existing unmanaged ${VISION_MCP_NAME} entry in ${claudeJson}. ` +
+        "Remove or rename it, then re-run the install."
+    );
+  }
+  cfg.mcpServers = cfg.mcpServers || {};
+  cfg.mcpServers[VISION_MCP_NAME] = { type: "stdio", command: mcp.command, args: mcp.args };
+  writeJson(claudeJson, cfg, opts.dryRun);
+  installVisionSkillDir(skillsDir, { remove: false, dryRun: opts.dryRun });
+  console.log("  + vision (inspect_image MCP + at-vision skill)");
+}
+
 function runClaude(opts) {
+  if (wants(opts, "vision")) runClaudeVision(opts);
+  if (wants(opts, "usage")) {
+    const skillsDir = opts.claudeSkillsDir || path.join(os.homedir(), ".claude", "skills");
+    console.log(`claude usage: ${skillsDir}`);
+    installUsageSkillDir(skillsDir, "claude", {
+      remove: opts.uninstall,
+      dryRun: opts.dryRun,
+    });
+    console.log(opts.uninstall ? "  - usage skill" : "  + usage skill (at-usage)");
+  }
+  if (!wants(opts, "statusline")) return;
   const settings = opts.settings || path.join(os.homedir(), ".claude", "settings.json");
   console.log(`claude (global): ${settings}`);
   const cfg = readJson(settings);
@@ -444,11 +780,30 @@ function runClaude(opts) {
 // written (Codex validates hooks.json against a schema); our hook is found by
 // command signature instead. ----
 
+function runCodexVision(opts) {
+  const file = opts.codexConfig || path.join(os.homedir(), ".codex", "config.toml");
+  const skillsDir = opts.codexSkillsDir || path.join(os.homedir(), ".agents", "skills");
+  console.log(`codex vision: ${file}`);
+  updateCodexVisionBlock(file, {
+    remove: opts.uninstall,
+    dryRun: opts.dryRun,
+    mcp: visionMcpCommand(),
+  });
+  installVisionSkillDir(skillsDir, { remove: opts.uninstall, dryRun: opts.dryRun });
+  console.log(opts.uninstall ? "  - vision" : "  + vision (inspect_image MCP + at-vision skill)");
+}
+
 function runCodex(opts) {
+  if (wants(opts, "vision")) runCodexVision(opts);
   if (!wants(opts, "usage")) {
-    console.log("codex: nothing to do (supports: usage).");
     return;
   }
+  const skillsDir = opts.codexSkillsDir || path.join(os.homedir(), ".agents", "skills");
+  console.log(`codex usage skill: ${skillsDir}`);
+  installUsageSkillDir(skillsDir, "codex", {
+    remove: opts.uninstall,
+    dryRun: opts.dryRun,
+  });
   const file = opts.codexHooks || path.join(os.homedir(), ".codex", "hooks.json");
   console.log(`codex (global): ${file}`);
   const cfg = readJson(file);
@@ -491,9 +846,58 @@ function opencodeConfigDir(opts) {
   );
 }
 
+// opencode.json may be JSONC with user comments — edit only our key in place.
+function updateOpencodeVisionMcp(file, { remove, dryRun, mcp }) {
+  const exists = fs.existsSync(file);
+  const currentText = exists ? fs.readFileSync(file, "utf8") : "{}\n";
+  const errors = [];
+  const current = parseJsonc(currentText, errors, { allowTrailingComma: true }) || {};
+  if (errors.length > 0 || typeof current !== "object" || Array.isArray(current)) {
+    throw new Error(`Cannot parse ${file} as JSONC`);
+  }
+  const existing = current.mcp && current.mcp[VISION_MCP_NAME];
+  if (existing && !isOpenCodeVisionMcp(existing, mcp)) {
+    if (remove) {
+      console.log(`  kept unmanaged ${VISION_MCP_NAME} entry in ${file}`);
+      return;
+    }
+    throw new Error(
+      `Found an existing unmanaged ${VISION_MCP_NAME} entry in ${file}. ` +
+        "Remove or rename it, then re-run the install."
+    );
+  }
+  const desired = remove
+    ? undefined
+    : { type: "local", command: [mcp.command, ...mcp.args], enabled: true };
+  if (JSON.stringify(existing) === JSON.stringify(desired)) {
+    console.log(`  kept existing ${file}`);
+    return;
+  }
+  const eol = currentText.includes("\r\n") ? "\r\n" : "\n";
+  const edits = modify(currentText, ["mcp", VISION_MCP_NAME], desired, {
+    formattingOptions: { insertSpaces: true, tabSize: 2, eol },
+  });
+  const updated = applyEdits(currentText, edits).replace(/\s*$/, "") + eol;
+  writeText(file, updated, dryRun);
+}
+
+function runOpencodeVision(opts) {
+  const configDir = opencodeConfigDir(opts);
+  const file = path.join(configDir, "opencode.json");
+  const skillsDir = path.join(configDir, "skills");
+  console.log(`opencode vision: ${file}`);
+  updateOpencodeVisionMcp(file, {
+    remove: opts.uninstall,
+    dryRun: opts.dryRun,
+    mcp: visionMcpCommand(),
+  });
+  installVisionSkillDir(skillsDir, { remove: opts.uninstall, dryRun: opts.dryRun });
+  console.log(opts.uninstall ? "  - vision" : "  + vision (inspect_image MCP + at-vision skill)");
+}
+
 function runOpencode(opts) {
+  if (wants(opts, "vision")) runOpencodeVision(opts);
   if (!wants(opts, "usage")) {
-    console.log("opencode: nothing to do (supports: usage).");
     return;
   }
 
@@ -520,6 +924,70 @@ function runOpencode(opts) {
   if (!opts.dryRun) console.log("  NOTE: restart opencode to load the agent-tools usage plugin.");
 }
 
+function visionRuntimeHasRemainingReference(opts) {
+  const removed = new Set(opts.agents);
+  if (!removed.has("claude")) {
+    const file = opts.claudeJson || path.join(os.homedir(), ".claude.json");
+    try {
+      if (isClaudeVisionMcp(readJson(file).mcpServers?.[VISION_MCP_NAME])) return true;
+    } catch {
+      return true;
+    }
+  }
+  if (!removed.has("codex")) {
+    const file = opts.codexConfig || path.join(os.homedir(), ".codex", "config.toml");
+    try {
+      const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+      const start = text.indexOf(CODEX_VISION_BEGIN);
+      const end = text.indexOf(CODEX_VISION_END, start + CODEX_VISION_BEGIN.length);
+      if (start !== -1 && end !== -1) {
+        const block = text.slice(start, end);
+        if (block.includes(fwd(VISION_RUNTIME_SERVER))) {
+          return true;
+        }
+      }
+    } catch {
+      return true;
+    }
+  }
+  if (!removed.has("opencode")) {
+    const file = path.join(opencodeConfigDir(opts), "opencode.json");
+    try {
+      if (fs.existsSync(file)) {
+        const errors = [];
+        const config = parseJsonc(fs.readFileSync(file, "utf8"), errors, { allowTrailingComma: true });
+        if (errors.length > 0) return true;
+        if (isOpenCodeVisionMcp(config?.mcp?.[VISION_MCP_NAME])) return true;
+      }
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+
+function cleanupVisionRuntimeIfUnused(opts) {
+  if (!opts.uninstall || !wants(opts, "vision") || !fs.existsSync(VISION_RUNTIME_DIR)) return;
+  if (visionRuntimeHasRemainingReference(opts)) {
+    console.log(`  kept shared vision runtime ${VISION_RUNTIME_DIR} (another agent still references it)`);
+    return;
+  }
+  if (opts.dryRun) {
+    console.log(`  [dry-run] would remove unused vision runtime ${VISION_RUNTIME_DIR}`);
+    return;
+  }
+  fs.rmSync(VISION_RUNTIME_DIR, { recursive: true, force: true });
+  if (!fs.existsSync(`${VISION_RATE_LIMIT_STATE}.lock`)) {
+    fs.rmSync(VISION_RATE_LIMIT_STATE, { force: true });
+    try {
+      fs.rmdirSync(path.dirname(VISION_RATE_LIMIT_STATE));
+    } catch {
+      // The shared cache directory may contain state for other integrations.
+    }
+  }
+  console.log(`  removed unused vision runtime ${VISION_RUNTIME_DIR}`);
+}
+
 const AGENTS = { claude: runClaude, codex: runCodex, opencode: runOpencode };
 
 function main() {
@@ -538,6 +1006,7 @@ function main() {
   }
   validateAgentCapabilities(opts);
   installRuntimeAssets(opts);
+  if (wants(opts, "vision")) installVisionRuntime(opts);
   for (const name of opts.agents) {
     const run = AGENTS[name];
     if (!run) {
@@ -546,6 +1015,19 @@ function main() {
     }
     run(opts);
   }
+  cleanupVisionRuntimeIfUnused(opts);
 }
 
-main();
+// Standalone vision commands dispatch before capability parsing so image
+// paths and questions are never mistaken for integrations.
+const subcommand = process.argv[2];
+if (subcommand === "inspect-image") {
+  const { runInspectImageCli } = await import(
+    pathToFileURL(VISION_BUNDLED_CLI).href
+  );
+  process.exitCode = await runInspectImageCli(process.argv.slice(3));
+} else if (subcommand === "mcp-vision") {
+  await import(pathToFileURL(VISION_BUNDLED_MCP_SERVER).href);
+} else {
+  main();
+}