@idl3/claude-control 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 idl3
+
+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

@@ -0,0 +1,144 @@
+# claude-control
+
+A tiny, local web UI to **watch and drive your Claude Code sessions from a
+browser or phone**. It discovers the Claude sessions you already run inside
+**tmux**, streams each session's transcript live, lets you reply, answer
+`AskUserQuestion` prompts, attach screenshots/files, and capture the pane — all
+over `127.0.0.1` (or your Tailscale tailnet), guarded by a token.
+
+No daemon to babysit, no database: it reads Claude Code's transcript files and
+talks to tmux. Bind is localhost-only by default.
+
+---
+
+## Install (npm)
+
+```bash
+npm install -g @idl3/claude-control     # or run once: npx @idl3/claude-control
+```
+
+**Prerequisites:** Node ≥20 and **tmux** on your `PATH` (`brew install tmux` · `sudo apt install tmux`). The web UI ships prebuilt — no build step on install.
+
+```bash
+claude-control                    # start the server (prints the URL)
+claude-control --help             # config + subcommands
+claude-control install-service    # macOS: launchd auto-start on login + restart on crash
+claude-control uninstall-service
+```
+
+Open the printed URL. If a token is configured (env `CLAUDE_CONTROL_TOKEN`, or a
+token in `~/.claude-control/token`), the app **prompts for it on first load** and
+stores it in your browser — the token is never placed in the URL. With no token
+set, it runs open on `127.0.0.1` / your tailnet.
+
+---
+
+## Quick start (from source)
+
+```bash
+git clone https://github.com/idl3/claude-control.git
+cd claude-control
+npm install
+npm run build        # builds the web UI (web/dist)
+npm start            # prints a URL with a token
+```
+
+Open the printed URL (e.g. `http://127.0.0.1:4317/?token=…`). Any Claude Code
+session running in tmux shows up in the left rail.
+
+> **Already have tmux running with Claude sessions?** You're done — just run
+> `npm start` and they appear automatically.
+
+---
+
+## The tmux setup (the one requirement)
+
+claude-control manages sessions **through tmux**: it lists tmux windows, finds
+the ones running Claude Code, and sends your replies as keystrokes to the right
+pane. So your Claude sessions need to live in tmux.
+
+### A) You already use tmux
+
+Nothing to do. claude-control reads your **default tmux server** (the same one
+`tmux ls` shows). Start it and your sessions appear. To point at a non-default
+tmux binary, set `CLAUDE_CONTROL_TMUX=/path/to/tmux`.
+
+### B) You don't use tmux yet
+
+Install it and run Claude *inside* a tmux session so claude-control can see it:
+
+```bash
+# macOS: brew install tmux   ·   Debian/Ubuntu: sudo apt install tmux
+
+tmux new -s work       # start (or attach) a tmux session
+claude                 # run Claude Code inside it — now it's discoverable
+```
+
+That's it. Open more windows (`Ctrl-b c`) and run more Claude sessions; each
+becomes a row in claude-control. (Tip: detach with `Ctrl-b d` — the sessions
+keep running and stay visible in claude-control.)
+
+A session is recognized when its pane is running Claude Code **or** has a
+matching transcript under `~/.claude/projects/`.
+
+---
+
+## Updating
+
+claude-control compares your checkout against its git upstream (`origin`) and
+shows an **update banner** when new commits are available. Click **Update now**
+— the server pulls, reinstalls, rebuilds the web bundle, and restarts itself in
+place; the page reconnects automatically. (Equivalent manual update: `git pull
+&& npm install && npm run build`, then restart.)
+
+Version numbers follow npm semver (bump `package.json` per release); this is
+**v0.1.0**.
+
+---
+
+## Configuration
+
+All optional. Prefer `CLAUDE_CONTROL_*`; legacy `COCKPIT_*` names still work.
+
+| Env | Default | Purpose |
+|---|---|---|
+| `CLAUDE_CONTROL_PORT` | `4317` | HTTP/WS port |
+| `CLAUDE_CONTROL_HOST` | `127.0.0.1` | Bind address |
+| `CLAUDE_CONTROL_TOKEN` | _(none)_ | Require `?token=` on every request (recommended if exposed beyond localhost) |
+| `CLAUDE_CONTROL_PROJECTS` | `~/.claude/projects` | Where Claude Code transcripts live |
+| `CLAUDE_CONTROL_UPLOADS` | `~/.claude-control/uploads` | Where attachments are stored (TTL-swept) |
+| `CLAUDE_CONTROL_TMUX` | _(auto)_ | tmux binary override |
+| `CLAUDE_CONTROL_MAX_UPLOAD_MB` | `25` | Per-file upload cap |
+
+---
+
+## Security
+
+- Binds `127.0.0.1` by default; cross-origin WebSocket upgrades are rejected.
+- Set `CLAUDE_CONTROL_TOKEN` before exposing it (e.g. via `tailscale serve`) —
+  **this UI can type into your live sessions.**
+- Uploads are written `0600` under the uploads dir and swept after a TTL.
+
+---
+
+## How it works
+
+- **Discovery** — polls `tmux list-windows` every few seconds and matches each
+  window to the newest transcript for its cwd (`lib/sessions.js`).
+- **Transcript** — tails each subscribed session's `*.jsonl` (bounded reads)
+  and streams appends over WebSocket (`lib/transcript.js`).
+- **Input** — replies and answers are sent with `tmux send-keys` to the exact
+  pane (`lib/tmux.js`); attachments upload to the uploads dir and their path is
+  appended to the message for Claude to read.
+
+## Development
+
+```bash
+npm run dev             # server with --watch
+cd web && npm run dev   # Vite dev server for the UI
+npm test                # node:test unit tests
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// claude-control CLI entry. Default action starts the server (server.js runs on
+// import); subcommands wrap the launchd service scripts and version/help.
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.join(__dirname, '..');
+const pkg = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+const cmd = process.argv[2];
+
+function runScript(name) {
+  const child = spawn('/bin/bash', [path.join(ROOT, 'bin', name)], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+switch (cmd) {
+  case '-v':
+  case '--version':
+    console.log(pkg.version);
+    break;
+
+  case '-h':
+  case '--help':
+    console.log(`claude-control v${pkg.version}
+Local web UI to watch and drive Claude Code tmux sessions.
+
+Usage:
+  claude-control [start]        Start the server (default)
+  claude-control install-service    Install the launchd service (macOS): auto-start + restart
+  claude-control uninstall-service  Remove the launchd service
+  claude-control --version
+  claude-control --help
+
+Config (env vars, all optional):
+  CLAUDE_CONTROL_PORT     (default 4317)
+  CLAUDE_CONTROL_HOST     (default 127.0.0.1)
+  CLAUDE_CONTROL_TOKEN    token auth; also read from ~/.claude-control/token.
+                          Unset + no file = tokenless (relies on bind/tailnet).
+  CLAUDE_CONTROL_PROJECTS (default ~/.claude/projects)
+
+Requires: Node >=20 and tmux on PATH.`);
+    break;
+
+  case 'install-service':
+    runScript('install-service.sh');
+    break;
+
+  case 'uninstall-service':
+    runScript('uninstall-service.sh');
+    break;
+
+  case undefined:
+  case 'start':
+    // server.js executes main() on import.
+    await import(path.join(ROOT, 'server.js'));
+    break;
+
+  default:
+    console.error(`unknown command: ${cmd}\nrun "claude-control --help"`);
+    process.exit(1);
+}

package/bin/install-service.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Install claude-control as a launchd service: auto-start on login, restart on
+# crash. Token auth is OPTIONAL: gates on ~/.claude-control/token if present,
+# else runs tokenless (tailnet-only). Idempotent — safe to re-run after updates.
+set -euo pipefail
+
+LABEL="com.ernest.claude-control"
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CONFIG_DIR="$HOME/.claude-control"
+TOKEN_FILE="$CONFIG_DIR/token"
+LOG_DIR="$CONFIG_DIR/logs"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+PORT="${CLAUDE_CONTROL_PORT:-4317}"
+
+mkdir -p "$CONFIG_DIR" "$LOG_DIR" "$HOME/Library/LaunchAgents"
+
+# Token (OPTIONAL): if ~/.claude-control/token exists, gate the UI on it;
+# otherwise run tokenless — open to anything that can reach the port (the
+# 127.0.0.1 bind + tailnet ACL + cross-origin check are the remaining guards).
+# To (re-)enable token auth: write a token to that file and re-run this script.
+TOKEN="$(cat "$TOKEN_FILE" 2>/dev/null || true)"
+if [ -n "$TOKEN" ]; then
+  TOKEN_ENV="    <key>CLAUDE_CONTROL_TOKEN</key><string>$TOKEN</string>"
+else
+  TOKEN_ENV=""
+  echo "no token file ($TOKEN_FILE) — installing TOKENLESS (open on the tailnet)"
+fi
+
+# launchd runs with a minimal PATH — resolve absolute binaries and a PATH that
+# lets the server find tmux.
+NODE_BIN="$(command -v node)"
+TMUX_BIN="$(command -v tmux 2>/dev/null || echo /opt/homebrew/bin/tmux)"
+TMUX_DIR="$(dirname "$TMUX_BIN")"
+SVC_PATH="$TMUX_DIR:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+# launchd gives a LaunchAgent a different $TMPDIR than the login session, so the
+# bundled tmux can't find the running server's socket (-> 0 sessions). Pin
+# TMUX_TMPDIR to where the socket actually lives.
+TMUX_TMPDIR_VAL="$("$TMUX_BIN" display-message -p '#{socket_path}' 2>/dev/null | sed -E 's#/tmux-[0-9]+/[^/]+$##')"
+if [ -z "$TMUX_TMPDIR_VAL" ]; then
+  for d in /private/tmp /tmp "${TMPDIR:-}"; do
+    [ -n "$d" ] && [ -S "$d/tmux-$(id -u)/default" ] && { TMUX_TMPDIR_VAL="$d"; break; }
+  done
+fi
+TMUX_TMPDIR_VAL="${TMUX_TMPDIR_VAL:-/tmp}"
+echo "tmux socket dir: $TMUX_TMPDIR_VAL"
+
+# Build the web bundle if absent (server falls back to public/ otherwise).
+if [ ! -f "$REPO/web/dist/index.html" ]; then
+  echo "building web bundle…"; (cd "$REPO" && npm run build)
+fi
+
+# Stop any manually-launched server already holding the port.
+EXISTING="$(lsof -nP -iTCP:"$PORT" -sTCP:LISTEN -t 2>/dev/null || true)"
+if [ -n "$EXISTING" ]; then echo "stopping existing server (pid $EXISTING)"; kill $EXISTING 2>/dev/null || true; sleep 1; fi
+
+cat > "$PLIST" <<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>$NODE_BIN</string>
+    <string>$REPO/server.js</string>
+  </array>
+  <key>WorkingDirectory</key><string>$REPO</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+$TOKEN_ENV
+    <key>CLAUDE_CONTROL_PORT</key><string>$PORT</string>
+    <key>HOME</key><string>$HOME</string>
+    <key>PATH</key><string>$SVC_PATH</string>
+    <key>TMUX_TMPDIR</key><string>$TMUX_TMPDIR_VAL</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>5</integer>
+  <key>StandardOutPath</key><string>$LOG_DIR/out.log</string>
+  <key>StandardErrorPath</key><string>$LOG_DIR/err.log</string>
+</dict>
+</plist>
+PLIST
+
+launchctl unload "$PLIST" 2>/dev/null || true
+launchctl load "$PLIST"
+
+# Expose over Tailscale (tailnet-only HTTPS). Harmless if already configured.
+if command -v tailscale >/dev/null 2>&1; then
+  tailscale serve --bg --https=443 "localhost:$PORT" >/dev/null 2>&1 || true
+fi
+
+HOSTDNS="$(tailscale status --json 2>/dev/null | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{process.stdout.write((JSON.parse(d).Self?.DNSName||"").replace(/\.$/,""))}catch{}})' 2>/dev/null || true)"
+
+BASE="$([ -n "$HOSTDNS" ] && echo "https://$HOSTDNS/" || echo "http://127.0.0.1:$PORT/")"
+echo ""
+echo "✓ claude-control installed as $LABEL (auto-starts on login, restarts on crash)"
+echo "  logs:  $LOG_DIR/{out,err}.log"
+echo "  url:   $BASE"
+if [ -n "$TOKEN" ]; then
+  # Don't put the token in the URL (it leaks via history/logs); the web app
+  # prompts for it and stores it in localStorage.
+  echo "  auth:  token — enter it at the login prompt: $TOKEN"
+else
+  echo "  auth:  TOKENLESS (tailnet-only)"
+fi

package/bin/self-update.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# claude-control self-update — invoked by POST /api/update (the in-UI "Update
+# now" button). Pulls the latest source, reinstalls deps, rebuilds the web
+# bundle, then restarts the server in place. Runs DETACHED from the server it
+# restarts, so killing the old process can't kill this script.
+#
+# Inherits the server's env (token/port/host), so the relaunched server keeps
+# the same configuration. All output goes to the update log.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+DATA_DIR="${CLAUDE_CONTROL_DATA:-$HOME/.claude-control}"
+mkdir -p "$DATA_DIR"
+LOG="$DATA_DIR/update.log"
+PORT="${CLAUDE_CONTROL_PORT:-${COCKPIT_PORT:-4317}}"
+
+{
+  echo "=== self-update $(date) (port $PORT) ==="
+
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git pull --ff-only && echo "git pull ok" || echo "git pull skipped/failed"
+  else
+    echo "not a git checkout — skipping git pull"
+  fi
+
+  npm install --no-audit --no-fund && echo "root deps ok" || echo "root deps failed"
+  ( cd web && npm install --no-audit --no-fund && npm run build ) \
+    && echo "web build ok" || echo "web build failed"
+
+  # Restart: stop whatever holds the port, then relaunch with the inherited env.
+  OLD="$(lsof -ti tcp:"$PORT" 2>/dev/null || true)"
+  if [ -n "$OLD" ]; then kill $OLD 2>/dev/null || true; fi
+  for _ in 1 2 3 4 5 6; do
+    lsof -ti tcp:"$PORT" >/dev/null 2>&1 || break
+    sleep 1
+  done
+
+  nohup node "$ROOT/server.js" > "$DATA_DIR/server.log" 2>&1 </dev/null &
+  echo "restarted server pid $!"
+} >> "$LOG" 2>&1

package/bin/uninstall-service.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Remove the claude-control launchd service. Leaves the token + uploads intact.
+set -euo pipefail
+
+LABEL="com.ernest.claude-control"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+PORT="${CLAUDE_CONTROL_PORT:-4317}"
+
+if [ -f "$PLIST" ]; then
+  launchctl unload "$PLIST" 2>/dev/null || true
+  rm -f "$PLIST"
+  echo "✓ removed $LABEL"
+else
+  echo "service not installed ($PLIST not found)"
+fi
+
+# Optional: stop tailscale serve for this port.
+if command -v tailscale >/dev/null 2>&1; then
+  tailscale serve --https=443 off >/dev/null 2>&1 || true
+  echo "  tailscale serve stopped"
+fi
+echo "  (token + uploads under ~/.claude-control are left in place)"

package/lib/answer.js

@@ -0,0 +1,64 @@
+// Translate an AskUserQuestion selection into Claude Code TUI picker keystrokes.
+//
+// Verified against the live Claude Code picker (a multi-question tabbed UI):
+//   - Options are NUMBERED (1..N) in question.options order, with extra meta
+//     options ("Type something", "Chat about this") appended after.
+//   - SINGLE-select: pressing the option's number selects it AND auto-advances
+//     to the next question tab.
+//   - MULTI-select: pressing a number TOGGLES that option (cursor stays); press
+//     Right (→) to advance to the next tab.
+//   - After the last question the picker lands on the "Submit" tab showing
+//     "1. Submit answers / 2. Cancel"; pressing "1" commits all answers.
+// Keys are sent one at a time with a small delay (see tmux.sendRawKeysSequenced)
+// so the single-select auto-advance re-render completes before the next key.
+
+const MAX_NUMBERED = 9; // number-key selection only works for options 1..9
+
+function numberKey(optionIndex) {
+  const n = optionIndex + 1;
+  if (n > MAX_NUMBERED) {
+    throw new Error(`option #${n} beyond number-key range (1..${MAX_NUMBERED})`);
+  }
+  return String(n);
+}
+
+/**
+ * Keys to answer ONE question (not including the final Submit).
+ * @param {{multiSelect?: boolean, options: {label:string}[]}} question
+ * @param {string[]} selectedLabels
+ * @returns {string[]}
+ */
+export function buildAnswerKeys(question, selectedLabels) {
+  const options = Array.isArray(question?.options) ? question.options : [];
+  const indices = (selectedLabels || [])
+    .map((label) => options.findIndex((o) => o.label === label))
+    .filter((i) => i >= 0)
+    .sort((a, b) => a - b);
+
+  if (indices.length === 0) throw new Error('no valid option selected for question');
+
+  if (!question.multiSelect) {
+    // Selecting a numbered option auto-advances to the next tab.
+    return [numberKey(indices[0])];
+  }
+  // Toggle each chosen option, then advance to the next tab with Right.
+  return [...indices.map(numberKey), 'Right'];
+}
+
+/**
+ * Full key program for a (possibly multi-question) AskUserQuestion, ending with
+ * the Submit-tab confirmation.
+ * @param {{questions: object[]}} pending
+ * @param {string[][]} selections  selections[i] = chosen labels for questions[i]
+ * @returns {string[]}
+ */
+export function buildAnswerProgram(pending, selections) {
+  const questions = pending?.questions || [];
+  if (questions.length === 0) throw new Error('pending has no questions');
+  const program = [];
+  for (let i = 0; i < questions.length; i += 1) {
+    program.push(...buildAnswerKeys(questions[i], selections?.[i] || []));
+  }
+  program.push('1'); // "Submit answers" on the Submit tab
+  return program;
+}

package/lib/auth.js

@@ -0,0 +1,81 @@
+// Request authentication for claude-control.
+//
+// Tokens NEVER ride the URL anymore (URLs leak via history/logs/referrer).
+// Instead:
+//   - HTTP/API requests carry the token in `Authorization: Bearer <token>`.
+//   - WebSocket upgrades carry it as a `Sec-WebSocket-Protocol` value, because
+//     browsers cannot set arbitrary headers on `new WebSocket(...)` but CAN
+//     offer subprotocols.
+//
+// Tokenless mode (no token configured server-side) stays fully open: every
+// check returns true and the client shows no login prompt.
+//
+// The ttyd raw-terminal surface is the ONE exception — it is opened via
+// window.open to a separately-proxied URL that cannot send an Authorization
+// header, so it keeps its own `?token=` mechanism (handled in server.js's
+// /term/ branch, not here).
+
+// A dedicated subprotocol label the client always offers alongside the token,
+// so the server can select a non-secret protocol to echo back (some proxies /
+// strict clients want a selection) without ever reflecting the raw token.
+export const WS_PROTOCOL = 'claude-control';
+
+/**
+ * Extract the bearer token from an incoming HTTP request's Authorization
+ * header. Scheme match is case-insensitive ("Bearer", "bearer", "BEARER").
+ * Returns the token string, or null when absent/malformed.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {string|null}
+ */
+export function tokenFromRequest(req) {
+  const header = req?.headers?.authorization;
+  if (typeof header !== 'string') return null;
+  const m = /^\s*Bearer\s+(.+)\s*$/i.exec(header);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Authenticate an HTTP/API request against the configured token.
+ *
+ * Tokenless server → always authorized. Otherwise the request must present the
+ * exact token via `Authorization: Bearer <token>`.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {string|null|undefined} configToken
+ * @returns {boolean}
+ */
+export function checkToken(req, configToken) {
+  if (!configToken) return true;
+  return tokenFromRequest(req) === configToken;
+}
+
+/**
+ * Parse the offered WebSocket subprotocols from a `Sec-WebSocket-Protocol`
+ * header value (comma-separated, each entry trimmed). Returns [] when absent.
+ *
+ * @param {string|undefined} headerValue
+ * @returns {string[]}
+ */
+export function parseWsProtocols(headerValue) {
+  if (typeof headerValue !== 'string') return [];
+  return headerValue
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Authenticate a WebSocket upgrade against the configured token. The client
+ * offers the token as one of its subprotocols (alongside WS_PROTOCOL). Tokenless
+ * server → always authorized.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {string|null|undefined} configToken
+ * @returns {boolean}
+ */
+export function checkWsToken(req, configToken) {
+  if (!configToken) return true;
+  const offered = parseWsProtocols(req?.headers?.['sec-websocket-protocol']);
+  return offered.includes(configToken);
+}

package/lib/config.js

@@ -0,0 +1,118 @@
+/**
+ * lib/config.js — tiny persisted config store.
+ *
+ * Holds the operator-editable settings that drive "new session" creation:
+ * the launch command to run in a fresh tmux window (default "claude", but
+ * overridable to a shell alias like `yolo` or `claude --flags`) and the
+ * default cwd new sessions start in.
+ *
+ * Persisted at ~/.claude-control/config.json (honour CLAUDE_CONTROL_DATA when
+ * set, matching server.js's env-override convention). Reads never throw —
+ * defaults are merged over whatever's on disk. Writes validate strictly and
+ * use mode 0600 (same as the uploads handler) since this is a single-user
+ * localhost tool.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// Env lookup mirrors server.js: prefer CLAUDE_CONTROL_<X>, fall back to the
+// legacy COCKPIT_<X> so existing launchers keep working.
+const env = (name) =>
+  process.env[`CLAUDE_CONTROL_${name}`] ?? process.env[`COCKPIT_${name}`];
+
+/** Resolve the data directory (CLAUDE_CONTROL_DATA or ~/.claude-control). */
+function dataDir() {
+  return env('DATA') || path.join(os.homedir(), '.claude-control');
+}
+
+/** Absolute path to the config file. */
+function configPath() {
+  return path.join(dataDir(), 'config.json');
+}
+
+const LAUNCH_MAX = 500;
+
+/** Defaults, recomputed each call so a changed HOME/env is honoured. */
+function defaults() {
+  return {
+    launchCommand: 'claude',
+    defaultCwd: os.homedir(),
+  };
+}
+
+/**
+ * Read the persisted config, merged over defaults. Never throws — a missing,
+ * empty, or corrupt file falls back to defaults. Only known keys are surfaced.
+ *
+ * @returns {{ launchCommand: string, defaultCwd: string }}
+ */
+export function readConfig() {
+  const base = defaults();
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+  } catch {
+    return base;
+  }
+  if (!parsed || typeof parsed !== 'object') return base;
+  return {
+    launchCommand:
+      typeof parsed.launchCommand === 'string' && parsed.launchCommand.trim()
+        ? parsed.launchCommand
+        : base.launchCommand,
+    defaultCwd:
+      typeof parsed.defaultCwd === 'string' && parsed.defaultCwd.trim()
+        ? parsed.defaultCwd
+        : base.defaultCwd,
+  };
+}
+
+/**
+ * Validate a partial update against the current config and persist the merged
+ * result. Throws on validation failure (the caller maps that to HTTP 400).
+ *
+ * Validation:
+ *  - launchCommand: non-empty string, ≤500 chars.
+ *  - defaultCwd: a path that exists and is a directory.
+ *
+ * @param {{ launchCommand?: unknown, defaultCwd?: unknown }} partial
+ * @returns {{ launchCommand: string, defaultCwd: string }} the saved config
+ */
+export function writeConfig(partial = {}) {
+  const current = readConfig();
+  const next = { ...current };
+
+  if (partial.launchCommand !== undefined) {
+    const cmd = partial.launchCommand;
+    if (typeof cmd !== 'string' || !cmd.trim()) {
+      throw new Error('launchCommand must be a non-empty string');
+    }
+    if (cmd.length > LAUNCH_MAX) {
+      throw new Error(`launchCommand must be ≤${LAUNCH_MAX} characters`);
+    }
+    next.launchCommand = cmd;
+  }
+
+  if (partial.defaultCwd !== undefined) {
+    const cwd = partial.defaultCwd;
+    if (typeof cwd !== 'string' || !cwd.trim()) {
+      throw new Error('defaultCwd must be a non-empty string');
+    }
+    let stat;
+    try {
+      stat = fs.statSync(cwd);
+    } catch {
+      throw new Error(`defaultCwd does not exist: ${cwd}`);
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`defaultCwd is not a directory: ${cwd}`);
+    }
+    next.defaultCwd = cwd;
+  }
+
+  const dir = dataDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(next, null, 2), { mode: 0o600 });
+  return next;
+}