roger-roger 0.1.1 → 0.1.2

package/README.md

@@ -16,6 +16,8 @@ It asks a few questions in the terminal and does the rest. First it offers to pu
 
 If you'd rather install first and set up after, that works too: `npm install -g roger-roger`, then `roger-roger install`.
 
+To take it off again, `npx roger-roger@latest uninstall` (or `roger-roger uninstall`): it lists what it finds, you tick what should go, and it removes the hooks, the skill links, the Herdr plugin, the daemon and the tray, your settings and tokens, and the global command. The Slack CLI is offered too, unticked. `roger-roger help` shows every command, and `roger-roger help notify` one command's flags.
+
 Other ways in:
 
 - **skills.sh**: `npx skills add code-red-app/roger-roger` copies the skill alone. The agent runs it as `node <skill-dir>/scripts/roger-roger.mjs` and, on first use, asks you to run `npx roger-roger install`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roger-roger",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Bring yourself back to the conversation: your coding agents reach you by Slack, a sound or a spoken line when they finish, get stuck, or need a decision, and you answer from your phone.",
   "type": "module",
   "bin": {

package/skills/roger-roger/SKILL.md

@@ -261,6 +261,8 @@ Judge it by what happens if you are wrong, not by whether it feels routine. A fo
 ## Other commands
 
 - `install`: the interactive setup, for the user to run in a terminal (section 1). `install --yes` asks nothing: it links the skill for every agent on the machine and registers with Herdr, and prints what it did.
+- `uninstall`: takes it out again, for the user to run in a terminal (`npx roger-roger@latest uninstall`): hooks, skill links, the Herdr plugin, the daemon and the tray, settings and tokens, the global command. `--yes` removes all of that without asking (`--slack-cli` adds the Slack CLI). Never run it for the user unasked.
+- `help [command]`: the commands, and one command's flags.
 - `status`: current config, whether the tokens are present, the daemon, running sessions, and every valid option value.
 - `slack-setup [status|install-cli|login|create]`: the Slack steps `install` runs, one at a time, for repairing a connection by hand. `create` again is safe: it updates the same app, which is what to do after the manifest changed or when a scope is missing.
 - `sessions [--all]`: which agents are running, what each is called, and what each is doing. `sessions rename sage plum` gives one a different name (the user's request, not yours to change on a whim).

package/skills/roger-roger/herdr-plugin.toml

@@ -6,7 +6,7 @@
 
 id = "roger-roger"
 name = "roger-roger"
-version = "0.1.1"
+version = "0.1.2"
 min_herdr_version = "0.9.0"
 description = "Slack, a sound or a spoken line from the agents in your panes, and questions you answer from your phone"
 platforms = ["linux", "macos", "windows"]

package/skills/roger-roger/scripts/help.mjs

@@ -0,0 +1,210 @@
+// `roger-roger help`: the commands, grouped by what they are for, laid out to the terminal's width
+// and coloured when it is one. `help <command>` shows that command's flags. The text lives here as
+// data, so the overview, the per-command pages and the tests all read the same thing.
+
+import { VERSION } from "./lib.mjs";
+import { coloursOn, makeStyle, width } from "./tui.mjs";
+
+export const TAGLINE = "Bring yourself back to the conversation: your agents reach you by Slack, a sound, or a voice.";
+
+/** Every command: where it belongs, how it is called, what it does, and (for the busy ones) its flags. */
+export const COMMANDS = [
+  // ---- setting up
+  { section: "Setting up", name: "install", usage: "[--yes]", summary: "Set everything up in the terminal: the command on your PATH, the skill for every agent, Herdr, Slack, the sound and the voice, hooks, tray. Run it again to change anything. --yes asks nothing and only links the skill.", flags: [["--yes", "no questions: link the skill for every agent on the machine and register with Herdr, then print what was done"]] },
+  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"]] },
+  { section: "Setting up", name: "status", usage: "", summary: "Settings, whether the tokens are there, the daemon, who is running, and every valid option value." },
+  {
+    section: "Setting up", name: "setup", usage: "[flags]", summary: "Change any setting; the rest are kept.",
+    flags: [
+      ["--methods slack,sound,speech", "how to be reached, any combination"],
+      ["--slack-target U0123|C0123|#name", "your member ID for DMs, or a channel"],
+      ["--slack-mention U0123", "who to mention in channel posts"],
+      ["--sound NAME", "chime, ding, marimba, bubble, alert"],
+      ["--voice NAME", "a voice of the speech provider (see voices)"],
+      ["--speech auto|brief|same", "what is spoken: the agent's choice, one sentence, or the whole message"],
+      ["--when auto|done-and-blocked|blocked-only|on-request", "when agents notify"],
+      ["--speech-provider gemini|openai|elevenlabs", "who makes the voice"],
+      ["--speech-key-var NAME|auto", "the environment variable holding that provider's key"],
+      ["--model ID", "the provider's speech model"],
+      ["--speech-volume 0-150", "the voice's volume"],
+      ["--duck on|off, --duck-level 0-100", "turn other sound down while the voice speaks (Windows)"],
+      ["--local-fallback true|false", "use the computer's voice when the provider fails"],
+      ["--say-who on|off", "start a spoken line with the agent's name"],
+      ["--session-label on|off", "the small name · machine · agent line under Slack messages"],
+      ["--remind 15m|off", "remind about an unanswered question after this long"],
+      ["--on-expire recommended|nothing", "what an unanswered question settles as"],
+      ["--quiet-hours 22:00-08:00|off, --quiet-mute speech,sound", "when, and what, to keep quiet"],
+      ["--permission-pings on|off", "also ping for ordinary permission prompts in the terminal"],
+      ["--terminal-wait 20s", "how long a terminal question waits before the ping (OpenCode, Codex)"],
+      ["--tray auto|off", "start the tray with the daemon once it is installed"],
+      ["--notes TEXT", "anything else the agent should follow"],
+    ],
+  },
+  { section: "Setting up", name: "slack-setup", usage: "[status|install-cli|login|create]", summary: "The Slack steps one at a time, for repairing a connection by hand. `next` says which comes next." },
+  { section: "Setting up", name: "hooks", usage: "status|install|uninstall [claude|opencode|codex|all]", summary: "Ping you when an agent asks a question in its own terminal and can't tell you itself." },
+  { section: "Setting up", name: "daemon", usage: "status|start|stop", summary: "The one process behind everything. It starts on demand; this is for looking at it, or restarting it after a change to the code." },
+  { section: "Setting up", name: "tray", usage: "status|start|stop|install", summary: "An icon showing every agent, a panel behind it, snooze on right-click. The native part is installed on request (about 4 MB)." },
+
+  // ---- reaching the user
+  {
+    section: "Reaching the user", name: "notify", usage: "--kind K --message TEXT [flags]", summary: "Post to Slack, play the sound, speak the line: any or all, as configured.",
+    flags: [
+      ["--kind done|blocked|input|milestone|error|info", "sets the Slack emoji"],
+      ["--message TEXT", "the written message, self-contained (Slack mrkdwn works)"],
+      ["--say TEXT", "the spoken line; short, no paths or URLs. Gemini tone tags like [positive] work"],
+      ["--only sound,speech", "this call only, some of the methods"],
+      ["--project NAME", "the label shown in Slack (default: the directory name)"],
+      ["--attach FILE", "a file to post with the message; repeatable"],
+      ["--summary, --field \"Label=value\"", "an end-of-task card with key facts, how long it took, and every decision"],
+      ["--actions \"A|B\", --recommend A", "follow-up buttons; `wait` the returned id like a question"],
+      ["--reply-to TS", "post in a thread: the replyTo that came with the user's message"],
+      ["--then-listen [25m]", "post, then stay reachable until the user says something"],
+    ],
+    example: "roger-roger notify --kind done --message \"Tests green, PR ready.\" --say \"[positive] All green.\" --session \"billing refactor\" --agent-model \"opus 5\"",
+  },
+  { section: "Reaching the user", name: "progress", usage: "--message TEXT [--key NAME] [--done]", summary: "One Slack message, edited in place as the work moves on, with Pause, Stop and Note buttons." },
+  { section: "Reaching the user", name: "control", usage: "[--key NAME] [--wait DURATION]", summary: "Read Pause, Stop and new messages without posting. --wait blocks while paused." },
+  { section: "Reaching the user", name: "listen", usage: "[--wait 25m]", summary: "Park until the user says something. Run it in the background as the last thing you do." },
+  { section: "Reaching the user", name: "snooze", usage: "[1h|off]", summary: "Sound and speech off for a while; Slack keeps working." },
+
+  // ---- asking
+  {
+    section: "Asking the user", name: "ask", usage: "--question TEXT --choices \"A|B\" [flags]", summary: "A question with a button per option in Slack. Returns an id at once; `wait` for the answer.",
+    flags: [
+      ["--question TEXT", "self-contained"],
+      ["--choices \"A|B\"", "2 to 10 options"],
+      ["--recommend A", "the option you'd pick, shown in green; with --multi, several"],
+      ["--multi", "checkboxes and a Submit button instead of one button per option"],
+      ["--details TEXT", "context under the question"],
+      ["--draft TEXT | --draft-file PATH", "text to approve or edit before use: a commit message, a PR description"],
+      ["--expires 45m", "how long the question stays open"],
+      ["--on-expire recommended|nothing", "settle as the recommended option, or just expire. Use nothing for anything hard to undo"],
+      ["--remind 15m|off", "reminders for this question"],
+      ["--other true|false", "the Other… button for a typed answer"],
+      ["--reply-to TS", "ask in a thread"],
+      ["--wait [DURATION]", "block until settled, as `wait` would"],
+      ["--say, --only, --kind, --attach", "as for notify"],
+    ],
+    example: "roger-roger ask --question \"Deploy now?\" --choices \"Yes|Tomorrow|No\" --recommend Yes --on-expire nothing --wait 10m",
+  },
+  { section: "Asking the user", name: "wait", usage: "ID [--timeout DURATION]", summary: "Block until answered, expired or cancelled. Exit 0 answered, 5 expired or cancelled, 4 still pending after --timeout, 6 the user sent a message instead." },
+  { section: "Asking the user", name: "check", usage: "ID", summary: "The question's state, without waiting." },
+  { section: "Asking the user", name: "cancel", usage: "ID [--reason TEXT]", summary: "Withdraw a question; its Slack message stops offering buttons." },
+  { section: "Asking the user", name: "decisions", usage: "[--all]", summary: "Pending questions; --all includes recent closed ones." },
+
+  // ---- sessions
+  { section: "Sessions", name: "sessions", usage: "[--all] | rename NAME NEWNAME", summary: "Who is running and what each is called. Rename gives one a different colour name." },
+  { section: "Sessions", name: "end", usage: "[NAME]", summary: "This session is finished; stop routing messages to it." },
+  { section: "Sessions", name: "inbox", usage: "", summary: "Messages the user sent this session, and anything left for the next agent." },
+
+  // ---- sounds and voices
+  { section: "Sounds and voices", name: "play", usage: "[SOUND]", summary: "Hear a sound (default: the configured one)." },
+  { section: "Sounds and voices", name: "say", usage: "TEXT [--voice NAME] [--local | --test]", summary: "Hear a voice. --test insists on the provider: its voice or an error, never the computer's." },
+  { section: "Sounds and voices", name: "voices", usage: "[--refresh]", summary: "The provider's voices and models; --refresh asks the provider." },
+  { section: "Sounds and voices", name: "preview-sounds", usage: "[SOUND...] [--voice NAME] [--local]", summary: "Each sound announced by name, then played." },
+  { section: "Sounds and voices", name: "preview-voices", usage: "[VOICE...] [--all] [--text TEXT]", summary: "Each voice introduces itself." },
+];
+
+export const ANY_COMMAND = [
+  ["--session NAME", "what this work is called, and how the session is recognised between commands: always pass it"],
+  ["--agent-model MODEL", "your model, short: \"opus 5\", \"gpt-6\""],
+  ["--agent NAME", "your agent product, when it can't be detected"],
+  ["--session-id ID, --agent-pid PID", "when the agent knows better than the environment does"],
+];
+
+/** Text folded to `max` columns at spaces; a word longer than that stands alone. */
+export function wrap(text, max) {
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && width(line) + 1 + width(word) > max) {
+      lines.push(line);
+      line = word;
+    } else line = line ? `${line} ${word}` : word;
+  }
+  if (line) lines.push(line);
+  return lines.length ? lines : [""];
+}
+
+/** A two-column table: the left column padded to one width, the right wrapped beside it. */
+function table(rows, { indent, columns, c, left = (s) => s, right = (s) => s, gap = 3, maxLeft = 34 }) {
+  const leftWidth = Math.min(maxLeft, Math.max(...rows.map(([l]) => width(l))));
+  const rightWidth = Math.max(20, columns - indent - leftWidth - gap);
+  const out = [];
+  for (const [l, r] of rows) {
+    const lines = wrap(r, rightWidth);
+    if (width(l) > leftWidth) {
+      out.push(" ".repeat(indent) + left(l));
+      for (const line of lines) out.push(" ".repeat(indent + leftWidth + gap) + right(line));
+      continue;
+    }
+    const pad = " ".repeat(leftWidth - width(l) + gap);
+    out.push(" ".repeat(indent) + left(l) + pad + right(lines[0]));
+    for (const line of lines.slice(1)) out.push(" ".repeat(indent + leftWidth + gap) + right(line));
+  }
+  return out;
+}
+
+/** The overview, or one command's page. Returns the text; the caller prints it. */
+export function helpText(command = "", { columns = process.stdout.columns || 100, colours = coloursOn() } = {}) {
+  const c = makeStyle(colours);
+  const cols = Math.max(60, Math.min(columns, 110));
+  const out = [""];
+  const title = `${c.bold("roger-roger")}${VERSION ? "  " + c.dim(VERSION) : ""}`;
+
+  if (command) {
+    const cmd = COMMANDS.find((x) => x.name === command);
+    if (!cmd) return null;
+    out.push(`  ${title}`);
+    out.push("");
+    out.push(`  ${c.cyan(c.bold(cmd.name))}${cmd.usage ? " " + c.dim(cmd.usage) : ""}`);
+    for (const line of wrap(cmd.summary, cols - 2)) out.push(`  ${line}`);
+    if (cmd.flags?.length) {
+      out.push("");
+      out.push(`  ${c.bold("Flags")}`);
+      out.push(...table(cmd.flags, { indent: 4, columns: cols, c, left: c.cyan }));
+    }
+    if (cmd.example) {
+      out.push("");
+      out.push(`  ${c.bold("Example")}`);
+      for (const line of wrap(cmd.example, cols - 4)) out.push(`    ${c.dim(line)}`);
+    }
+    out.push("");
+    out.push(`  ${c.bold("Any command")}`);
+    out.push(...table(ANY_COMMAND, { indent: 4, columns: cols, c, left: c.cyan }));
+    out.push("");
+    return out.join("\n") + "\n";
+  }
+
+  out.push(`  ${title}`);
+  for (const line of wrap(TAGLINE, cols - 2)) out.push(`  ${c.dim(line)}`);
+  out.push("");
+  out.push(`  ${c.bold("Usage")}`);
+  out.push(...table([["roger-roger <command> [flags]", "every command prints one JSON object"], ["roger-roger help <command>", "that command's flags"]], {
+    indent: 4, columns: cols, c, maxLeft: 30, left: (l) => c.cyan("roger-roger") + " " + c.dim(l.slice("roger-roger ".length)),
+  }));
+  const sections = [...new Set(COMMANDS.map((x) => x.section))];
+  for (const section of sections) {
+    out.push("");
+    out.push(`  ${c.bold(section)}`);
+    const rows = COMMANDS.filter((x) => x.section === section).map((x) => [x.usage ? `${x.name} ${x.usage}` : x.name, x.summary]);
+    const styled = rows.map(([l, r]) => [l, r]);
+    out.push(...table(styled, {
+      indent: 4, columns: cols, c, maxLeft: 30,
+      left: (l) => {
+        const [name, ...rest] = l.split(" ");
+        return c.cyan(name) + (rest.length ? " " + c.dim(rest.join(" ")) : "");
+      },
+    }));
+  }
+  out.push("");
+  out.push(`  ${c.bold("Any command")}`);
+  out.push(...table(ANY_COMMAND, { indent: 4, columns: cols, c, left: c.cyan, maxLeft: 30 }));
+  out.push("");
+  out.push(`  ${c.bold("Start here")}`);
+  out.push(...table([["npx roger-roger@latest install", "with nothing installed yet"], ["roger-roger install", "once the command is on your PATH; the same setup, to change anything"]], {
+    indent: 4, columns: cols, c, maxLeft: 30, left: c.cyan, right: c.dim,
+  }));
+  out.push("");
+  return out.join("\n") + "\n";
+}

package/skills/roger-roger/scripts/install.mjs

@@ -11,23 +11,15 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { SKILL_DIR, VOICES, applySetup, configPath, listSounds, loadConfig, saveConfig, voiceSample } from "./lib.mjs";
-import { PROVIDERS, SPEECH_SETUP, catalog, keyFor } from "./tts.mjs";
-import { saveKey } from "./speechkey.mjs";
+import { SKILL_DIR, VERSION, VOICES, applySetup, configPath, listSounds, loadConfig, rogerRogerHome, saveConfig, voiceSample } from "./lib.mjs";
+import { PROVIDERS, SPEECH_SETUP, catalog } from "./tts.mjs";
+import { envValue, hasSavedKey, saveKey } from "./speechkey.mjs";
 import { createApp, loginFinish, loginStart, setupStatus } from "./slackapp.mjs";
-import { installCli } from "./slackcli.mjs";
-import { call } from "./client.mjs";
+import { cliInstallDir, findCli, installCli } from "./slackcli.mjs";
+import { call, connect, request } from "./client.mjs";
 import { identity } from "./agent.mjs";
 import { Cancelled, createUI } from "./tui.mjs";
 
-export const VERSION = (() => {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(SKILL_DIR, "..", "..", "package.json"), "utf8")).version ?? "";
-  } catch {
-    return "";
-  }
-})();
-
 // ---------------------------------------------------------------- where skills live
 
 /** The agents that read skills from a folder in the home directory, and where. */
@@ -318,24 +310,43 @@ async function chooseSpeech(ui, { config, persist }) {
   const p = PROVIDERS[provider];
   // Saved now so the previews below speak with this provider, not the one configured before.
   await persist({ "speech-provider": provider });
-  let key = keyFor({ speechProvider: provider, speechKeyVar: config?.speechProvider === provider ? config?.speechKeyVar ?? "" : "" });
-  if (key.value) {
-    ui.done(`${p.label} key found`, `in ${key.name}`);
-  } else {
-    const pasted = await ui.text({
-      message: `${p.label} API key`,
-      mask: true,
-      placeholder: "paste it, or leave empty to use the computer's own voice for now",
-    });
+
+  // Where the key is: the user says, rather than the setup assuming from what happens to be set.
+  const keyFile = path.join(rogerRogerHome(), "keys.json");
+  const chosenBefore = config?.speechProvider === provider ? String(config?.speechKeyVar ?? "") : "";
+  const describe = (name) => (process.env[name] ? "set in your environment" : hasSavedKey(name) ? "a key pasted into an earlier setup" : envValue(name) ? "set in your saved variables" : "not set");
+  const known = [...new Set([...p.keyVars, ...(chosenBefore ? [chosenBefore] : [])])];
+  const pick = await ui.select({
+    message: `Where is your ${p.label} API key?`,
+    initial: chosenBefore ? `var:${chosenBefore}` : known.find((name) => envValue(name)) ? `var:${known.find((name) => envValue(name))}` : "paste",
+    choices: [
+      ...known.map((name) => ({ value: `var:${name}`, label: name, hint: describe(name) })),
+      { value: "other", label: "Another variable…", hint: "you name it" },
+      { value: "paste", label: "Paste it now", hint: `kept in ${keyFile}, readable by you only` },
+      { value: "none", label: "No key for now", hint: "the computer's own voice speaks until there is one" },
+    ],
+  });
+  let keyVar = "";
+  let hasKey = false;
+  if (pick.startsWith("var:") || pick === "other") {
+    keyVar = pick === "other"
+      ? (await ui.text({ message: "Which variable?", placeholder: "MY_GEMINI_KEY", validate: (v) => (/^[A-Za-z_][A-Za-z0-9_]*$/.test(v) ? "" : "a variable name: letters, digits and underscores") })).toUpperCase()
+      : pick.slice(4);
+    hasKey = Boolean(envValue(keyVar));
+    if (hasKey) ui.done(`The key in ${keyVar} will be used`);
+    else ui.done(`${keyVar} is empty right now`, "set it and the voice will work; the computer's own voice speaks until then");
+  } else if (pick === "paste") {
+    const pasted = await ui.text({ message: `${p.label} API key`, mask: true, placeholder: "paste it, or leave empty for no key" });
     if (pasted) {
-      const file = saveKey(p.keyVars[0], pasted);
-      key = { name: p.keyVars[0], value: pasted };
-      ui.done("Key saved", `${file}; setting ${p.keyVars[0]} in your environment works too`);
-    } else {
-      ui.done("No key", "the computer's own voice will speak until a key is set");
-    }
+      saveKey(p.keyVars[0], pasted);
+      hasKey = true;
+      ui.done("Key saved", `${keyFile}; setting ${p.keyVars[0]} in your environment later works too`);
+    } else ui.done("Nothing pasted", "the computer's own voice speaks until a key is set");
+  } else {
+    ui.done("No key", "the computer's own voice speaks until a key is set");
   }
-  const hasKey = Boolean(key.value);
+  // The named variable, or the provider's usual ones when the key was pasted or there is none.
+  await persist({ "speech-key-var": keyVar || "auto" });
 
   const all = catalog(provider).voices;
   const choice = (v) => ({
@@ -616,6 +627,266 @@ export async function runInstall(args, { script, hooks, input = process.stdin, o
   }
 }
 
+// ---------------------------------------------------------------- uninstall
+
+/** The skill as agents see it: links (always ours, by name) and folders that hold a SKILL.md. */
+export function skillFootprint(home = os.homedir(), fsx = fs) {
+  return skillLinks(home).filter((a) => {
+    try {
+      const st = fsx.lstatSync(a.link);
+      return st.isSymbolicLink() || (st.isDirectory() && fsx.existsSync(path.join(a.link, "SKILL.md")));
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Remove a link, or a copy. */
+export function removeSkillLink(link, fsx = fs) {
+  if (fsx.lstatSync(link).isSymbolicLink()) fsx.unlinkSync(link);
+  else fsx.rmSync(link, { recursive: true, force: true });
+}
+
+/** Whether Herdr has the plugin, so uninstall can say so rather than guess. */
+export function herdrHasPlugin(herdr) {
+  try {
+    const r = spawnSync(herdr.command, ["plugin", "list", "--json"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+    return (JSON.parse(r.stdout)?.result?.plugins ?? []).some((p) => p.plugin_id === "roger-roger");
+  } catch {
+    return false;
+  }
+}
+
+export function herdrUnlink(herdr) {
+  const r = spawnSync(herdr.command, ["plugin", "unlink", "roger-roger"], { encoding: "utf8", windowsHide: true, timeout: 20_000 });
+  if (r.status === 0) return { ok: true };
+  const text = `${r.stderr}${r.stdout}`.trim();
+  let message = text;
+  try {
+    message = JSON.parse(text)?.error?.message ?? text;
+  } catch {}
+  return /not (found|linked|installed)|unknown plugin/i.test(message) ? { ok: true, note: message } : { ok: false, error: message };
+}
+
+/** `npm uninstall -g roger-roger`. Throws with npm's last words when it fails. */
+export function uninstallGlobally(env = process.env) {
+  const r = npmSync(["uninstall", "-g", "roger-roger", "--no-audit", "--no-fund", "--loglevel", "error"], env, 300_000);
+  if (r.status !== 0) throw new Error((r.stderr || r.stdout || r.error?.message || `npm exited with ${r.status}`).trim().split(/\r?\n/).slice(-3).join(" "));
+  return r.stdout.trim();
+}
+
+/** Where the Slack CLI that `install` put on the machine is, if it is there at all. */
+export async function slackCliFootprint(home = os.homedir()) {
+  const dir = cliInstallDir();
+  const cli = await findCli();
+  const ours = Boolean(cli && norm(cli.command).startsWith(norm(dir)));
+  return { dir, login: path.join(home, ".slack"), cli, ours, present: ours || fs.existsSync(dir) };
+}
+
+/** Take the Slack CLI out: the binary, its login, and (Windows) the PATH entry `install` added. */
+export function removeSlackCli({ home = os.homedir(), fsx = fs } = {}) {
+  const { dir, login } = { dir: cliInstallDir(), login: path.join(home, ".slack") };
+  fsx.rmSync(dir, { recursive: true, force: true });
+  fsx.rmSync(login, { recursive: true, force: true });
+  if (process.platform === "win32") {
+    spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command",
+      "$p = [Environment]::GetEnvironmentVariable('Path', 'User'); $b = Join-Path $env:AG_DIR 'bin'; " +
+      "$new = ($p -split ';' | Where-Object { $_ -and $_.ToLower() -ne $b.ToLower() }) -join ';'; " +
+      "if ($new -ne $p) { [Environment]::SetEnvironmentVariable('Path', $new, 'User') }",
+    ], { env: { ...process.env, AG_DIR: dir }, windowsHide: true, timeout: 20_000 });
+  } else {
+    const link = path.join(home, ".local", "bin", "slack");
+    try {
+      if (norm(fsx.readlinkSync(link)).startsWith(norm(dir))) fsx.unlinkSync(link);
+    } catch {}
+  }
+}
+
+/** Stop the tray and the daemon if one is running; never start one to do it. */
+async function stopDaemon(env = process.env) {
+  let socket;
+  try {
+    socket = await connect({ start: false, env });
+  } catch {
+    return false;
+  }
+  try {
+    await request(socket, { cmd: "tray", args: { _: ["stop"] } }).catch(() => {});
+    await request(socket, { cmd: "stop" }).catch(() => {});
+    return true;
+  } finally {
+    socket.end();
+  }
+}
+
+/** What is on this machine, so uninstall can offer exactly that. */
+export async function uninstallFindings({ home = os.homedir(), env = process.env, hooks = null, script = "" } = {}) {
+  const herdr = findHerdr(env);
+  const hookAgents = Object.entries(hooks?.agents ?? {}).filter(([, a]) => {
+    try {
+      return a.status({ script }).installed || a.status({ script }).partial;
+    } catch {
+      return false;
+    }
+  }).map(([name]) => name);
+  const global = globalCopy(env);
+  return {
+    links: skillFootprint(home),
+    herdr: herdr && herdrHasPlugin(herdr) ? herdr : null,
+    hookAgents,
+    home: [rogerRogerHome(env), path.join(home, ".attention")].filter((d) => fs.existsSync(d)),
+    global: global?.present ? global : null,
+    slackCli: await slackCliFootprint(home),
+  };
+}
+
+/** Everything but the Slack CLI, with no questions. Returns what was done. */
+export async function quietUninstall({ home = os.homedir(), env = process.env, hooks = null, script = "", slackCli = false } = {}) {
+  const found = await uninstallFindings({ home, env, hooks, script });
+  const done = { daemonStopped: await stopDaemon(env), hooks: [], links: [], herdr: null, home: [], slackCli: false, global: null };
+  for (const name of found.hookAgents) {
+    try {
+      hooks.agents[name].uninstall();
+      done.hooks.push(name);
+    } catch (e) {
+      done.hooks.push({ agent: name, error: e.message });
+    }
+  }
+  if (found.herdr) done.herdr = herdrUnlink(found.herdr);
+  for (const a of found.links) {
+    try {
+      removeSkillLink(a.link);
+      done.links.push(a.link);
+    } catch (e) {
+      done.links.push({ link: a.link, error: e.message });
+    }
+  }
+  for (const dir of found.home) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    done.home.push(dir);
+  }
+  if (slackCli && found.slackCli.present) {
+    removeSlackCli({ home });
+    done.slackCli = true;
+  }
+  if (found.global) {
+    try {
+      uninstallGlobally(env);
+      done.global = { removed: true, dir: found.global.dir };
+    } catch (e) {
+      done.global = { removed: false, error: e.message };
+    }
+  }
+  return done;
+}
+
+/** The conversation for taking it out. Returns the process exit code. */
+export async function runUninstall(args, { script, hooks, input = process.stdin, output = process.stdout, env = process.env, home = os.homedir() } = {}) {
+  const ui = createUI({ input, output, env });
+  const c = ui.style;
+
+  if (args.yes || !ui.interactive) {
+    const done = await quietUninstall({ home, env, hooks, script, slackCli: Boolean(args["slack-cli"]) });
+    output.write(JSON.stringify({ ok: true, ...done }, null, 2) + "\n");
+    return 0;
+  }
+
+  try {
+    ui.intro(`roger-roger uninstall ${VERSION ? c.dim(VERSION) : ""}`, "Takes roger-roger off this machine. You choose what goes.");
+    const found = await ui.run("Looking around", () => uninstallFindings({ home, env, hooks, script }), { done: () => "Looked around" });
+    const labels = { claude: "Claude Code", opencode: "OpenCode", codex: "Codex" };
+    const choices = [];
+    if (found.links.length) choices.push({ value: "links", label: "The skill, for agents", hint: found.links.map((a) => a.label).join(", "), checked: true });
+    if (found.hookAgents.length) choices.push({ value: "hooks", label: "Terminal-question hooks", hint: found.hookAgents.map((n) => labels[n] ?? n).join(", "), checked: true });
+    if (found.herdr) choices.push({ value: "herdr", label: "The Herdr plugin", hint: "herdr plugin unlink", checked: true });
+    if (found.home.length) choices.push({ value: "home", label: "Settings, Slack tokens, state", hint: found.home.join(", "), checked: true });
+    if (found.global) choices.push({ value: "global", label: "The roger-roger command", hint: `npm uninstall -g (${found.global.dir})`, checked: true });
+    if (found.slackCli.present) choices.push({ value: "slack-cli", label: "The Slack CLI", hint: `${found.slackCli.dir} and its login in ~/.slack; Slack's tool, so off by default`, checked: false });
+    if (!choices.length) {
+      ui.outro([c.bold("Nothing of roger-roger's is on this machine."), "", "If it is somewhere unusual, remove it by hand, and see `roger-roger help uninstall`."]);
+      return 0;
+    }
+    const what = await ui.multiselect({ message: "What should go?", choices });
+    if (!what.length) {
+      ui.outro([c.bold("Nothing removed.")]);
+      return 0;
+    }
+    const sure = await ui.confirm({ message: "Remove that now?", hint: "there is no undo", initial: true });
+    if (!sure) {
+      ui.outro([c.bold("Nothing removed.")]);
+      return 0;
+    }
+
+    const removed = [];
+    if (await stopDaemon(env)) ui.done("Stopped the daemon and the tray");
+    if (what.includes("hooks")) {
+      for (const name of found.hookAgents) {
+        try {
+          hooks.agents[name].uninstall();
+          ui.done(`${labels[name] ?? name}: hooks removed`);
+          removed.push(`hooks: ${labels[name] ?? name}`);
+        } catch (e) {
+          ui.failed(`${labels[name] ?? name}: hooks not removed`, e.message);
+        }
+      }
+    }
+    if (what.includes("herdr")) {
+      const r = herdrUnlink(found.herdr);
+      if (r.ok) {
+        ui.done("Herdr plugin unlinked", r.note ?? "");
+        removed.push("Herdr plugin");
+      } else ui.failed("Herdr would not unlink the plugin", r.error);
+    }
+    if (what.includes("links")) {
+      for (const a of found.links) {
+        try {
+          removeSkillLink(a.link);
+          ui.done(`${a.label}: skill removed`, a.link);
+          removed.push(a.label);
+        } catch (e) {
+          ui.failed(`${a.label}: not removed`, e.message);
+        }
+      }
+    }
+    if (what.includes("home")) {
+      for (const dir of found.home) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        ui.done("Removed", dir);
+        removed.push(dir);
+      }
+    }
+    if (what.includes("slack-cli")) {
+      removeSlackCli({ home });
+      ui.done("Slack CLI removed", `${found.slackCli.dir}, ~/.slack, and its PATH entry`);
+      removed.push("Slack CLI");
+    }
+    if (what.includes("global")) {
+      try {
+        await ui.run("Removing the roger-roger command", () => uninstallGlobally(env), { done: () => "The roger-roger command is gone" });
+        removed.push("the roger-roger command");
+      } catch {
+        // ui.run has already said what npm said.
+      }
+    }
+    ui.outro([
+      c.bold("Done."),
+      "",
+      ...removed.map((s) => `${c.green("•")} ${s}`),
+      "",
+      c.dim("Lines about roger-roger in your own CLAUDE.md or AGENTS.md are yours, so they were left alone."),
+      `Back any time: ${c.cyan("npx roger-roger@latest install")}`,
+    ]);
+    return 0;
+  } catch (e) {
+    if (e instanceof Cancelled) {
+      output.write(os.EOL + `${ui.rail.end}  Stopped. Nothing more was removed.` + os.EOL + os.EOL);
+      return 130;
+    }
+    ui.failed("Uninstall stopped", e.message);
+    return 1;
+  }
+}
+
 /** One line on what a test notification managed. */
 function describeResults(results = {}) {
   const parts = [];

package/skills/roger-roger/scripts/lib.mjs

@@ -13,6 +13,15 @@ import { detectAgent } from "./agent.mjs";
 export const SKILL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const SOUNDS_DIR = path.join(SKILL_DIR, "sounds");
 
+/** The package's version, when the skill sits inside the package; empty for a bare skills.sh copy. */
+export const VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(SKILL_DIR, "..", "..", "package.json"), "utf8")).version ?? "";
+  } catch {
+    return "";
+  }
+})();
+
 export const METHODS = ["slack", "sound", "speech"];
 export const KINDS = ["done", "blocked", "input", "milestone", "error", "info"];
 export const SPEECH_MODES = ["auto", "same", "brief"];

package/skills/roger-roger/scripts/roger-roger.mjs

@@ -30,7 +30,8 @@ import { fileURLToPath } from "node:url";
 import { claudeHookRequest, claudeSettingsPath, claudeStatus, installClaude, readStdin, uninstallClaude } from "./hooks.mjs";
 import { codexHome, codexHookRequest, codexStatus, installCodex, uninstallCodex } from "./hooks-codex.mjs";
 import { installOpencode, opencodeConfigDir, opencodeHookRequest, opencodeStatus, uninstallOpencode } from "./hooks-opencode.mjs";
-import { runInstall } from "./install.mjs";
+import { runInstall, runUninstall } from "./install.mjs";
+import { helpText } from "./help.mjs";
 
 function out(obj, code = 0) {
   process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
@@ -321,6 +322,17 @@ const AGENTS = {
   },
 };
 
+/** `help`, `help <command>`, `--help`, or a command that doesn't exist: the overview, or one command's page. */
+function help(command, args) {
+  const wanted = command === "help" ? args._[0] : "";
+  const unknown = command && !["help", "--help", "-h", undefined].includes(command);
+  if (unknown) process.stderr.write(`roger-roger: unknown command "${command}"\n`);
+  const page = wanted ? helpText(wanted) : null;
+  if (wanted && !page) process.stderr.write(`roger-roger: no such command "${wanted}"\n`);
+  process.stdout.write(page ?? helpText());
+  process.exitCode = unknown || (wanted && !page) ? 2 : 0;
+}
+
 /** Ask the daemon, or do it here when the daemon is from a copy of the skill that predates hooks. */
 async function sendPermission(args, session) {
   try {
@@ -409,68 +421,7 @@ function hooksCommand(args) {
   return out({ ok: !failed, agents: results }, failed ? 1 : 0);
 }
 
-const HELP = `roger-roger - bring the user back to the conversation
-
-  install [--yes]                set everything up in the terminal: link the skill for every agent,
-                                 connect Slack, choose the sound and the voice, hooks, tray.
-                                 --yes (or no terminal) only links the skill and registers with Herdr
-  status                         config, daemon, running sessions, every valid option (JSON)
-  setup [--methods slack,sound,speech] [--sound NAME] [--voice NAME]
-        [--speech auto|same|brief] [--when auto|done-and-blocked|blocked-only|on-request]
-        [--slack-target U0123|C0123|#channel] [--slack-mention U0123]
-        [--local-fallback true|false] [--model ID] [--notes TEXT]
-        [--remind 15m|off] [--on-expire recommended|nothing] [--say-who on|off]
-        [--quiet-hours 22:00-08:00|off] [--quiet-mute speech,sound,slack] [--session-label on|off]
-        [--speech-provider gemini|openai|elevenlabs] [--speech-key-var NAME|auto]
-        [--speech-volume 0-150] [--duck on|off] [--duck-level 0-100] [--tray auto|off]
-        [--permission-pings on|off] [--terminal-wait 20s]
-  slack-setup [status|install-cli|login|create]
-                                 create the roger-roger Slack app with the Slack CLI
-
-  notify --kind done|blocked|input|milestone|error|info --message TEXT
-         [--say TEXT] [--only sound,speech] [--project NAME] [--attach FILE]
-         [--summary] [--field "Label=value"] [--actions "A|B"] [--recommend A]
-         [--reply-to TS] [--then-listen 25m]
-         [--session NAME] [--agent-model MODEL]
-  progress --message TEXT [--key NAME] [--done]
-                                 one Slack message, edited in place as the work moves on
-  control [--key NAME] [--wait DURATION]
-                                 read Pause / Stop and new messages without posting
-  inbox                          messages the user sent this session, and anything unclaimed
-  snooze [1h|off]                mute the sound and the speech for a while; Slack keeps working
-  tray status|start|stop|install an icon showing every agent, and a panel behind it
-  listen [--wait 25m]            park until the user says something; run it in the background as
-                                 the last thing you do, so a message reaches you while you're idle
-
-  ask --question TEXT --choices "A|B" [--recommend A] [--details TEXT] [--multi]
-      [--draft TEXT|--draft-file PATH] [--expires 45m] [--remind 15m]
-      [--on-expire recommended|nothing] [--other true|false] [--wait [DURATION]] [--reply-to TS]
-  wait ID [--timeout DURATION]   block until answered/expired/cancelled (exit 0 / 5, 4 = timed out,
-                                 6 = the user sent a message instead)
-  check ID                       the current state, without waiting
-  cancel ID [--reason TEXT]      withdraw a question
-  decisions [--all]              pending questions (and recent closed ones with --all)
-
-  sessions [--all]               which agents are running, and what each is called
-  sessions rename NAME NEWNAME   give a session a different colour name
-  end [NAME]                     this session (or NAME) is finished; stop routing messages to it
-
-  play [SOUND]                   preview a sound
-  say TEXT [--voice NAME] [--local | --test]
-                                 --test checks the provider and key: its voice or an error, never the local one
-  voices [--refresh]             the speech provider's voices and models (--refresh asks the provider)
-  preview-sounds [SOUND...] [--voice NAME] [--local]
-                                 announce each sound by name, then play it
-  preview-voices [VOICE...] [--all] [--text TEXT]
-
-  daemon status|start|stop       the always-on process behind all of the above
-  hooks status|install|uninstall [claude|opencode|all]
-                                 ping you when an agent asks a question in the terminal
-
-Any command takes --session NAME (what this work is called, and how the session is recognised
-between commands), --agent-model MODEL, --agent NAME, and, if the agent knows better than the
-environment does, --session-id ID and --agent-pid PID.
-`;
+// The help text lives in help.mjs, laid out for the terminal.
 
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
@@ -486,6 +437,9 @@ async function main() {
     case "install":
       process.exitCode = await runInstall(args, { script: SCRIPT, hooks: { agents: AGENTS } });
       return;
+    case "uninstall":
+      process.exitCode = await runUninstall(args, { script: SCRIPT, hooks: { agents: AGENTS } });
+      return;
     case "status": return status();
     case "setup": return setup(args);
     case "slack-setup": return slackSetup(args);
@@ -521,8 +475,7 @@ async function main() {
       return run(command, args);
 
     default:
-      process.stdout.write(HELP);
-      process.exitCode = command && command !== "help" ? 2 : 0;
+      return help(command, args);
   }
 }
 

package/skills/roger-roger/scripts/slackcli.mjs

@@ -44,6 +44,10 @@ export function capture(cmd, args, { input, env, cwd, timeout = 120_000, detache
 }
 
 /** Where the official installers put the binary, per platform. */
+export function cliInstallDir() {
+  return installDir();
+}
+
 function installDir() {
   if (process.platform === "win32") return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "slack-cli");
   return path.join(os.homedir(), ".slack");