gitwarren 0.1.8-beta.1 → 0.1.9

package/README.md

@@ -8,33 +8,58 @@ This package is the command line. There is also a desktop app; see
 [gitwarren-app](https://github.com/klarluft/gitwarren-app).
 
 ```
-npx gitwarren serve
+npx gitwarren serve --open
 ```
 
-That serves the review UI on `127.0.0.1:41427` and prints a URL carrying a
-token minted for that launch. Open it, add a repository, pick two refs, and
-review the diff.
+That serves the review UI on `127.0.0.1:41427`, prints a URL carrying a token
+minted for that launch, and opens it. Add a repository, pick two refs, and
+review the diff. Ctrl-C stops it. Needs Node 22 or newer; on a machine without
+Node, the Homebrew formula and the install script in the
+[app repository](https://github.com/klarluft/gitwarren-app#the-gitwarren-command-line)
+bring their own.
 
 ## Commands
 
+**Run it now**
+
+| | |
+| --- | --- |
+| `gitwarren serve [--open]` | run GitWarren in this terminal and print its URL; `--open` opens it too |
+| `gitwarren open [link]` | open the running GitWarren in your browser, carrying the token |
+
+**Keep it running**
+
 | | |
 | --- | --- |
-| `gitwarren serve` | serve the web view on loopback and print its URL |
-| `gitwarren serve --stdio` | answer GitWarren's protocol on stdin/stdout |
-| `gitwarren open [link]` | open this machine's GitWarren in a browser, carrying the token |
-| `gitwarren service install` | write the agent launcher, and start at login |
-| `gitwarren service uninstall` | remove the login item |
-| `gitwarren service status` | what is registered, and what is running |
+| `gitwarren service install` | run GitWarren in the background, from now and at every login |
+| `gitwarren service uninstall` | stop that, and remove the login item |
+| `gitwarren service status` | what is running, and where the data is |
+
+**Let a coding agent in**
+
+| | |
+| --- | --- |
+| `gitwarren agent-setup` | print the one sentence to give an agent so it can reach GitWarren over MCP |
+
+`gitwarren serve --stdio` answers GitWarren's protocol on stdin and stdout; it
+is what a GitWarren on another machine spawns, and nothing a person needs to
+type.
 
 `gitwarren open` takes a `gitwarren://` deep link or the `http://127.0.0.1`
 URL an agent hands out, and lands on that review rather than the home screen.
 
 ## Letting an agent in
 
-`gitwarren service install` writes `~/.gitwarren/bin/gitwarren-mcp`, which is a
-GitWarren MCP server your coding agent can start. Point the agent at that one
-path — it is the same on every machine, and GitWarren keeps it pointing at
-whichever install ran last.
+Every install carries GitWarren's MCP server. What an agent needs is one
+stable command to start it with, and that is `~/.gitwarren/bin/gitwarren-mcp` —
+the same path on every machine, written by `gitwarren serve`, `gitwarren
+agent-setup` and `gitwarren service install` alike, and kept pointing at
+whichever install ran last. `gitwarren agent-setup` prints the sentence to
+paste into the agent.
+
+The MCP server reads the same SQLite file the browser view does, so an agent
+can open and comment on reviews whether or not GitWarren is being served. What
+serving adds is that the links an agent hands you have something to open.
 
 ## Where your data is
 

package/lib/gitwarren.cjs

@@ -10242,7 +10242,7 @@ function cmdQuote(value) {
   if (value.includes('"')) throw new Error(`a Windows path cannot contain a quote: ${value}`);
   return `"${value}"`;
 }
-const APP_VERSION = "0.1.8-beta.1";
+const APP_VERSION = "0.1.9";
 const REMOTE_ROOT = "$HOME/.gitwarren";
 const runOnHost = (route2, options) => {
   switch (route2.kind) {
@@ -16691,7 +16691,7 @@ function describeMcpLaunch() {
     available,
     stable: true,
     direct: { command: launcher, args: [], env: {} },
-    note: available ? void 0 : "No MCP launcher on this machine yet. `gitwarren service install` writes it."
+    note: available ? void 0 : "No MCP launcher on this machine yet. `gitwarren agent-setup` writes it, and so does `gitwarren serve`."
   };
 }
 const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
@@ -26868,7 +26868,7 @@ Connection: close\r
     }
   };
 }
-const VERSION$1 = "0.1.8-beta.1";
+const VERSION$1 = "0.1.9";
 function isWebBuild(directory) {
   return fs.existsSync(node_path.join(directory, "index.html")) && !fs.existsSync(node_path.join(directory, "main.ts"));
 }
@@ -26914,11 +26914,12 @@ function whereTheOwnerIs(owner) {
     ${url}
 `;
 }
-function runListen() {
+function runListen(hooks = {}) {
   const owner = readLiveDaemonRuntime();
   if (owner) {
+    const who = owner.owner === "gui" ? "the desktop app" : "another `gitwarren serve`, in a terminal or as the background service (which `gitwarren service uninstall` stops)";
     console.error(
-      `[gitwarren-serve] this machine's GitWarren is already being served by ${owner.owner === "gui" ? "the app" : "another gitwarren serve"} (pid ${owner.pid}). A data directory has one owner. Quit that first, or use the one that is running` + whereTheOwnerIs(owner)
+      `[gitwarren] GitWarren is already running on this machine (pid ${owner.pid}), as ${who}. Only one can serve a data directory at a time. Quit that first, or use the one that is running` + whereTheOwnerIs(owner)
     );
     process.exitCode = 1;
     return false;
@@ -26926,7 +26927,7 @@ function runListen() {
   const webRoot = resolveWebRoot();
   if (!webRoot) {
     console.error(
-      "[gitwarren-serve] no web build found. Run `npm run build:web`, or set GITWARREN_WEB_ROOT to the directory holding its index.html."
+      "[gitwarren] no web build found. Run `npm run build:web`, or set GITWARREN_WEB_ROOT to the directory holding its index.html."
     );
     process.exitCode = 1;
     return false;
@@ -26953,10 +26954,10 @@ function runListen() {
   server.on("error", (error2) => {
     if (error2.code === "EADDRINUSE") {
       console.error(
-        `[gitwarren-serve] port ${LINK_SERVER_PORT} is already in use. That port is the one every GitWarren link names, so serving on a different one would mean serving where nobody is looking. Free it and start again.`
+        `[gitwarren] port ${LINK_SERVER_PORT} is already in use. That port is the one every GitWarren link names, so serving on a different one would mean serving where nobody is looking. Free it and start again.`
       );
     } else {
-      console.error("[gitwarren-serve] the server failed", error2);
+      console.error("[gitwarren] the server failed", error2);
     }
     shutdownListen();
     process.exitCode = 1;
@@ -26969,13 +26970,16 @@ function runListen() {
       linkPort,
       owner: "daemon"
     });
+    const url = `http://${LINK_SERVER_HOST}:${LINK_SERVER_PORT}/?${TOKEN_PARAM}=${token}`;
     console.error(
-      `[gitwarren-serve] GitWarren is at
+      `[gitwarren] GitWarren is running at
 
-    http://${LINK_SERVER_HOST}:${LINK_SERVER_PORT}/?${TOKEN_PARAM}=${token}
+    ${url}
 
-The token is new each time this starts, and is exchanged for a session cookie the first time the URL is opened.`
+Open that URL, or run \`gitwarren open\` in another terminal. The token in it is minted for this launch and becomes a cookie the first time the page loads.
+Press Ctrl-C to stop. To keep GitWarren running in the background instead, from now and at every login, use \`gitwarren service install\`.`
     );
+    hooks.onListening?.(url);
   });
   closeOnExit = () => {
     handler.close();
@@ -27002,10 +27006,11 @@ hand it is a way to see what the protocol says:
 
 --listen serves the web view on loopback and prints a URL carrying this
 launch's token. It claims this machine's data directory, so it refuses to
-start while the app is running - see daemon/listen.ts.
+start while the app is running - see daemon/listen.ts. \`gitwarren serve\` with
+no flag means this one.
 `;
-function runDaemon(argv) {
-  if (argv.includes("--listen")) return runListen();
+function runDaemon(argv, hooks = {}) {
+  if (argv.includes("--listen")) return runListen(hooks);
   if (!argv.includes("--stdio")) {
     console.error(USAGE$4);
     return false;
@@ -27062,6 +27067,99 @@ command = ${tomlString(mcp.command)}
     }
   ];
 }
+const WEB_ROOT_ENV_VAR = "GITWARREN_WEB_ROOT";
+function relaunchEnv() {
+  const env = { [MIGRATIONS_DIR_ENV_VAR]: resolveMigrationsFolder() };
+  const webRoot = resolveWebRoot();
+  if (webRoot) env[WEB_ROOT_ENV_VAR] = webRoot;
+  const dataDir = process.env[DATA_DIR_ENV_VAR]?.trim();
+  if (dataDir) env[DATA_DIR_ENV_VAR] = dataDir;
+  return env;
+}
+function findMcpServer(script) {
+  const candidates = [
+    script && node_path.join(node_path.dirname(script), "server.cjs"),
+    script && node_path.join(node_path.dirname(script), "..", "lib", "server.cjs"),
+    node_path.join(process.cwd(), "out", "mcp", "server.cjs")
+  ];
+  for (const candidate of candidates) {
+    if (candidate && fs.existsSync(candidate)) return fs.realpathSync(candidate);
+  }
+  return null;
+}
+function describeSelf() {
+  const argv1 = process.argv[1];
+  let script = null;
+  if (argv1 !== void 0) {
+    try {
+      const resolved2 = fs.realpathSync(argv1);
+      script = /\.[cm]?ts$/i.test(resolved2) ? null : resolved2;
+    } catch {
+      script = null;
+    }
+  }
+  return { node: fs.realpathSync(process.execPath), script, mcpServer: findMcpServer(script), env: relaunchEnv() };
+}
+const BANNER = (what) => [
+  `GitWarren ${what}. Written by the gitwarren command line, so a config or a`,
+  "login item that names this path keeps working when the install moves.",
+  "Generated file - rerun `gitwarren service install` to refresh it, do not edit this."
+];
+function bannerFor(what, comment, eol) {
+  return BANNER(what).map((line) => `${comment} ${line}${eol}`).join("");
+}
+function posixLauncher(what, self, script) {
+  const exports2 = Object.entries(self.env).map(([name, value]) => `export ${name}=${shellQuote(value)}
+`).join("");
+  return "#!/bin/sh\n" + bannerFor(what, "#", "\n") + exports2 + `exec ${shellQuote(self.node)} ${shellQuote(script)} "$@"
+`;
+}
+function windowsLauncher(what, self, script) {
+  const sets = Object.entries(self.env).map(([name, value]) => `set "${name}=${value}"\r
+`).join("");
+  return "@echo off\r\n" + bannerFor(what, "REM", "\r\n") + "setlocal\r\n" + sets + `${cmdQuote(self.node)} ${cmdQuote(script)} %*\r
+exit /b %ERRORLEVEL%\r
+`;
+}
+function write(path, contents) {
+  let current2 = null;
+  try {
+    current2 = fs.readFileSync(path, "utf8");
+  } catch {
+  }
+  if (current2 !== contents) {
+    fs.mkdirSync(getLauncherDirectory(), { recursive: true });
+    fs.writeFileSync(path, contents, "utf8");
+  }
+  if (process.platform !== "win32") fs.chmodSync(path, 493);
+  return current2 === null;
+}
+function writeLaunchers(self) {
+  if (self.script === null) {
+    throw new Error(
+      "this gitwarren is running from a source checkout, so there is no single file a login item could name. Build it first (`npm run build:daemon`), or install GitWarren from a tarball, Homebrew or npm."
+    );
+  }
+  const posix = process.platform !== "win32";
+  const created = [];
+  const cli = getCliLauncherPath();
+  if (write(cli, (posix ? posixLauncher : windowsLauncher)("CLI", self, self.script))) created.push(cli);
+  let mcp = null;
+  if (self.mcpServer !== null) {
+    mcp = getMcpLauncherPath();
+    if (write(mcp, (posix ? posixLauncher : windowsLauncher)("MCP server", self, self.mcpServer)))
+      created.push(mcp);
+  }
+  return { cli, mcp, created };
+}
+function ensureLaunchers() {
+  try {
+    const { created } = writeLaunchers(describeSelf());
+    return { created, refused: null };
+  } catch (error2) {
+    return { created: [], refused: error2 instanceof Error ? error2.message : String(error2) };
+  }
+}
 const USAGE$3 = `gitwarren agent-setup [--manual]
 
 Prints the sentence to paste into an agent so it can reach this machine's
@@ -27089,14 +27187,25 @@ function runAgentSetup(argv) {
       console.log(snippet.text.trimEnd());
     }
   }
-  if (!fs.existsSync(command)) {
+  const launchers = ensureLaunchers();
+  if (launchers.created.includes(command)) {
+    console.error(`
+[gitwarren] wrote ${command}, which the sentence above names.`);
+  } else if (!fs.existsSync(command)) {
     console.error(
       `
-[gitwarren] no launcher at ${command} yet. \`gitwarren service install\` writes it.`
+[gitwarren] no launcher at ${command} yet, and this run could not write one` + (launchers.refused ? `: ${launchers.refused}` : ".")
     );
   }
   return true;
 }
+function openInBrowser(url, onError) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  const child = node_child_process.execFile(command, args, { windowsHide: true }, (error2) => {
+    if (error2) onError(`could not ask ${command} to open a browser (${error2.message})`);
+  });
+  child.unref();
+}
 const REVIEW_TABS = ["conversation", "commits", "files", "browse"];
 const HOME = { name: "repositories" };
 const HOST_SEGMENT = "h";
@@ -27217,21 +27326,6 @@ token so the tab is authenticated without anything being copied.
   --print  print the URL instead of opening it - for an ssh session, or for
            piping somewhere.
 `;
-function openInBrowser(url) {
-  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
-  const child = node_child_process.execFile(command, args, { windowsHide: true }, (error2) => {
-    if (error2) {
-      console.error(
-        `[gitwarren] could not ask ${command} to open a browser (${error2.message}). The URL is:
-
-    ${url}
-`
-      );
-      process.exitCode = 1;
-    }
-  });
-  child.unref();
-}
 function runOpen(argv) {
   const print = argv.includes("--print");
   const rest = argv.filter((argument) => argument !== "--print");
@@ -27242,7 +27336,7 @@ function runOpen(argv) {
   const owner = readLiveDaemonRuntime();
   if (owner === null) {
     console.error(
-      "[gitwarren] nothing is serving this machine. Start it with `gitwarren serve`, or `gitwarren service install` to have it start at login."
+      "[gitwarren] GitWarren is not running on this machine, so there is nothing to open. `gitwarren serve` runs it in a terminal; `gitwarren service install` keeps it running in the background."
     );
     process.exitCode = 1;
     return true;
@@ -27273,91 +27367,16 @@ ${USAGE$2}`);
     return true;
   }
   if (print) console.log(url);
-  else openInBrowser(url);
+  else
+    openInBrowser(url, (message) => {
+      console.error(`[gitwarren] ${message}. The URL is:
+
+    ${url}
+`);
+      process.exitCode = 1;
+    });
   return true;
 }
-const WEB_ROOT_ENV_VAR = "GITWARREN_WEB_ROOT";
-function relaunchEnv() {
-  const env = { [MIGRATIONS_DIR_ENV_VAR]: resolveMigrationsFolder() };
-  const webRoot = resolveWebRoot();
-  if (webRoot) env[WEB_ROOT_ENV_VAR] = webRoot;
-  const dataDir = process.env[DATA_DIR_ENV_VAR]?.trim();
-  if (dataDir) env[DATA_DIR_ENV_VAR] = dataDir;
-  return env;
-}
-function findMcpServer(script) {
-  const candidates = [
-    script && node_path.join(node_path.dirname(script), "server.cjs"),
-    script && node_path.join(node_path.dirname(script), "..", "lib", "server.cjs"),
-    node_path.join(process.cwd(), "out", "mcp", "server.cjs")
-  ];
-  for (const candidate of candidates) {
-    if (candidate && fs.existsSync(candidate)) return fs.realpathSync(candidate);
-  }
-  return null;
-}
-function describeSelf() {
-  const argv1 = process.argv[1];
-  let script = null;
-  if (argv1 !== void 0) {
-    try {
-      const resolved2 = fs.realpathSync(argv1);
-      script = /\.[cm]?ts$/i.test(resolved2) ? null : resolved2;
-    } catch {
-      script = null;
-    }
-  }
-  return { node: fs.realpathSync(process.execPath), script, mcpServer: findMcpServer(script), env: relaunchEnv() };
-}
-const BANNER = (what) => [
-  `GitWarren ${what}. Written by \`gitwarren service install\`, so a config or a`,
-  "login item that names this path keeps working when the install moves.",
-  "Generated file - run the command again, do not edit this."
-];
-function bannerFor(what, comment, eol) {
-  return BANNER(what).map((line) => `${comment} ${line}${eol}`).join("");
-}
-function posixLauncher(what, self, script) {
-  const exports2 = Object.entries(self.env).map(([name, value]) => `export ${name}=${shellQuote(value)}
-`).join("");
-  return "#!/bin/sh\n" + bannerFor(what, "#", "\n") + exports2 + `exec ${shellQuote(self.node)} ${shellQuote(script)} "$@"
-`;
-}
-function windowsLauncher(what, self, script) {
-  const sets = Object.entries(self.env).map(([name, value]) => `set "${name}=${value}"\r
-`).join("");
-  return "@echo off\r\n" + bannerFor(what, "REM", "\r\n") + "setlocal\r\n" + sets + `${cmdQuote(self.node)} ${cmdQuote(script)} %*\r
-exit /b %ERRORLEVEL%\r
-`;
-}
-function write(path, contents) {
-  let current2 = null;
-  try {
-    current2 = fs.readFileSync(path, "utf8");
-  } catch {
-  }
-  if (current2 !== contents) {
-    fs.mkdirSync(getLauncherDirectory(), { recursive: true });
-    fs.writeFileSync(path, contents, "utf8");
-  }
-  if (process.platform !== "win32") fs.chmodSync(path, 493);
-}
-function writeLaunchers(self) {
-  if (self.script === null) {
-    throw new Error(
-      "this gitwarren is running from a source checkout, so there is no single file a login item could name. Build it first (`npm run build:daemon`), or install GitWarren from a tarball, Homebrew or npm."
-    );
-  }
-  const posix = process.platform !== "win32";
-  const cli = getCliLauncherPath();
-  write(cli, (posix ? posixLauncher : windowsLauncher)("CLI", self, self.script));
-  let mcp = null;
-  if (self.mcpServer !== null) {
-    mcp = getMcpLauncherPath();
-    write(mcp, (posix ? posixLauncher : windowsLauncher)("MCP server", self, self.mcpServer));
-  }
-  return { cli, mcp };
-}
 const LAUNCHD_LABEL = "com.gitwarren.daemon";
 const SYSTEMD_UNIT = "gitwarren.service";
 const WINDOWS_TASK = "GitWarren daemon";
@@ -27416,11 +27435,18 @@ const USAGE$1 = `gitwarren service install [--no-login-item]
 gitwarren service uninstall
 gitwarren service status
 
-install   writes ~/.gitwarren/bin/gitwarren and gitwarren-mcp, and registers a
-          login item that runs \`gitwarren serve --listen\`.
-uninstall removes the login item. The launchers stay: an agent config may name
-          one, and removing a login item is not a request to break that.
-status    says what is registered and what is running.
+install    keeps GitWarren running in the background: it starts now, and again
+           at every login, so \`gitwarren open\` and the links an agent hands
+           you always have something to open. Registers a LaunchAgent on
+           macOS, a systemd user unit on Linux, an at-logon task on Windows.
+           Also writes ~/.gitwarren/bin/gitwarren and gitwarren-mcp, the
+           stable paths the app and an agent start this install by.
+           --no-login-item writes those two files and registers nothing,
+           for a machine that is only ever reached from another one.
+uninstall  stops the background GitWarren and removes the login item. The two
+           files in ~/.gitwarren/bin stay, because an agent config may name
+           one; delete that directory by hand to remove them.
+status     what is registered, what is running, and where the data is.
 `;
 function macLogPath() {
   return node_path.join(node_os.homedir(), "Library", "Logs", "GitWarren", "daemon.log");
@@ -27471,6 +27497,7 @@ function registerLoginItem(launcher) {
       "ONLOGON",
       "/F"
     ]);
+    ask("schtasks", ["/Run", "/TN", WINDOWS_TASK]);
     return `Scheduled Task "${WINDOWS_TASK}"`;
   }
   if (path === null) throw new Error("no login item path for this platform");
@@ -27526,14 +27553,22 @@ function install(argv) {
     );
   }
   if (argv.includes("--no-login-item")) {
-    console.log("--no-login-item: nothing was registered to start at login.");
+    console.log("Nothing was registered to start at login (--no-login-item).");
     return true;
   }
-  console.log(registerLoginItem(cli) + " will run `gitwarren serve --listen` at login.");
   const owner = readLiveDaemonRuntime();
+  console.log(`registered ${registerLoginItem(cli)}`);
   if (owner?.owner === "gui") {
     console.log(
-      "\nGitWarren.app is running and owns this data directory. A data directory has one owner, so the daemon will stand aside whenever the app is up - which is fine, and means the login item only does something on the logins where you do not open it."
+      "\nThe desktop app is running and owns this data directory, so the background GitWarren has stood aside for now. Only one can serve at a time; the login item does its job on the logins where you do not open the app."
+    );
+  } else if (owner !== null) {
+    console.log(
+      "\nA `gitwarren serve` is already running in a terminal, so the background GitWarren has stood aside for now. Stop that one and it takes over at the next login, or straight away if you run `gitwarren service install` again."
+    );
+  } else {
+    console.log(
+      "\nGitWarren is now running in the background, and will start again when you log in. `gitwarren open` opens it in your browser; `gitwarren service uninstall` undoes all of this."
     );
   }
   console.log(`
@@ -27549,17 +27584,19 @@ function runService(argv) {
       case "uninstall":
         console.log(`removed ${removeLoginItem()}`);
         console.log(
-          "The launchers in ~/.gitwarren/bin were left alone. Delete them by hand if an agent no longer needs to reach this machine."
+          "GitWarren no longer runs in the background or starts at login. `gitwarren serve` still runs it in a terminal. The two files in ~/.gitwarren/bin were left alone, because an agent config may name one; delete that directory to remove them."
         );
         return true;
       case "status": {
         const owner = readLiveDaemonRuntime();
-        console.log(`Login item:  ${loginItemState()}`);
-        console.log(`Launcher:    ${fs.existsSync(getCliLauncherPath()) ? getCliLauncherPath() : "not written"}`);
+        const mcp = getMcpLauncherPath();
+        console.log(`Login item:    ${loginItemState()}`);
+        console.log(`CLI launcher:  ${fs.existsSync(getCliLauncherPath()) ? getCliLauncherPath() : "not written"}`);
+        console.log(`MCP launcher:  ${fs.existsSync(mcp) ? mcp : "not written - `gitwarren agent-setup` writes it"}`);
         console.log(
-          `Serving now: ${owner === null ? "nothing" : `${owner.owner === "gui" ? "GitWarren.app" : "gitwarren serve"} (pid ${owner.pid})`}`
+          `Running now:   ${owner === null ? "nothing - `gitwarren serve` runs it in this terminal" : `${owner.owner === "gui" ? "the desktop app" : "gitwarren serve"} (pid ${owner.pid})`}`
         );
-        console.log(`Data:        ${getDataDirectory()}`);
+        console.log(`Data:          ${getDataDirectory()}`);
         return true;
       }
       default:
@@ -27572,30 +27609,75 @@ function runService(argv) {
     return true;
   }
 }
-const VERSION = "0.1.8-beta.1";
-const USAGE = `gitwarren - local-only code review, from the command line
+const VERSION = "0.1.9";
+const USAGE = `gitwarren - code review for your own git repositories, in a browser tab
+
+Run it now
+  gitwarren serve                run GitWarren in this terminal and print its URL
+                                 (--open also opens the browser; Ctrl-C stops it)
+  gitwarren open [link]          open the running GitWarren in your browser
+
+Keep it running
+  gitwarren service install      run GitWarren in the background, from now and at
+                                 every login
+  gitwarren service uninstall    stop that, and remove the login item
+  gitwarren service status       what is running, and where the data is
 
-  gitwarren serve                serve the web view on loopback and print its URL
-  gitwarren serve --stdio        answer GitWarren's protocol on stdin/stdout
-  gitwarren open [link]          open this machine's GitWarren in a browser
-  gitwarren service install      write the launchers and start at login
-  gitwarren service uninstall    remove the login item
-  gitwarren service status       what is registered, and what is running
-  gitwarren agent-setup          print the sentence that points an agent here
+Let a coding agent in
+  gitwarren agent-setup          print the one sentence to give an agent so it can
+                                 reach this GitWarren over MCP
+
+  gitwarren serve --stdio        answer GitWarren's protocol on stdin/stdout (this
+                                 is what another machine's GitWarren spawns)
   gitwarren --version
 
-Run a subcommand with no valid arguments to see its own usage.
+Run a subcommand with --help to see its own usage.
 
-The web view is served on 127.0.0.1 only, behind a token minted per launch.
-\`gitwarren open\` carries that token for you; see docs/across-hosts.md.
+GitWarren serves on 127.0.0.1 only, behind a token minted per launch, and
+\`gitwarren open\` carries that token for you. Reviews live in one SQLite file
+on this machine - serving, the background service and the MCP server all read
+the same one, so an agent can use GitWarren whether or not it is being served.
 `;
+const SERVE_USAGE = `gitwarren serve [--open]
+gitwarren serve --stdio
+
+Runs GitWarren in this terminal, serving the review UI on 127.0.0.1 and printing
+a URL that carries this launch's token. Ctrl-C stops it.
+
+  --open    also open that URL in your browser
+  --stdio   answer GitWarren's protocol on stdin/stdout instead. This is what a
+            GitWarren on another machine spawns over ssh or wsl.exe; by hand it
+            is a way to see what the protocol says.
+
+Serving also writes ~/.gitwarren/bin/gitwarren-mcp, the command a coding agent
+starts the MCP server with - see \`gitwarren agent-setup\`.
+`;
+function afterListening(url, open2) {
+  const launchers = ensureLaunchers();
+  if (launchers.refused) {
+    console.error(
+      `
+[gitwarren] no launcher was written to ~/.gitwarren/bin, so an agent has nothing to start yet: ${launchers.refused}`
+    );
+  } else if (launchers.created.length > 0) {
+    console.error(`
+[gitwarren] wrote ${launchers.created.join(" and ")}`);
+  }
+  if (open2) {
+    openInBrowser(url, (message) => console.error(`[gitwarren] ${message}. The URL is above.`));
+  }
+}
 function runCli(argv) {
   const [command, ...rest] = argv;
   switch (command) {
-    case "serve":
-      return runDaemon(
-        rest.includes("--stdio") || rest.includes("--listen") ? rest : [...rest, "--listen"]
-      );
+    case "serve": {
+      if (rest.includes("--help") || rest.includes("-h")) {
+        console.log(SERVE_USAGE);
+        return true;
+      }
+      const argv2 = rest.includes("--stdio") || rest.includes("--listen") ? rest : [...rest, "--listen"];
+      return runDaemon(argv2, { onListening: (url) => afterListening(url, rest.includes("--open")) });
+    }
     case "open":
       return runOpen(rest);
     case "service":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitwarren",
-  "version": "0.1.8-beta.1",
+  "version": "0.1.9",
   "description": "Code review for your own machines and your own agents, served on loopback. No Electron, no account.",
   "keywords": ["code-review", "git", "diff", "mcp", "local-first", "ssh", "wsl", "tailscale", "self-hosted"],
   "homepage": "https://github.com/klarluft/gitwarren-app",