likho-cli 0.3.0 → 0.4.0

package/README.md

@@ -24,6 +24,17 @@ 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.
 
+## Wake-ups (agents answer when tagged)
+
+`npx likho-cli` also asks: *let your agents here wake up when they're tagged,
+while this computer is on?* Yes installs a small helper in `~/.likho` that
+starts with your computer. When an agent whose chat is closed is tagged in
+Likho (and you switched *Wake up when tagged* on for it, in Project → Agents),
+the helper runs it in its project folder without a window (`claude -p`,
+`codex exec`, `gemini`) and its answer is posted in the room. Its key can only
+see and answer those wake-ups. `npx likho-cli helper` shows it;
+`npx likho-cli helper off` stops and removes it.
+
 ## Commands
 
 | Command | What it does |

package/bin/likho.js

@@ -15,6 +15,11 @@ const path = require("node:path");
 const { tools, context } = require("../lib/tools");
 const { chooseInBrowser } = require("../lib/browser");
 const { UnreadableFile } = require("../lib/files");
+const os = require("node:os");
+const helper = require("../lib/helperInstall");
+
+// Kinds of agents the wake helper can run without a window (lib/helper.js).
+const WAKEABLE = ["claude-code", "codex", "gemini"];
 
 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";
@@ -23,7 +28,8 @@ 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;
+    if (a === "status" || a === "remove" || a === "help" || a === "helper") opts.command = a;
+    else if (a === "off" && opts.command === "helper") opts.off = true;
     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;
@@ -57,6 +63,22 @@ async function answer(question) {
 const say = (line = "") => console.log(line);
 const mcpUrl = (opts, org) => `${opts.server}/mcp${org ? `?org=${encodeURIComponent(org)}` : ""}`;
 
+/**
+ * The host a "likho" entry really points at, when that isn't this Likho
+ * ("" when it is). A shared or downloaded project can carry a settings file
+ * whose "likho" leads to someone else's server; it's never trusted silently.
+ */
+function foreignHost(url, opts) {
+  try {
+    const u = new URL(url);
+    const ours = new URL(opts.server);
+    if (u.host === ours.host && u.protocol === ours.protocol && u.pathname.replace(/\/+$/, "") === "/mcp") return "";
+    return u.protocol === "https:" ? u.host : `${u.protocol}//${u.host} (not https)`;
+  } catch {
+    return String(url).slice(0, 60) || "an unreadable address";
+  }
+}
+
 /** The organization in a Likho address written by this tool ("" if none). */
 function orgOfUrl(url) {
   try {
@@ -120,15 +142,24 @@ async function connect(opts) {
     // 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));
+    // Entries named "likho" that point elsewhere are replaced, not kept.
+    const foreign = new Map([...existing].map(([id, url]) => [id, foreignHost(url, opts)]).filter(([, host]) => host));
+    for (const id of foreign.keys()) existing.delete(id);
+    if (foreign.size) {
+      const lines = usable.filter((t) => foreign.has(t.id)).map((t) => `${t.name}'s "likho" entry points to ${foreign.get(t.id)}, not Likho. It will be replaced.`);
+      ui.log.warn(lines.join("\n"));
+    }
     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 (foreign.has(t.id)) return `⚠ points to ${foreign.get(t.id)}, not Likho: will be replaced`;
       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));
+    let keepAll = false;
     if (opts.tools) {
       chosen = usable; // named on the command line: set up as asked
     } else if (interactive(opts)) {
@@ -137,52 +168,72 @@ async function connect(opts) {
         const next = await answer(ui.select({
           message: "Anything to change?",
           options: [
-            { value: "keep", label: "No, keep everything as it is" },
+            { value: "keep", label: "No, keep the tools as they are" },
             { value: "change", label: "Yes, switch a tool to another organization" },
           ],
           initialValue: "keep",
         }));
-        if (next === "keep") {
-          ui.outro("Nothing to do.");
-          return 0;
-        }
+        keepAll = next === "keep";
       }
-      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 (!keepAll) {
+        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,
         }));
-        if (what === "keep") chosen = chosen.filter((x) => x !== t);
+        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.");
+
+    // Wake-ups: agents here answer when tagged, while this computer is on.
+    // Needs the browser step (a person signs in to mint the helper's key).
+    let wantHelper = false;
+    const wakeable = found.filter((t) => WAKEABLE.includes(t.id));
+    if (wakeable.length && interactive(opts) && !opts.org) {
+      const already = helper.readConfig();
+      wantHelper = await answer(ui.confirm({
+        message: already
+          ? "Keep this computer waking your agents when they're tagged? (refreshes its sign-in)"
+          : "Let your agents here wake up when they're tagged, while this computer is on?",
+        initialValue: true,
+      }));
+    }
+    if (!chosen.length && !wantHelper) {
+      ui.outro(keepAll ? "Nothing to do." : "Nothing changed.");
       return 0;
     }
 
     // Which organization each lands in: picked in the browser, signed in.
     let orgFor;
+    let helperCodes = {};
+    const pair = wantHelper ? helper.pkce() : null;
     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) : "" },
+        {
+          scope,
+          tools: chosen.map((t) => t.id).join(","),
+          folder: scope === "project" ? path.basename(ctx.cwd) : "",
+          ...(pair ? { helper: "1", challenge: pair.challenge, machine: os.hostname().slice(0, 60) } : {}),
+        },
         {
           log: (line) => {
             const text = line.trim();
@@ -203,10 +254,7 @@ async function connect(opts) {
       // 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;
+      helperCodes = choice.helper || {};
     }
 
     const done = [];
@@ -229,15 +277,42 @@ async function connect(opts) {
       }
     }
 
+    let helperOn = false;
+    if (pair && Object.keys(helperCodes).length) {
+      try {
+        const orgs = [];
+        for (const code of Object.values(helperCodes)) {
+          const { key, org } = await helper.redeem(opts.server, code, pair.verifier);
+          orgs.push({ slug: org.slug, name: org.name, key });
+        }
+        helper.install(opts.server, orgs, isProjectFolder(ctx) ? ctx.cwd : "");
+        helperOn = true;
+        ui.log.success(`Wake-ups on for ${orgs.map((o) => o.name).join(", ")}: this computer wakes your agents when they're tagged, while it's on.`);
+      } catch (err) {
+        ui.log.error(`Couldn't set up wake-ups: ${err.message}. Run npx likho-cli again to retry.`);
+      }
+    }
+
     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"');
+    }
+    if (helperOn) {
+      const where = isProjectFolder(ctx)
+        ? `Agents are only woken in folders set up like this one (${path.basename(ctx.cwd)}): run npx likho-cli in each other project folder too.`
+        : "Agents are only woken in project folders you set up: run npx likho-cli inside each project folder whose agents should wake.";
+      ui.note(
+        `In Likho: Project → Agents → Wake up when tagged.\nSwitch it on for the agents that should answer while their chat is closed.\n\n${where}`,
+        "One more step: choose which agents wake up"
+      );
+    }
+    if (done.length || helperOn) {
+      ui.outro(done.length ? 'Then, in any chat: "join Likho"' : "Done.");
     } else {
       ui.outro("Nothing was connected.");
     }
-    return done.length ? 0 : 1;
+    return done.length || helperOn ? 0 : 1;
   } catch (err) {
     return cancelled(err);
   }
@@ -250,8 +325,9 @@ function status(opts) {
   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"}`);
+    const show = (url) => (!url ? "not connected" : foreignHost(url, opts) ? `⚠ ${url} (not Likho: run npx likho-cli to replace it)` : url);
+    if (t.global) rows.push(`all projects: ${show(t.current(ctx, "global"))}`);
+    if (t.project && inProject) rows.push(`this project: ${show(t.current(ctx, "project"))}`);
     say(`  ${t.name.padEnd(14)} ${t.detect() ? "" : "(not installed) "}${rows.join(" · ")}`);
   }
   say();
@@ -293,12 +369,40 @@ async function remove(opts) {
   }
 }
 
+/** `npx likho-cli helper` (is it on?) and `npx likho-cli helper off`. */
+function helperCommand(opts) {
+  const cfg = helper.readConfig();
+  if (opts.off) {
+    helper.uninstall();
+    say();
+    say("  Wake-ups are off on this computer: the helper is stopped and won't start with it.");
+    say();
+    return 0;
+  }
+  if (!cfg) {
+    say();
+    say("  Wake-ups aren't set up on this computer. Run npx likho-cli in a project folder and answer Yes.");
+    say();
+    return 0;
+  }
+  say();
+  say("  Likho wake helper");
+  say(`    Running:        ${helper.running() ? "yes" : "no (it starts with the computer)"}`);
+  say(`    Organizations:  ${cfg.orgs.map((o) => o.name || o.slug).join(", ")}`);
+  say(`    Starts with:    ${helper.startupFile()}`);
+  say("    Log:            ~/.likho/helper.log");
+  say("    Turn off:       npx likho-cli helper off");
+  say();
+  return 0;
+}
+
 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.
+  npx likho-cli helper     Is this computer waking your agents when tagged? (helper off: stop it)
 
   --here                   Only this project folder.
   --global                 All projects on this computer.
@@ -311,7 +415,7 @@ function help() {
 
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
-  const run = { connect, status, remove, help }[opts.command];
+  const run = { connect, status, remove, help, helper: helperCommand }[opts.command];
   process.exitCode = await run(opts);
 }
 

package/lib/helper.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// Likho wake helper: wakes your agents when they're tagged while their chat
+// is closed. Installed by `npx likho-cli` (copied to ~/.likho/helper.js) and
+// started with the computer. No dependencies: it must run on its own.
+//
+// Every ~15 s it asks Likho for work (/api/wake/next), with a key that can do
+// nothing else: see and answer wake jobs for agents you connected. A job runs
+// the agent's own tool in the agent's project folder without a window, with
+// the message as its prompt, and the answer goes back to the room.
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+
+const HOME = process.env.LIKHO_CLI_HOME || os.homedir();
+const DIR = path.join(HOME, ".likho");
+const CONFIG = path.join(DIR, "helper.json");
+const LOG = path.join(DIR, "helper.log");
+const PID = path.join(DIR, "helper.pid");
+const SESSIONS = path.join(DIR, "wake-sessions.json");
+const IDLE_MS = 15_000;
+const RUN_LIMIT_MS = 10 * 60_000;
+const MAX_REPLY = 20_000;
+
+// How each kind of agent runs without a window. Arguments are fixed: the
+// message only ever travels on standard input, never on a command line.
+const RUNNERS = {
+  "claude-code": (session) => ({ cmd: "claude", args: ["-p", "--output-format", "json", ...(session ? ["--resume", session] : [])] }),
+  codex: () => ({ cmd: "codex", args: ["exec", "--skip-git-repo-check", "-"] }),
+  gemini: () => ({ cmd: "gemini", args: [] }),
+};
+const LIMIT_TEXT = /usage limit|limit reached|rate limit|quota|too many requests|\b429\b/i;
+
+function log(line) {
+  try {
+    if (fs.existsSync(LOG) && fs.statSync(LOG).size > 1_000_000) fs.renameSync(LOG, `${LOG}.1`);
+    fs.appendFileSync(LOG, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // logging must never stop the helper
+  }
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** One helper per computer. */
+function takeLock() {
+  const other = Number(readJson(PID, 0));
+  if (other && other !== process.pid && alive(other)) return false;
+  fs.mkdirSync(DIR, { recursive: true });
+  fs.writeFileSync(PID, String(process.pid));
+  const release = () => {
+    try {
+      if (Number(readJson(PID, 0)) === process.pid) fs.unlinkSync(PID);
+    } catch {}
+  };
+  process.on("exit", release);
+  for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => process.exit(0));
+  return true;
+}
+
+async function call(cfg, org, method, url, body) {
+  const res = await fetch(`${cfg.server}${url}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${org.key}`,
+      "X-Likho-Helper": os.hostname().slice(0, 60),
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {
+    data = null;
+  }
+  return { status: res.status, data };
+}
+
+function kill(child) {
+  if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+  else child.kill("SIGKILL");
+}
+
+function run(cmd, args, { cwd, input, env }) {
+  return new Promise((resolve) => {
+    let out = "";
+    let err = "";
+    let child;
+    try {
+      child = spawn(cmd, args, { cwd, env, shell: process.platform === "win32", windowsHide: true });
+    } catch (e) {
+      resolve({ code: -1, out: "", err: e.message });
+      return;
+    }
+    const timer = setTimeout(() => {
+      err += "\n(stopped after 10 minutes)";
+      kill(child);
+    }, RUN_LIMIT_MS);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", (e) => (err += e.message));
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, out, err });
+    });
+    child.stdin.end(input);
+  });
+}
+
+// Only folders this person set up with likho-cli on this computer. The folder
+// in a job comes from Likho (where the agent registered); a project's path is
+// shared in an organization, so a teammate's agent could have set it. Never
+// run an agent somewhere you didn't choose.
+const norm = (p) => {
+  const r = path.resolve(String(p || ""));
+  return process.platform === "win32" ? r.toLowerCase() : r;
+};
+
+function allowedFolder(cfg, folder) {
+  const f = norm(folder);
+  return (cfg.folders || []).some((ok) => {
+    const a = norm(ok);
+    return f === a || f.startsWith(a.endsWith(path.sep) ? a : a + path.sep);
+  });
+}
+
+async function wake(cfg, org, job) {
+  const assistant = job.agent.assistant;
+  const finish = (body) => call(cfg, org, "POST", `/api/wake/jobs/${job.id}/finish`, body);
+  if (!RUNNERS[assistant]) return finish({ status: "failed", error: `this computer can't wake ${assistant || "this kind of"} agents yet` });
+  if (!job.folder || !fs.existsSync(job.folder)) {
+    return finish({ status: "failed", error: `its project folder isn't on this computer (${job.folder || "unknown"})` });
+  }
+  if (!allowedFolder(cfg, job.folder)) {
+    log(`refused: ${job.folder} isn't a folder set up for wake-ups`);
+    return finish({ status: "failed", error: "its folder isn't set up for wake-ups on this computer; run npx likho-cli in that folder" });
+  }
+  const sessions = readJson(SESSIONS, {});
+  const session = /^[\w-]{8,80}$/.test(sessions[job.agent.number] || "") ? sessions[job.agent.number] : "";
+  const { cmd, args } = RUNNERS[assistant](session);
+  // The PATH saved at setup (a computer's startup environment can be thinner).
+  // Windows spells it "Path": set the existing key, never add a second one.
+  const env = { ...process.env };
+  if (cfg.path) env[Object.keys(env).find((k) => k.toUpperCase() === "PATH") || "PATH"] = cfg.path;
+  log(`waking ${job.agent.name} (#${job.agent.number}) in ${job.folder} for #${job.room}`);
+  const result = await run(cmd, args, { cwd: job.folder, input: job.prompt, env });
+
+  let reply = result.out.trim();
+  if (assistant === "claude-code") {
+    try {
+      const parsed = JSON.parse(reply);
+      if (parsed.session_id) {
+        sessions[job.agent.number] = parsed.session_id;
+        fs.writeFileSync(SESSIONS, JSON.stringify(sessions, null, 2));
+      }
+      if (parsed.is_error && LIMIT_TEXT.test(String(parsed.result))) return finish({ status: "limited", retry_after: 3600 });
+      reply = String(parsed.result || "").trim();
+    } catch {
+      // not JSON: an error message, handled below
+    }
+  }
+  const all = `${result.out}\n${result.err}`;
+  if (!reply && LIMIT_TEXT.test(all)) return finish({ status: "limited", retry_after: 3600 });
+  if (result.code !== 0 && !reply) {
+    if (/not recognized|ENOENT|not found/i.test(result.err)) return finish({ status: "failed", error: `${cmd} isn't installed or isn't on this computer's PATH` });
+    return finish({ status: "failed", error: (result.err.trim().split("\n").pop() || `exited with ${result.code}`).slice(0, 250) });
+  }
+  if (!reply) return finish({ status: "failed", error: "it finished without an answer" });
+  log(`answered for ${job.agent.name}`);
+  return finish({ status: "done", reply: reply.slice(0, MAX_REPLY) });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+  if (!takeLock()) return;
+  log(`helper started (pid ${process.pid})`);
+  for (;;) {
+    const cfg = readJson(CONFIG, null);
+    if (!cfg || !Array.isArray(cfg.orgs) || !cfg.orgs.length) {
+      log("no organizations configured; stopping");
+      return;
+    }
+    let worked = false;
+    for (const org of cfg.orgs) {
+      try {
+        const { status, data } = await call(cfg, org, "GET", "/api/wake/next");
+        if (status === 401 || status === 403) {
+          if (!org.warned) log(`${org.slug}: Likho refused this computer's key (revoked?). Run npx likho-cli to set it up again.`);
+          org.warned = true;
+          continue;
+        }
+        if (data && data.job) {
+          await wake(cfg, org, data.job);
+          worked = true;
+        }
+      } catch (e) {
+        log(`${org.slug}: ${e.message}`); // offline or Likho asleep: try again later
+      }
+    }
+    await sleep(worked ? 1000 : IDLE_MS);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { RUNNERS, LIMIT_TEXT, allowedFolder };

package/lib/helperInstall.js

@@ -0,0 +1,139 @@
+// Installing the wake helper: its own copy in ~/.likho, a key per
+// organization (from a browser sign-in), and a way to start with the computer.
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { spawn, spawnSync } = require("node:child_process");
+
+const home = () => process.env.LIKHO_CLI_HOME || os.homedir();
+const dir = () => path.join(home(), ".likho");
+const configFile = () => path.join(dir(), "helper.json");
+const helperFile = () => path.join(dir(), "helper.js");
+const pidFile = () => path.join(dir(), "helper.pid");
+const LABEL = "me.likho.helper";
+
+function startupFile() {
+  if (process.platform === "win32") {
+    // LIKHO_CLI_HOME (tests) keeps even the startup entry inside that folder.
+    const appData = (!process.env.LIKHO_CLI_HOME && process.env.APPDATA) || path.join(home(), "AppData", "Roaming");
+    return path.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "likho-helper.vbs");
+  }
+  if (process.platform === "darwin") return path.join(home(), "Library", "LaunchAgents", `${LABEL}.plist`);
+  return path.join(home(), ".config", "autostart", "likho-helper.desktop");
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(configFile(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** PKCE pair for the browser sign-in: the challenge goes to the page, the verifier stays here. */
+function pkce() {
+  const verifier = crypto.randomBytes(48).toString("base64url");
+  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+async function redeem(server, code, verifier) {
+  const res = await fetch(`${server}/api/auth/mcp/redeem`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code, verifier }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || !data.api_key) throw new Error(data.error || `Likho said ${res.status}`);
+  return { key: data.api_key, org: data.workspace };
+}
+
+function running() {
+  try {
+    const pid = Number(fs.readFileSync(pidFile(), "utf8"));
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    return 0;
+  }
+}
+
+function stop() {
+  const pid = running();
+  if (!pid) return;
+  if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+  else {
+    try {
+      process.kill(pid);
+    } catch {}
+  }
+}
+
+function startNow() {
+  const child = spawn(process.execPath, [helperFile()], { detached: true, stdio: "ignore", windowsHide: true });
+  child.unref();
+}
+
+function writeStartup() {
+  const node = process.execPath;
+  const file = startupFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (process.platform === "win32") {
+    // A hidden window: wscript runs node with no console showing.
+    const q = (s) => s.replace(/"/g, '""');
+    fs.writeFileSync(file, `CreateObject("WScript.Shell").Run """${q(node)}"" ""${q(helperFile())}""", 0, False\r\n`);
+  } else if (process.platform === "darwin") {
+    const x = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+    fs.writeFileSync(file, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array><string>${x(node)}</string><string>${x(helperFile())}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict></plist>
+`);
+  } else {
+    fs.writeFileSync(file, `[Desktop Entry]\nType=Application\nName=Likho helper\nExec="${node}" "${helperFile()}"\nX-GNOME-Autostart-enabled=true\nNoDisplay=true\n`);
+  }
+}
+
+/**
+ * Save the organizations' keys and the folder this was run in, copy the
+ * helper, make it start with the computer, and (re)start it now.
+ * `orgs`: [{slug, name, key}].
+ */
+function install(server, orgs, folder) {
+  fs.mkdirSync(dir(), { recursive: true });
+  const current = readConfig() || { server, orgs: [] };
+  const merged = current.orgs.filter((o) => !orgs.some((n) => n.slug === o.slug));
+  // The folders agents may be woken in: only ones set up here, by this person.
+  const folders = [...new Set([...(current.folders || []), ...(folder ? [path.resolve(folder)] : [])])];
+  const config = { server, orgs: [...merged, ...orgs], folders, path: process.env.PATH || "" };
+  fs.writeFileSync(configFile(), JSON.stringify(config, null, 2), { mode: 0o600 });
+  fs.copyFileSync(path.join(__dirname, "helper.js"), helperFile());
+  writeStartup();
+  stop();
+  if (process.platform === "darwin") {
+    spawnSync("launchctl", ["unload", startupFile()], { stdio: "ignore" });
+    spawnSync("launchctl", ["load", "-w", startupFile()], { stdio: "ignore" });
+  } else {
+    startNow();
+  }
+  return config;
+}
+
+function uninstall() {
+  stop();
+  if (process.platform === "darwin") spawnSync("launchctl", ["unload", startupFile()], { stdio: "ignore" });
+  for (const f of [startupFile(), configFile(), helperFile(), pidFile()]) {
+    try {
+      fs.unlinkSync(f);
+    } catch {}
+  }
+}
+
+module.exports = { pkce, redeem, install, uninstall, readConfig, running, startupFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "likho-cli",
-  "version": "0.3.0",
+  "version": "0.4.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",