likho-cli 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# likho-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect every AI tool on your computer to [Likho](https://likho.me) in one
+command.
+
+```
+npx likho-cli
+```
+
+1. Inside a project folder it asks: **just this project**, or **all projects
+   on this computer**.
+2. It finds your AI tools: Claude Code, Codex, Cursor, VS Code, Gemini CLI,
+   opencode, Windsurf (and tells you how to add Claude Desktop).
+3. Your browser opens on likho.me to choose the organization: one for the
+   project, or one per tool.
+4. It adds Likho to each tool's MCP settings, next to your other servers, and
+   keeps a `.likho-backup` of any file it changes.
+
+Run it again any time: tools already connected are shown with their
+organization and start unticked, so it only adds what's missing. Ticking a
+connected tool asks whether to keep it or switch it to another organization;
+nothing is switched silently.
+
+Then restart the tools, sign in once in each (one click, your browser is
+already signed in), and say "join Likho" in any chat.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `npx likho-cli` | Set up (asks this project or all projects) |
+| `npx likho-cli status` | What is connected where |
+| `npx likho-cli remove` | Take Likho out again |
+
+Options: `--here` (this project only), `--global` (all projects),
+`--tool codex,cursor` (only these tools), `--org <slug>` (skip the browser),
+`--yes` (no questions), `--server <url>` (another Likho).
+
+## What it writes
+
+Only Likho's address (`https://likho.me/mcp?org=<organization>`), never a key.
+Project files (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`,
+`.gemini/settings.json`, `opencode.json`) are safe to commit. Codex and
+Windsurf only have settings for all projects.

package/bin/likho.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// npx likho-cli: connect the AI tools on this computer to Likho.
+//
+//   npx likho-cli            set up (asks: this project, or all projects?)
+//   npx likho-cli status     what is connected where
+//   npx likho-cli remove     take Likho out again
+//
+// Options: --here (this project only), --global (all projects),
+// --tool codex,cursor (only these), --org <slug> (skip the browser step),
+// --yes (no questions), --server <url> (another Likho, default https://likho.me).
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { tools, context } = require("../lib/tools");
+const { chooseInBrowser } = require("../lib/browser");
+const { UnreadableFile } = require("../lib/files");
+
+const PROJECT_MARKERS = [".git", "package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml", "composer.json", "Gemfile", "pom.xml", "build.gradle", ".mcp.json"];
+const SUPPORT = "https://likho.me/dashboard/organizations";
+
+function parseArgs(argv) {
+  const opts = { command: "connect", tools: null, org: "", server: process.env.LIKHO_URL || "https://likho.me", scope: "", yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "status" || a === "remove" || a === "help") opts.command = a;
+    else if (a === "--here" || a === "--project") opts.scope = "project";
+    else if (a === "--global" || a === "--everywhere") opts.scope = "global";
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--tool") opts.tools = (argv[++i] || "").split(",").filter(Boolean);
+    else if (a === "--org") opts.org = argv[++i] || "";
+    else if (a === "--server") opts.server = (argv[++i] || opts.server).replace(/\/+$/, "");
+    else if (a === "-h" || a === "--help") opts.command = "help";
+  }
+  return opts;
+}
+
+function isProjectFolder(ctx) {
+  if (path.resolve(ctx.cwd) === path.resolve(ctx.home)) return false;
+  return PROJECT_MARKERS.some((m) => fs.existsSync(path.join(ctx.cwd, m)));
+}
+
+// Questions use arrow keys and space (@clack/prompts). Without a terminal to
+// ask in (CI, piped) or with --yes, every question takes its default.
+const interactive = (opts) => Boolean(process.stdin.isTTY && process.stdout.isTTY && !opts.yes);
+let ui;
+const loadUi = async () => (ui = ui || (await import("@clack/prompts")));
+
+class Cancelled extends Error {}
+
+async function answer(question) {
+  const value = await question;
+  if (ui.isCancel(value)) throw new Cancelled();
+  return value;
+}
+
+const say = (line = "") => console.log(line);
+const mcpUrl = (opts, org) => `${opts.server}/mcp${org ? `?org=${encodeURIComponent(org)}` : ""}`;
+
+/** The organization in a Likho address written by this tool ("" if none). */
+function orgOfUrl(url) {
+  try {
+    return new URL(url).searchParams.get("org") || "";
+  } catch {
+    return "";
+  }
+}
+
+async function chooseScope(opts, ctx, verb) {
+  if (opts.scope) return opts.scope;
+  if (!isProjectFolder(ctx)) return "global";
+  if (!interactive(opts)) return "project";
+  const folder = path.basename(ctx.cwd);
+  const setup = verb === "Set up";
+  return answer(ui.select({
+    message: `${verb} Likho for`,
+    options: [
+      { value: "project", label: `Just this project (${folder})`, hint: setup ? "every AI tool opened here uses one organization" : undefined },
+      { value: "global", label: "All projects on this computer", hint: setup ? "an organization for each tool" : undefined },
+    ],
+    initialValue: "project",
+  }));
+}
+
+function selectTools(opts, ctx) {
+  let list = tools(ctx);
+  if (opts.tools) list = list.filter((t) => opts.tools.includes(t.id));
+  return list;
+}
+
+function cancelled(err) {
+  if (!(err instanceof Cancelled)) throw err;
+  ui.cancel("Cancelled. Nothing was changed.");
+  return 1;
+}
+
+async function connect(opts) {
+  const ctx = context();
+  await loadUi();
+  try {
+    ui.intro("Likho: connect your AI tools");
+    const scope = await chooseScope(opts, ctx, "Set up");
+    const found = selectTools(opts, ctx).filter((t) => opts.tools || t.detect());
+    if (!found.length) {
+      ui.log.warn("No supported AI tools found on this computer.\nSupported: Claude Code, Codex, Cursor, VS Code, Gemini CLI, opencode, Windsurf, Claude Desktop.");
+      ui.outro(`To connect another tool by hand, see Connect in your Likho dashboard: ${SUPPORT}`);
+      return 1;
+    }
+    const usable = found.filter((t) => (scope === "project" ? t.project : t.global));
+    const elsewhere = found.filter((t) => !usable.includes(t));
+    if (elsewhere.length) {
+      ui.log.info(`${elsewhere.map((t) => t.name).join(", ")} can only be set up for all projects: run npx likho-cli --global for ${elsewhere.length === 1 ? "it" : "them"}.`);
+    }
+    if (!usable.length) {
+      ui.outro("Nothing to set up here.");
+      return 1;
+    }
+
+    // What is already set up, so running again adds what's missing and keeps
+    // what works. In a project, the all-projects setting is shown too: the
+    // project one overrides it in this folder.
+    const existing = new Map(usable.filter((t) => !t.manual).map((t) => [t.id, t.current(ctx, scope)]).filter(([, url]) => url));
+    const inherited = (t) => (scope === "project" && t.global && !t.manual ? t.current(ctx, "global") : null);
+    const hintFor = (t) => {
+      if (t.manual) return "you add it in its settings";
+      if (existing.has(t.id)) return `already connected → ${orgOfUrl(existing.get(t.id)) || "Likho"}`;
+      const all = inherited(t);
+      return all ? `connected for all projects → ${orgOfUrl(all) || "Likho"}; this would override it here` : undefined;
+    };
+
+    let chosen = usable.filter((t) => !existing.has(t.id));
+    if (opts.tools) {
+      chosen = usable; // named on the command line: set up as asked
+    } else if (interactive(opts)) {
+      if (!chosen.length) {
+        ui.log.info(`Likho is already set up here: ${usable.filter((t) => existing.has(t.id)).map((t) => `${t.name} → ${orgOfUrl(existing.get(t.id)) || "Likho"}`).join(", ")}`);
+        const next = await answer(ui.select({
+          message: "Anything to change?",
+          options: [
+            { value: "keep", label: "No, keep everything as it is" },
+            { value: "change", label: "Yes, switch a tool to another organization" },
+          ],
+          initialValue: "keep",
+        }));
+        if (next === "keep") {
+          ui.outro("Nothing to do.");
+          return 0;
+        }
+      }
+      const ids = await answer(ui.multiselect({
+        message: `Which AI tools should Likho connect${scope === "project" ? ` in ${path.basename(ctx.cwd)}` : ""}?`,
+        options: usable.map((t) => ({ value: t.id, label: t.name, hint: hintFor(t) })),
+        initialValues: chosen.map((t) => t.id),
+        required: false,
+      }));
+      chosen = usable.filter((t) => ids.includes(t.id));
+      // Ticking a connected tool means "switch it": confirm, never silently.
+      for (const t of chosen.filter((x) => existing.has(x.id))) {
+        const what = await answer(ui.select({
+          message: `${t.name} is already connected to ${orgOfUrl(existing.get(t.id)) || "Likho"}. What now?`,
+          options: [
+            { value: "keep", label: "Keep it as it is" },
+            { value: "switch", label: "Switch to another organization", hint: `you'll sign in again in ${t.name}` },
+          ],
+          initialValue: "keep",
+        }));
+        if (what === "keep") chosen = chosen.filter((x) => x !== t);
+      }
+    } else if (existing.size) {
+      ui.log.info(`Kept as they are: ${usable.filter((t) => existing.has(t.id)).map((t) => t.name).join(", ")} (already connected).`);
+    }
+    if (!chosen.length) {
+      ui.outro("Nothing changed.");
+      return 0;
+    }
+
+    // Which organization each lands in: picked in the browser, signed in.
+    let orgFor;
+    if (opts.org) {
+      orgFor = () => opts.org;
+    } else {
+      const spin = ui.spinner();
+      const choice = await chooseInBrowser(
+        opts.server,
+        { scope, tools: chosen.map((t) => t.id).join(","), folder: scope === "project" ? path.basename(ctx.cwd) : "" },
+        {
+          log: (line) => {
+            const text = line.trim();
+            if (text.startsWith("http")) {
+              ui.log.message(`If it didn't open: ${text}`);
+              spin.start("Pick the organization in your browser");
+            } else if (text) {
+              ui.log.step(text.replace(/\.\.\.$/, ""));
+            }
+          },
+        }
+      );
+      if (!choice) {
+        spin.stop("Cancelled in the browser", 1);
+        throw new Cancelled();
+      }
+      spin.stop(choice.org ? `Organization: ${choice.org}` : "Organizations chosen");
+      // The page can untick tools too; older pages don't send `tools`.
+      if (Array.isArray(choice.tools)) chosen = chosen.filter((t) => choice.tools.includes(t.id));
+      orgFor = (t) => (choice.orgs && choice.orgs[t.id]) || choice.org || "";
+    }
+    if (!chosen.length) {
+      ui.outro("No tools picked. Nothing was changed.");
+      return 0;
+    }
+
+    const done = [];
+    for (const t of chosen) {
+      const org = orgFor(t);
+      const url = mcpUrl(opts, org);
+      if (t.manual) {
+        ui.log.warn(`${t.name}: add it yourself. ${t.signIn}\nURL: ${url}`);
+        continue;
+      }
+      try {
+        const result = t.install(ctx, scope, url);
+        const was = existing.has(t.id) ? orgOfUrl(existing.get(t.id)) : "";
+        ui.log.success(`${t.name}${org ? ` → ${org}` : ""}${was && was !== org ? ` (was ${was})` : result.replaced ? " (updated)" : ""}`);
+        done.push(t);
+      } catch (err) {
+        ui.log.error(err instanceof UnreadableFile
+          ? `${t.name}: ${err.message} has comments or isn't plain JSON, so it was left alone.\nAdd a server named "likho" with URL ${url} to it yourself.`
+          : `${t.name}: ${err.message}`);
+      }
+    }
+
+    if (done.length) {
+      const lines = done.map((t) => `${t.name}: ${t.signIn}`);
+      if (scope === "project") lines.push("", "The files written here hold only Likho's address, no keys: safe to commit.");
+      ui.note(lines.join("\n"), "Restart these tools, then sign in once in each");
+      ui.outro('Then, in any chat: "join Likho"');
+    } else {
+      ui.outro("Nothing was connected.");
+    }
+    return done.length ? 0 : 1;
+  } catch (err) {
+    return cancelled(err);
+  }
+}
+
+function status(opts) {
+  const ctx = context();
+  const inProject = isProjectFolder(ctx);
+  say("\n  Likho connections\n");
+  for (const t of selectTools(opts, ctx)) {
+    if (t.manual) continue;
+    const rows = [];
+    if (t.global) rows.push(`all projects: ${t.current(ctx, "global") || "not connected"}`);
+    if (t.project && inProject) rows.push(`this project: ${t.current(ctx, "project") || "not connected"}`);
+    say(`  ${t.name.padEnd(14)} ${t.detect() ? "" : "(not installed) "}${rows.join(" · ")}`);
+  }
+  say();
+  return 0;
+}
+
+async function remove(opts) {
+  const ctx = context();
+  await loadUi();
+  try {
+    ui.intro("Likho: remove from your AI tools");
+    const scope = await chooseScope(opts, ctx, "Remove");
+    const connected = selectTools(opts, ctx).filter((t) => !t.manual && (scope === "project" ? t.project : t.global) && t.current(ctx, scope));
+    if (!connected.length) {
+      ui.outro("Likho isn't connected there.");
+      return 0;
+    }
+    let chosen = connected;
+    if (!opts.tools && interactive(opts)) {
+      const ids = await answer(ui.multiselect({
+        message: "Remove Likho from which tools?",
+        options: connected.map((t) => ({ value: t.id, label: t.name })),
+        initialValues: connected.map((t) => t.id),
+        required: true,
+      }));
+      chosen = connected.filter((t) => ids.includes(t.id));
+    }
+    for (const t of chosen) {
+      try {
+        if (t.remove(ctx, scope)) ui.log.success(`Removed from ${t.name}`);
+      } catch (err) {
+        ui.log.error(`${t.name}: ${err.message}`);
+      }
+    }
+    ui.outro("Done. Restart those tools.");
+    return 0;
+  } catch (err) {
+    return cancelled(err);
+  }
+}
+
+function help() {
+  say(`
+  npx likho-cli            Connect the AI tools on this computer to Likho.
+                           Inside a project folder it asks: this project, or all projects.
+  npx likho-cli status     Show what is connected where.
+  npx likho-cli remove     Take Likho out of your tools.
+
+  --here                   Only this project folder.
+  --global                 All projects on this computer.
+  --tool codex,cursor      Only these tools (claude-code, codex, cursor, vscode, gemini, opencode, windsurf).
+  --org <slug>             Use this organization; skips the browser.
+  --yes                    Don't ask questions.
+`);
+  return 0;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const run = { connect, status, remove, help }[opts.command];
+  process.exitCode = await run(opts);
+}
+
+main().catch((err) => {
+  console.error(`\n  likho: ${err.message}`);
+  process.exitCode = 1;
+});

package/lib/browser.js

@@ -0,0 +1,78 @@
+// Choosing organizations in the browser, where the person is signed in to
+// Likho. The CLI never holds a Likho credential: it opens likho.me, the page
+// sends back only the chosen organization names to a one-off address on this
+// computer (127.0.0.1), and each AI tool signs in on its own later.
+"use strict";
+
+const http = require("node:http");
+const crypto = require("node:crypto");
+const { spawn } = require("node:child_process");
+
+function openBrowser(url) {
+  try {
+    const [cmd, args] =
+      process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+      : process.platform === "darwin" ? ["open", [url]]
+      : ["xdg-open", [url]];
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const DONE_PAGE = (title, body) => `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title>
+<style>body{font:15px system-ui,sans-serif;background:#121212;color:#ededed;display:grid;place-items:center;height:100vh;margin:0}
+main{max-width:420px;text-align:center}h1{font-size:20px;font-weight:500}p{color:#a0a0a0}</style></head>
+<body><main><h1>${title}</h1><p>${body}</p></main></body></html>`;
+
+/**
+ * Open `${server}/cli/connect` and wait for the person's choice.
+ * Resolves to the parsed choice ({orgs: {tool: slug}} or {org: slug}), or null
+ * when they cancel or time runs out.
+ */
+function chooseInBrowser(server, params, { timeoutMs = 5 * 60 * 1000, log = console.log } = {}) {
+  const state = crypto.randomBytes(16).toString("hex");
+  return new Promise((resolve) => {
+    let finished = false;
+    const finish = (value) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      server_.close();
+      resolve(value);
+    };
+    const server_ = http.createServer((req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (url.pathname !== "/done" || url.searchParams.get("state") !== state) {
+        res.writeHead(404).end();
+        return;
+      }
+      if (url.searchParams.get("cancel")) {
+        res.writeHead(200, { "content-type": "text/html" }).end(DONE_PAGE("Cancelled", "Nothing was changed. You can close this tab."));
+        finish(null);
+        return;
+      }
+      let choice = null;
+      try {
+        choice = JSON.parse(Buffer.from(url.searchParams.get("choice") || "", "base64url").toString("utf8"));
+      } catch {
+        choice = null;
+      }
+      res.writeHead(200, { "content-type": "text/html" }).end(
+        DONE_PAGE("All set", "Go back to your terminal to finish. You can close this tab.")
+      );
+      finish(choice);
+    });
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    server_.listen(0, "127.0.0.1", () => {
+      const { port } = server_.address();
+      const link = `${server}/cli/connect?${new URLSearchParams({ ...params, port: String(port), state })}`;
+      log("\n  Opening your browser to choose the organization...");
+      if (!openBrowser(link)) log("  Couldn't open it. Open this link yourself:");
+      log(`  ${link}\n`);
+    });
+  });
+}
+
+module.exports = { chooseInBrowser, openBrowser };

package/lib/files.js

@@ -0,0 +1,106 @@
+// Reading and writing the settings files of AI tools, carefully: never touch
+// anything but Likho's own entry, keep a backup of a file before its first
+// change, and refuse (rather than guess) when a file can't be read as JSON.
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+class UnreadableFile extends Error {}
+
+function readJson(file) {
+  if (!fs.existsSync(file)) return {};
+  const raw = fs.readFileSync(file, "utf8").replace(/^/, "");
+  if (!raw.trim()) return {};
+  try {
+    const data = JSON.parse(raw);
+    if (data && typeof data === "object" && !Array.isArray(data)) return data;
+  } catch {
+    // Comments or a trailing comma (VS Code and opencode allow them): we
+    // don't rewrite what we can't read exactly.
+  }
+  throw new UnreadableFile(file);
+}
+
+const backedUp = new Set();
+
+function backup(file) {
+  if (backedUp.has(file) || !fs.existsSync(file)) return;
+  fs.copyFileSync(file, `${file}.likho-backup`);
+  backedUp.add(file);
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  backup(file);
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+/** Put `entry` at data[section][name]; returns the previous entry, if any. */
+function setEntry(file, section, name, entry) {
+  const data = readJson(file);
+  const block = data[section] && typeof data[section] === "object" ? data[section] : {};
+  const previous = block[name];
+  data[section] = { ...block, [name]: entry };
+  writeJson(file, data);
+  return previous;
+}
+
+/** Remove data[section][name]; true when something was removed. */
+function removeEntry(file, section, name) {
+  if (!fs.existsSync(file)) return false;
+  const data = readJson(file);
+  if (!data[section] || !(name in data[section])) return false;
+  delete data[section][name];
+  writeJson(file, data);
+  return true;
+}
+
+function getEntry(file, section, name) {
+  try {
+    return (readJson(file)[section] || {})[name] || null;
+  } catch {
+    return null;
+  }
+}
+
+// ---- Codex's TOML: only the [mcp_servers.<name>] table is ever touched.
+function tomlTable(name) {
+  return new RegExp(`^\\[mcp_servers\\.${name}\\][\\s\\S]*?(?=^\\[|(?![\\s\\S]))`, "m");
+}
+
+function setTomlServer(file, name, url) {
+  const raw = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const table = `[mcp_servers.${name}]\nurl = ${JSON.stringify(url)}\n\n`;
+  const next = tomlTable(name).test(raw) ? raw.replace(tomlTable(name), table) : `${raw.replace(/\s*$/, "\n\n")}${table}`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  backup(file);
+  fs.writeFileSync(file, next.replace(/^\n+/, ""), "utf8");
+}
+
+function getTomlServerUrl(file, name) {
+  if (!fs.existsSync(file)) return null;
+  const match = fs.readFileSync(file, "utf8").match(tomlTable(name));
+  const url = match && match[0].match(/^url\s*=\s*"([^"]*)"/m);
+  return url ? url[1] : null;
+}
+
+function removeTomlServer(file, name) {
+  if (!fs.existsSync(file)) return false;
+  const raw = fs.readFileSync(file, "utf8");
+  if (!tomlTable(name).test(raw)) return false;
+  backup(file);
+  fs.writeFileSync(file, raw.replace(tomlTable(name), ""), "utf8");
+  return true;
+}
+
+module.exports = {
+  UnreadableFile,
+  readJson,
+  setEntry,
+  removeEntry,
+  getEntry,
+  setTomlServer,
+  getTomlServerUrl,
+  removeTomlServer,
+};

package/lib/tools.js

@@ -0,0 +1,192 @@
+// The AI tools likho-cli knows how to connect, and where each keeps its MCP
+// settings. Two places per tool when it has them:
+//   global   every folder on this computer (the tool's own settings)
+//   project  one folder only (a settings file inside the project)
+// Formats follow each tool's documentation; they are also what Likho's
+// Connect page shows for doing it by hand (frontend/src/ConnectionsCards.jsx).
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const files = require("./files");
+
+const NAME = "likho";
+
+function onPath(cmd) {
+  const probe = process.platform === "win32" ? spawnSync("where", [cmd], { encoding: "utf8" }) : spawnSync("which", [cmd], { encoding: "utf8" });
+  return probe.status === 0 && Boolean((probe.stdout || "").trim());
+}
+
+function run(cmd, args) {
+  // .cmd shims on Windows need a shell; every argument here is ours, not the user's.
+  const result = spawnSync(cmd, args, { encoding: "utf8", shell: process.platform === "win32" });
+  return result.status === 0;
+}
+
+function vscodeUserDir(ctx) {
+  if (ctx.platform === "win32") return path.join(ctx.appData, "Code", "User");
+  if (ctx.platform === "darwin") return path.join(ctx.home, "Library", "Application Support", "Code", "User");
+  return path.join(ctx.home, ".config", "Code", "User");
+}
+
+function claudeDesktopDir(ctx) {
+  if (ctx.platform === "win32") return path.join(ctx.appData, "Claude");
+  if (ctx.platform === "darwin") return path.join(ctx.home, "Library", "Application Support", "Claude");
+  return path.join(ctx.home, ".config", "Claude");
+}
+
+/** A tool whose settings are one JSON file per place. */
+function jsonTool({ id, name, section, entry, globalFile, projectFile, detect, signIn }) {
+  return {
+    id,
+    name,
+    detect,
+    signIn,
+    project: Boolean(projectFile),
+    global: Boolean(globalFile),
+    file: (ctx, scope) => (scope === "project" ? path.join(ctx.cwd, projectFile) : globalFile(ctx)),
+    install(ctx, scope, url) {
+      return { file: this.file(ctx, scope), replaced: Boolean(files.setEntry(this.file(ctx, scope), section, NAME, entry(url))) };
+    },
+    remove(ctx, scope) {
+      return files.removeEntry(this.file(ctx, scope), section, NAME);
+    },
+    current(ctx, scope) {
+      const found = files.getEntry(this.file(ctx, scope), section, NAME);
+      return found ? found.url || found.httpUrl || found.serverUrl || "(set)" : null;
+    },
+  };
+}
+
+function tools(ctx) {
+  const list = [
+    {
+      id: "claude-code",
+      name: "Claude Code",
+      detect: () => ctx.which("claude") || fs.existsSync(path.join(ctx.home, ".claude.json")) || fs.existsSync(path.join(ctx.home, ".claude")),
+      signIn: "In Claude Code run /mcp, pick likho, choose Authenticate.",
+      project: true,
+      global: true,
+      file: (c, scope) => (scope === "project" ? path.join(c.cwd, ".mcp.json") : path.join(c.home, ".claude.json")),
+      install(c, scope, url) {
+        const file = this.file(c, scope);
+        if (scope === "global" && c.which("claude")) {
+          // Claude Code rewrites ~/.claude.json while it runs: let its own CLI edit it.
+          run("claude", ["mcp", "remove", NAME, "--scope", "user"]);
+          if (run("claude", ["mcp", "add", "--transport", "http", "--scope", "user", NAME, url])) return { file, replaced: false };
+        }
+        return { file, replaced: Boolean(files.setEntry(file, "mcpServers", NAME, { type: "http", url })) };
+      },
+      remove(c, scope) {
+        if (scope === "global" && c.which("claude") && run("claude", ["mcp", "remove", NAME, "--scope", "user"])) return true;
+        return files.removeEntry(this.file(c, scope), "mcpServers", NAME);
+      },
+      current(c, scope) {
+        const found = files.getEntry(this.file(c, scope), "mcpServers", NAME);
+        return found ? found.url || "(set)" : null;
+      },
+    },
+    {
+      id: "codex",
+      name: "Codex",
+      detect: () => ctx.which("codex") || fs.existsSync(path.join(ctx.home, ".codex")),
+      signIn: "Run: codex mcp login likho",
+      project: false,
+      global: true,
+      file: (c) => path.join(c.home, ".codex", "config.toml"),
+      install(c, scope, url) {
+        const file = this.file(c);
+        if (c.which("codex")) {
+          run("codex", ["mcp", "remove", NAME]);
+          if (run("codex", ["mcp", "add", NAME, "--url", url])) return { file, replaced: false };
+        }
+        const replaced = Boolean(files.getTomlServerUrl(file, NAME));
+        files.setTomlServer(file, NAME, url);
+        return { file, replaced };
+      },
+      remove(c) {
+        if (c.which("codex") && run("codex", ["mcp", "remove", NAME])) return true;
+        return files.removeTomlServer(this.file(c), NAME);
+      },
+      current(c) {
+        return files.getTomlServerUrl(this.file(c), NAME);
+      },
+    },
+    jsonTool({
+      id: "cursor",
+      name: "Cursor",
+      section: "mcpServers",
+      entry: (url) => ({ url }),
+      globalFile: (c) => path.join(c.home, ".cursor", "mcp.json"),
+      projectFile: path.join(".cursor", "mcp.json"),
+      detect: () => ctx.which("cursor") || fs.existsSync(path.join(ctx.home, ".cursor")),
+      signIn: "Open Cursor Settings, MCP, and click Connect next to likho.",
+    }),
+    jsonTool({
+      id: "vscode",
+      name: "VS Code",
+      section: "servers",
+      entry: (url) => ({ type: "http", url }),
+      globalFile: (c) => path.join(vscodeUserDir(c), "mcp.json"),
+      projectFile: path.join(".vscode", "mcp.json"),
+      detect: () => ctx.which("code") || fs.existsSync(vscodeUserDir(ctx)),
+      signIn: "In VS Code open the MCP servers list and click Start on likho.",
+    }),
+    jsonTool({
+      id: "gemini",
+      name: "Gemini CLI",
+      section: "mcpServers",
+      entry: (url) => ({ httpUrl: url }),
+      globalFile: (c) => path.join(c.home, ".gemini", "settings.json"),
+      projectFile: path.join(".gemini", "settings.json"),
+      detect: () => ctx.which("gemini") || fs.existsSync(path.join(ctx.home, ".gemini")),
+      signIn: "In Gemini CLI run: /mcp auth likho",
+    }),
+    jsonTool({
+      id: "opencode",
+      name: "opencode",
+      section: "mcp",
+      entry: (url) => ({ type: "remote", url, enabled: true }),
+      globalFile: (c) => path.join(c.home, ".config", "opencode", "opencode.json"),
+      projectFile: "opencode.json",
+      detect: () => ctx.which("opencode") || fs.existsSync(path.join(ctx.home, ".config", "opencode")),
+      signIn: "Run: opencode mcp auth likho",
+    }),
+    jsonTool({
+      id: "windsurf",
+      name: "Windsurf",
+      section: "mcpServers",
+      entry: (url) => ({ serverUrl: url }),
+      globalFile: (c) => path.join(c.home, ".codeium", "windsurf", "mcp_config.json"),
+      projectFile: null,
+      detect: () => fs.existsSync(path.join(ctx.home, ".codeium", "windsurf")),
+      signIn: "In Windsurf open Cascade's MCP list and refresh; sign in when asked.",
+    }),
+  ];
+  // Claude Desktop only takes remote servers through its Connectors screen.
+  list.push({
+    id: "claude-desktop",
+    name: "Claude Desktop",
+    manual: true,
+    detect: () => fs.existsSync(claudeDesktopDir(ctx)),
+    signIn: "In Claude Desktop: Settings, Connectors, Add custom connector, paste the URL.",
+    project: false,
+    global: true,
+  });
+  return list;
+}
+
+function context(overrides = {}) {
+  const home = process.env.LIKHO_CLI_HOME || require("node:os").homedir();
+  return {
+    home,
+    cwd: process.cwd(),
+    platform: process.platform,
+    appData: process.env.APPDATA || path.join(home, "AppData", "Roaming"),
+    which: onPath,
+    ...overrides,
+  };
+}
+
+module.exports = { tools, context, NAME };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "likho-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Connect every AI tool on your computer (Claude Code, Codex, Cursor, VS Code, Gemini CLI, opencode, Windsurf) to Likho in one command.",
+  "license": "MIT",
+  "homepage": "https://likho.me",
+  "bin": {
+    "likho": "bin/likho.js",
+    "likho-cli": "bin/likho.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "keywords": [
+    "likho",
+    "mcp",
+    "claude-code",
+    "codex",
+    "cursor",
+    "ai-agents"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  }
+}