@clastres/groundcontrol 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# Ground Control
+
+Your AI agents, in your pocket. Every Claude Code session on this Mac becomes a pixel pilot in the [Ground Control iPhone app](https://groundcontrol.chat): watch them work, read replies as they stream, send new orders from anywhere.
+
+## Setup
+
+```sh
+npx groundcontrol
+```
+
+Scan the QR code it prints with the Ground Control app. Done. No account.
+
+## How it stays private
+
+The pairing key is generated on this machine and shared only through that QR code. Everything travels end to end encrypted (ChaCha20 Poly1305); the relay routes sealed bytes it cannot read, and stores nothing.
+
+## Requirements
+
+A Mac running [Claude Code](https://claude.com/claude-code), Node 20+, and the Ground Control iPhone app.
+
+Docs and FAQ: https://groundcontrol.chat

package/bin/groundcontrol.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../daemon.mjs';

package/daemon.mjs

@@ -0,0 +1,435 @@
+// Ground Control daemon — runs on the Mac next to Claude Code.
+// Watches live sessions, encrypts everything with ChaCha20-Poly1305, and
+// publishes through the relay. The relay never sees plaintext.
+//
+//   node server/daemon.mjs [--relay ws://localhost:8787]
+//
+// First run generates a pairing key and prints a QR code + pairing string
+// for the iOS app. Key lives in ~/.groundcontrol/key.
+
+import { WebSocket } from 'ws';
+import qrcode from 'qrcode-terminal';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, execFile, execSync } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileP = promisify(execFile);
+
+// ---------- config / pairing ----------
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+  GROUND CONTROL daemon
+
+  Usage: groundcontrol [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.
+
+  Options:
+    --relay <url>   Use a custom relay (default: wss://relay.groundcontrol.chat)
+    --version       Print version
+    --help          This message
+
+  Everything is end to end encrypted with a key that never leaves your machines.
+  Docs: https://groundcontrol.chat
+`);
+  process.exit(0);
+}
+if (process.argv.includes('--version')) {
+  console.log('0.1.0');
+  process.exit(0);
+}
+
+const argRelay = (() => {
+  const i = process.argv.indexOf('--relay');
+  return i > -1 ? process.argv[i + 1] : null;
+})();
+
+const CONF_DIR = path.join(os.homedir(), '.groundcontrol');
+const KEY_FILE = path.join(CONF_DIR, 'key');
+const RELAY_FILE = path.join(CONF_DIR, 'relay');
+fs.mkdirSync(CONF_DIR, { recursive: true });
+
+if (argRelay) fs.writeFileSync(RELAY_FILE, argRelay);
+const RELAY = fs.existsSync(RELAY_FILE) ? fs.readFileSync(RELAY_FILE, 'utf8').trim() : 'wss://relay.groundcontrol.chat';
+
+let key;
+if (fs.existsSync(KEY_FILE)) {
+  key = Buffer.from(fs.readFileSync(KEY_FILE, 'utf8').trim(), 'hex');
+} else {
+  key = crypto.randomBytes(32);
+  fs.writeFileSync(KEY_FILE, key.toString('hex'), { mode: 0o600 });
+}
+const CHANNEL = crypto.createHash('sha256').update(key).digest('hex').slice(0, 32);
+
+// LAN address so a phone on the same network can reach a locally hosted relay.
+const lanIP = Object.values(os.networkInterfaces()).flat()
+  .find((i) => i && i.family === 'IPv4' && !i.internal)?.address;
+const relayForPhone = RELAY.includes('localhost') && lanIP
+  ? RELAY.replace('localhost', lanIP)
+  : RELAY;
+
+const pairPayload = Buffer.from(JSON.stringify({ v: 1, k: key.toString('base64url'), r: relayForPhone }))
+  .toString('base64url');
+const pairString = `groundcontrol://pair#${pairPayload}`;
+
+console.log('\n  GROUND CONTROL daemon');
+console.log(`  relay:   ${RELAY}  (phone will use: ${relayForPhone})`);
+console.log(`  channel: ${CHANNEL}\n`);
+qrcode.generate(pairString, { small: true });
+console.log(`\n  Pairing code (paste into the app):\n\n  ${pairString}\n`);
+
+// ---------- crypto: wire format = base64( nonce(12) | ciphertext | tag(16) ) ----------
+
+function seal(obj) {
+  const nonce = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+  const ct = Buffer.concat([cipher.update(JSON.stringify(obj), 'utf8'), cipher.final()]);
+  return Buffer.concat([nonce, ct, cipher.getAuthTag()]).toString('base64');
+}
+
+function open(b64) {
+  const buf = Buffer.from(b64, 'base64');
+  const nonce = buf.subarray(0, 12);
+  const tag = buf.subarray(buf.length - 16);
+  const ct = buf.subarray(12, buf.length - 16);
+  const decipher = crypto.createDecipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+  decipher.setAuthTag(tag);
+  const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+  return JSON.parse(pt.toString('utf8'));
+}
+
+// ---------- Claude Code session discovery ----------
+
+const CLAUDE = path.join(os.homedir(), '.claude');
+const SESSIONS_DIR = path.join(CLAUDE, 'sessions');
+const PROJECTS_DIR = path.join(CLAUDE, 'projects');
+
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+
+// ---------- terminal injection (phase 2) ----------
+// Types the prompt into the actual terminal tab hosting the session, so the
+// desktop conversation updates live. Text and Enter are sent as separate
+// chunks: Claude Code treats a same-chunk trailing newline as a paste, but a
+// separate newline as a submit keypress.
+
+const ttyByPid = new Map();
+function ttyOf(pid) {
+  if (ttyByPid.has(pid)) return ttyByPid.get(pid);
+  let tty = '';
+  try { tty = execSync(`ps -o tty= -p ${pid}`).toString().trim(); } catch {}
+  if (tty === '??') tty = '';
+  ttyByPid.set(pid, tty);
+  return tty;
+}
+
+let termCache = { at: 0, terminal: false, iterm: false, tmuxPanes: new Map() };
+function terminalApps() {
+  if (Date.now() - termCache.at < 15_000) return termCache;
+  const running = (name) => { try { return execSync(`pgrep -x "${name}"`).toString().trim() !== ''; } catch { return false; } };
+  const tmuxPanes = new Map();
+  try {
+    for (const line of execSync('tmux list-panes -a -F "#{pane_tty} #{pane_id}"', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim().split('\n')) {
+      const [tty, id] = line.split(' ');
+      if (tty && id) tmuxPanes.set(tty, id);
+    }
+  } catch {}
+  termCache = { at: Date.now(), terminal: running('Terminal'), iterm: running('iTerm2'), tmuxPanes };
+  return termCache;
+}
+
+const escapeAS = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function osascript(script) {
+  try {
+    const { stdout } = await execFileP('osascript', ['-e', script]);
+    return stdout.trim();
+  } catch { return null; }
+}
+
+function findTabScript(app, dev, action) {
+  return `tell application "${app}"
+  repeat with w in windows
+    repeat with tb in tabs of w
+      if (tty of tb) is "${dev}" then
+        ${action}
+        return "ok"
+      end if
+    end repeat
+  end repeat
+  return "notfound"
+end tell`;
+}
+
+function canInject(tty) {
+  if (!tty) return false;
+  const apps = terminalApps();
+  return apps.tmuxPanes.has(`/dev/${tty}`) || apps.terminal || apps.iterm;
+}
+
+// Returns the method used, or null if no terminal path was found.
+async function injectPrompt(tty, text) {
+  const dev = `/dev/${tty}`;
+  const apps = terminalApps();
+  const clean = text.replace(/\r?\n/g, ' ').trim();
+
+  if (apps.tmuxPanes.has(dev)) {
+    try {
+      execSync(`tmux send-keys -t '${apps.tmuxPanes.get(dev)}' -l ${JSON.stringify(clean)}`);
+      await sleep(150);
+      execSync(`tmux send-keys -t '${apps.tmuxPanes.get(dev)}' Enter`);
+      return 'tmux';
+    } catch {}
+  }
+  if (apps.iterm) {
+    const r = await osascript(`tell application "iTerm2"
+  repeat with w in windows
+    repeat with tb in tabs of w
+      repeat with s in sessions of tb
+        if (tty of s) is "${dev}" then
+          tell s to write text "${escapeAS(clean)}" newline no
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+  return "notfound"
+end tell`);
+    if (r === 'ok') {
+      await sleep(150);
+      await osascript(`tell application "iTerm2"
+  repeat with w in windows
+    repeat with tb in tabs of w
+      repeat with s in sessions of tb
+        if (tty of s) is "${dev}" then
+          tell s to write text ""
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell`);
+      return 'iterm';
+    }
+  }
+  if (apps.terminal) {
+    const r = await osascript(findTabScript('Terminal', dev, `do script "${escapeAS(clean)}" in tb`));
+    if (r === 'ok') {
+      await sleep(200);
+      await osascript(findTabScript('Terminal', dev, 'do script "" in tb'));
+      return 'terminal';
+    }
+  }
+  return null;
+}
+
+const headlessActive = new Set(); // sessionIds with a headless --resume in flight
+
+const transcriptCache = new Map(); // sessionId -> file path
+
+function findTranscript(sessionId) {
+  if (transcriptCache.has(sessionId)) {
+    const p = transcriptCache.get(sessionId);
+    if (p && fs.existsSync(p)) return p;
+  }
+  try {
+    for (const dir of fs.readdirSync(PROJECTS_DIR)) {
+      const p = path.join(PROJECTS_DIR, dir, `${sessionId}.jsonl`);
+      if (fs.existsSync(p)) { transcriptCache.set(sessionId, p); return p; }
+    }
+  } catch {}
+  transcriptCache.set(sessionId, null);
+  return null;
+}
+
+function extractText(message) {
+  const c = message?.content;
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) {
+    return c.filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+  }
+  return '';
+}
+
+function readMessages(sessionId, maxBytes = 512 * 1024, limit = 80) {
+  const file = findTranscript(sessionId);
+  if (!file) return [];
+  let raw;
+  try {
+    const size = fs.statSync(file).size;
+    const fd = fs.openSync(file, 'r');
+    const start = Math.max(0, size - maxBytes);
+    const buf = Buffer.alloc(size - start);
+    fs.readSync(fd, buf, 0, buf.length, start);
+    fs.closeSync(fd);
+    raw = buf.toString('utf8');
+  } catch { return []; }
+
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let e; try { e = JSON.parse(line); } catch { continue; }
+    if (e.isSidechain) continue;
+    const role = e.message?.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const text = extractText(e.message).trim();
+    if (!text || /^(<system-reminder>|<command-name>|<local-command|<command-message|\[Request interrupted|\[SYSTEM NOTIFICATION)/.test(text)) continue;
+    out.push({ role, text: text.slice(0, 4000), ts: e.timestamp || null });
+  }
+  return out.slice(-limit);
+}
+
+function readSessions() {
+  const sessions = [];
+  let files = [];
+  try { files = fs.readdirSync(SESSIONS_DIR); } catch {}
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    let s;
+    try { s = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, f), 'utf8')); } catch { continue; }
+    if (!s.sessionId || !pidAlive(s.pid)) continue;
+    const msgs = readMessages(s.sessionId, 64 * 1024, 1);
+    const tty = ttyOf(s.pid);
+    sessions.push({
+      id: s.sessionId,
+      name: s.name || path.basename(s.cwd || '?'),
+      cwd: s.cwd || '',
+      project: path.basename(s.cwd || '?'),
+      status: headlessActive.has(s.sessionId) ? 'busy' : (s.status || 'idle'),
+      updatedAt: s.statusUpdatedAt || s.updatedAt || 0,
+      startedAt: s.startedAt || 0,
+      lastMessage: msgs.length ? msgs[msgs.length - 1] : null,
+      tty,
+      live: canInject(tty),
+    });
+  }
+  sessions.sort((a, b) => a.startedAt - b.startedAt);
+  return sessions;
+}
+
+// ---------- relay connection ----------
+
+let ws = null;
+let lastSnapshotJson = '';
+
+function sendSnapshot(force = false) {
+  const sessions = readSessions();
+  const json = JSON.stringify(sessions.map(({ lastMessage, ...s }) => ({ ...s, last: lastMessage?.text?.slice(0, 120) })));
+  if (!force && json === lastSnapshotJson) return;
+  lastSnapshotJson = json;
+  if (ws?.readyState === 1) {
+    ws.send(seal({ type: 'snapshot', at: Date.now(), sessions }));
+    console.log(`[daemon] snapshot -> ${sessions.length} session(s): ${sessions.map((s) => `${s.name}:${s.status}`).join(', ') || 'none'}`);
+  }
+}
+
+// Live transcript streaming: while a phone has a chat open, push transcript
+// updates the moment the JSONL file changes.
+const watchers = new Map(); // sessionId -> fs.FSWatcher
+function watchTranscript(sessionId) {
+  if (watchers.has(sessionId)) return;
+  const file = findTranscript(sessionId);
+  if (!file) return;
+  let debounce;
+  try {
+    const w = fs.watch(file, () => {
+      clearTimeout(debounce);
+      debounce = setTimeout(() => {
+        ws?.send(seal({ type: 'transcript', sessionId, messages: readMessages(sessionId) }));
+      }, 250);
+    });
+    watchers.set(sessionId, w);
+    console.log(`[daemon] watching transcript ${sessionId.slice(0, 8)}`);
+  } catch {}
+}
+function unwatchTranscript(sessionId) {
+  watchers.get(sessionId)?.close();
+  watchers.delete(sessionId);
+}
+
+async function handleCommand(cmd) {
+  if (cmd.type === 'getTranscript' && cmd.sessionId) {
+    ws?.send(seal({ type: 'transcript', sessionId: cmd.sessionId, messages: readMessages(cmd.sessionId) }));
+  } else if (cmd.type === 'watch' && cmd.sessionId) {
+    watchTranscript(cmd.sessionId);
+    ws?.send(seal({ type: 'transcript', sessionId: cmd.sessionId, messages: readMessages(cmd.sessionId) }));
+  } else if (cmd.type === 'unwatch' && cmd.sessionId) {
+    unwatchTranscript(cmd.sessionId);
+  } else if (cmd.type === 'ping' && cmd.sessionId) {
+    const s = readSessions().find((x) => x.id === cmd.sessionId);
+    ws?.send(seal({ type: 'pong', sessionId: cmd.sessionId, alive: !!s, status: s?.status || 'gone', at: Date.now() }));
+  } else if (cmd.type === 'prompt' && cmd.sessionId && cmd.text) {
+    const session = readSessions().find((s) => s.id === cmd.sessionId);
+    if (!session) return ws?.send(seal({ type: 'promptResult', sessionId: cmd.sessionId, ok: false, error: 'session not found' }));
+
+    // Preferred path: type into the real terminal so the desktop updates live.
+    if (session.live) {
+      const method = await injectPrompt(session.tty, cmd.text);
+      if (method) {
+        console.log(`[daemon] injected prompt into ${session.name} via ${method}`);
+        ws?.send(seal({ type: 'promptResult', sessionId: cmd.sessionId, ok: true, text: '' }));
+        watchTranscript(cmd.sessionId);
+        sendSnapshot(true);
+        return;
+      }
+    }
+    if (session.status === 'busy') return ws?.send(seal({ type: 'promptResult', sessionId: cmd.sessionId, ok: false, error: 'session is busy — wait for it to go idle' }));
+    console.log(`[daemon] prompt -> ${session.name}: ${cmd.text.slice(0, 60)}`);
+    headlessActive.add(cmd.sessionId);
+    sendSnapshot(true);
+    const child = spawn('claude', ['--resume', cmd.sessionId, '-p', cmd.text], {
+      cwd: session.cwd || os.homedir(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '', err = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    child.on('close', (code) => {
+      headlessActive.delete(cmd.sessionId);
+      ws?.send(seal({
+        type: 'promptResult', sessionId: cmd.sessionId, ok: code === 0,
+        text: (out || err).trim().slice(0, 4000),
+      }));
+      sendSnapshot(true);
+    });
+  }
+}
+
+let lastPongAt = Date.now();
+
+function connect() {
+  ws = new WebSocket(`${RELAY}/ch/${CHANNEL}?role=host`);
+  ws.on('open', () => { lastPongAt = Date.now(); console.log('[daemon] connected to relay'); sendSnapshot(true); });
+  ws.on('pong', () => { lastPongAt = Date.now(); });
+  ws.on('message', (data) => {
+    const str = data.toString();
+    if (str === '{"sys":"client-joined"}') { console.log('[daemon] phone connected'); sendSnapshot(true); return; }
+    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('error', () => {});
+}
+
+connect();
+setInterval(sendSnapshot, 1500);
+// Heartbeat traffic keeps the Cloudflare socket alive in both directions and
+// lets the phone detect a dead link; missing pongs force a reconnect here.
+setInterval(() => {
+  if (ws?.readyState === 1) {
+    ws.ping();
+    ws.send(seal({ type: 'hb', at: Date.now() }));
+    if (Date.now() - lastPongAt > 65_000) {
+      console.log('[daemon] stale relay link, forcing reconnect');
+      ws.terminate();
+    }
+  }
+}, 20_000);
+try { fs.watch(SESSIONS_DIR, () => sendSnapshot()); } catch {}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@clastres/groundcontrol",
+  "version": "0.1.0",
+  "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" },
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.0"
+  },
+  "keywords": ["claude", "claude-code", "ai", "agents", "cli", "ios", "remote", "monitor"],
+  "homepage": "https://groundcontrol.chat",
+  "author": "Carlos Lastres",
+  "license": "MIT"
+}