@clastres/groundcontrol 0.1.0 → 0.1.1

package/README.md

@@ -5,7 +5,7 @@ Your AI agents, in your pocket. Every Claude Code session on this Mac becomes a
 ## Setup
 
 ```sh
-npx groundcontrol
+npx @clastres/groundcontrol
 ```
 
 Scan the QR code it prints with the Ground Control app. Done. No account.

package/daemon.mjs

@@ -15,6 +15,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn, execFile, execSync } from 'node:child_process';
 import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
 
 const execFileP = promisify(execFile);
 
@@ -24,12 +25,20 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(`
   GROUND CONTROL daemon
 
-  Usage: groundcontrol [options]
+  Usage: groundcontrol [command] [options]
 
   Shows the Claude Code sessions on this Mac in the Ground Control iPhone app.
   On first run it generates a pairing key and prints a QR code. Scan it with
   the app and you are connected. No account needed.
 
+  Commands:
+    (none)              Run the daemon in this terminal
+    service install     Keep the daemon running in the background, always.
+                        Starts at login and restarts if it ever stops.
+    service uninstall   Remove the background service
+    service status      Check whether the background service is running
+    qr                  Print the pairing QR code and exit
+
   Options:
     --relay <url>   Use a custom relay (default: wss://relay.groundcontrol.chat)
     --version       Print version
@@ -41,10 +50,112 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   process.exit(0);
 }
 if (process.argv.includes('--version')) {
-  console.log('0.1.0');
+  console.log('0.1.1');
   process.exit(0);
 }
 
+// ---------- background service (launchd) ----------
+// `groundcontrol service install` keeps the daemon alive with no terminal:
+// starts at login, restarts on crash, survives everything short of logout.
+
+const subcommand = process.argv[2];
+if (subcommand === 'service') {
+  const action = process.argv[3];
+  const LABEL = 'chat.groundcontrol.daemon';
+  const confDir = path.join(os.homedir(), '.groundcontrol');
+  const logFile = path.join(confDir, 'daemon.log');
+  const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+  if (process.platform !== 'darwin') {
+    console.log('\n  The background service is macOS only for now. Keep the daemon');
+    console.log('  running in a terminal, tmux, or your own process manager.\n');
+    process.exit(1);
+  }
+  const uid = process.getuid();
+  const launchctl = (args) => {
+    try { return execSync(`launchctl ${args}`, { stdio: 'pipe' }).toString(); }
+    catch (e) { return (e.stdout?.toString() || '') + (e.stderr?.toString() || ''); }
+  };
+
+  if (action === 'install') {
+    fs.mkdirSync(confDir, { recursive: true });
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    const nodeBin = fs.realpathSync(process.execPath);
+    const daemonPath = fs.realpathSync(fileURLToPath(import.meta.url));
+    const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const plist = `<?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>${esc(nodeBin)}</string>
+        <string>${esc(daemonPath)}</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${esc(path.dirname(daemonPath))}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>5</integer>
+    <key>StandardOutPath</key>
+    <string>${esc(logFile)}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(path.join(confDir, 'daemon.err.log'))}</string>
+</dict>
+</plist>
+`;
+    fs.writeFileSync(plistPath, plist);
+    launchctl(`bootout gui/${uid}/${LABEL}`);
+    launchctl(`bootstrap gui/${uid} ${plistPath}`);
+    // launchd reports the job async; give it a moment to reach running state.
+    let out = '';
+    for (let i = 0; i < 5 && !out.includes('state = running'); i++) {
+      execSync('sleep 1');
+      out = launchctl(`print gui/${uid}/${LABEL}`);
+    }
+    if (out.includes('state = running')) {
+      console.log('\n  Ground Control daemon is now running in the background.');
+      console.log('  It starts at login and restarts automatically if it stops.\n');
+      console.log(`  Log:       ${logFile}`);
+      console.log('  Pair:      groundcontrol qr');
+      console.log('  Check:     groundcontrol service status');
+      console.log('  Remove:    groundcontrol service uninstall\n');
+    } else {
+      console.log('\n  Install finished but the service is not reporting as running.');
+      console.log(`  Check ${logFile} and try: launchctl bootstrap gui/${uid} ${plistPath}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  if (action === 'uninstall') {
+    launchctl(`bootout gui/${uid}/${LABEL}`);
+    try { fs.unlinkSync(plistPath); } catch {}
+    console.log('\n  Background service removed. Run the daemon manually with: groundcontrol\n');
+    process.exit(0);
+  }
+
+  if (action === 'status') {
+    const out = launchctl(`print gui/${uid}/${LABEL}`);
+    if (out.includes('state = running')) {
+      console.log('\n  Running in the background.');
+    } else if (fs.existsSync(plistPath)) {
+      console.log('\n  Installed but not running. Reinstall with: groundcontrol service install');
+    } else {
+      console.log('\n  Not installed. Set it up with: groundcontrol service install');
+    }
+    console.log(`  Log: ${logFile}\n`);
+    process.exit(0);
+  }
+
+  console.log('\n  Usage: groundcontrol service <install|uninstall|status>\n');
+  process.exit(1);
+}
+
 const argRelay = (() => {
   const i = process.argv.indexOf('--relay');
   return i > -1 ? process.argv[i + 1] : null;
@@ -84,6 +195,11 @@ console.log(`  channel: ${CHANNEL}\n`);
 qrcode.generate(pairString, { small: true });
 console.log(`\n  Pairing code (paste into the app):\n\n  ${pairString}\n`);
 
+if (subcommand === 'qr') process.exit(0);
+
+console.log('  Tip: keep this running without a terminal:');
+console.log('       npx @clastres/groundcontrol service install\n');
+
 // ---------- crypto: wire format = base64( nonce(12) | ciphertext | tag(16) ) ----------
 
 function seal(obj) {
@@ -414,7 +530,14 @@ function connect() {
     if (str.startsWith('{"sys"')) return;
     try { handleCommand(open(str))?.catch?.(() => {}); } catch (e) { console.log('[daemon] bad message (wrong key?)'); }
   });
-  ws.on('close', () => { console.log('[daemon] relay disconnected, retrying in 3s'); setTimeout(connect, 3000); });
+  ws.on('close', (code) => {
+    if (code === 4001) {
+      console.log('[daemon] another daemon took over this channel, exiting. Run only one copy.');
+      process.exit(0);
+    }
+    console.log('[daemon] relay disconnected, retrying in 3s');
+    setTimeout(connect, 3000);
+  });
   ws.on('error', () => {});
 }
 

package/package.json

@@ -1,16 +1,29 @@
 {
   "name": "@clastres/groundcontrol",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "See and command your Claude Code sessions from your iPhone. Pairs the Ground Control app with the agents running on this Mac, end to end encrypted.",
-  "bin": { "groundcontrol": "./bin/groundcontrol.mjs" },
+  "bin": {
+    "groundcontrol": "./bin/groundcontrol.mjs"
+  },
   "type": "module",
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.0"
   },
-  "keywords": ["claude", "claude-code", "ai", "agents", "cli", "ios", "remote", "monitor"],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "cli",
+    "ios",
+    "remote",
+    "monitor"
+  ],
   "homepage": "https://groundcontrol.chat",
   "author": "Carlos Lastres",
   "license": "MIT"
-}
+}