llmtab-desktop 2.0.1 → 2.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLMTab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,6 +21,29 @@ links the bins of the package you name:
 npm i -g llmtab llmtab-desktop
 ```
 
+## Running in the background
+
+`llmtab-desktop` detaches from your terminal. The prompt comes straight back,
+Ctrl-C does not kill the tray app, and closing the terminal leaves it running:
+
+```sh
+llmtab-desktop
+# llmtab-desktop: started in the background (pid 51234) · log: ~/.llmtab/desktop.log
+```
+
+Quit it from the tray menu. Output goes to `~/.llmtab/desktop.log`
+(`$LLMTAB_HOME/desktop.log` if you set that).
+
+To keep it attached to the terminal instead — useful when debugging a crash on
+startup — pass `--foreground`:
+
+```sh
+llmtab-desktop --foreground     # or -F
+```
+
+Any other arguments are forwarded to Electron as-is; anything after `--` is
+left for the app.
+
 ## Platform support
 
 | OS      | status                                                         |

package/bin.mjs

@@ -7,11 +7,16 @@
  * force on people who just want the CLI. We locate the installed `llmtab` via
  * normal Node resolution, so npm/pnpm/yarn layouts all work without guessing
  * at node_modules paths.
+ *
+ * The shell is a menu-bar app, so it detaches by default: the prompt comes
+ * straight back, Ctrl-C no longer kills it, and closing the terminal leaves it
+ * running. Pass --foreground (-F) to keep it attached for debugging.
  */
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, openSync } from "node:fs";
 import path from "node:path";
+import { logFilePath, parseArgs } from "./launcher.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -59,12 +64,44 @@ function resolveElectron() {
   return electronPath;
 }
 
-const child = spawn(resolveElectron(), [resolveShellEntry(), ...process.argv.slice(2)], {
-  stdio: "inherit",
-});
+/**
+ * Opens the detached shell's log in append mode, creating the state dir if the
+ * CLI has never run. A log we cannot open is not worth aborting the launch for
+ * — the app matters more than its diagnostics — so fall back to discarding.
+ */
+function openLog() {
+  const file = logFilePath();
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    return { fd: openSync(file, "a"), file };
+  } catch {
+    return { fd: "ignore", file: null };
+  }
+}
 
-child.on("error", (err) => die(`failed to launch Electron: ${err.message}`));
-child.on("exit", (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  else process.exit(code ?? 0);
-});
+const { foreground, forward } = parseArgs(process.argv.slice(2));
+const args = [resolveShellEntry(), ...forward];
+const electron = resolveElectron();
+
+if (foreground) {
+  const child = spawn(electron, args, { stdio: "inherit" });
+  child.on("error", (err) => die(`failed to launch Electron: ${err.message}`));
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+} else {
+  // `detached` puts the shell in its own process group, so the terminal's
+  // Ctrl-C (SIGINT to the foreground group) and its SIGHUP on close no longer
+  // reach it. Redirecting stdio frees the prompt; unref lets us exit first.
+  const { fd, file } = openLog();
+  const child = spawn(electron, args, {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  child.on("error", (err) => die(`failed to launch Electron: ${err.message}`));
+  child.unref();
+  const where = file ? ` · log: ${file}` : "";
+  console.log(`llmtab-desktop: started in the background (pid ${child.pid})${where}`);
+  console.log("  stop it from the tray menu; run with --foreground to keep it attached.");
+}

package/launcher.mjs

@@ -0,0 +1,47 @@
+/**
+ * Pure launcher decisions for `llmtab-desktop`, split out of bin.mjs so they
+ * can be tested without spawning Electron.
+ */
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Splits our own flags from the ones Electron should receive.
+ *
+ * A menu-bar app that holds the terminal hostage is a bug, so detaching is the
+ * default and `--foreground` is the escape hatch for debugging. Everything else
+ * is forwarded verbatim; anything after `--` belongs to the app, so a
+ * `--foreground` there is passed through rather than consumed.
+ */
+export function parseArgs(argv) {
+  const forward = [];
+  let foreground = false;
+  let appArgs = false;
+  for (const arg of argv) {
+    if (appArgs) {
+      forward.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      appArgs = true;
+      forward.push(arg);
+      continue;
+    }
+    if (arg === "--foreground" || arg === "-F") {
+      foreground = true;
+      continue;
+    }
+    forward.push(arg);
+  }
+  return { foreground, forward };
+}
+
+/** Base state dir, mirroring src/shared/paths.ts (LLMTAB_HOME overrides). */
+export function stateHome(env = process.env, home = os.homedir()) {
+  return env.LLMTAB_HOME ?? path.join(home, ".llmtab");
+}
+
+/** Where a detached shell's stdout/stderr are appended. */
+export function logFilePath(env = process.env, home = os.homedir()) {
+  return path.join(stateHome(env, home), "desktop.log");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "llmtab-desktop",
-  "version": "2.0.1",
-  "description": "Menu-bar / tray app for LLMTab — adds the Electron shell to the llmtab CLI.",
+  "version": "2.0.3",
+  "description": "Menu-bar / tray app for LLMTab \u2014 adds the Electron shell to the llmtab CLI.",
   "type": "module",
   "license": "MIT",
   "author": "naninanides",
@@ -33,10 +33,12 @@
   },
   "files": [
     "bin.mjs",
+    "launcher.mjs",
+    "LICENSE",
     "README.md"
   ],
   "dependencies": {
     "electron": "^44.0.0",
-    "llmtab": "^2.0.1"
+    "llmtab": "^2.0.2"
   }
 }