offhands 0.1.1

package/README.internal.md

@@ -0,0 +1,49 @@
+# offhands — internal README (do not publish)
+
+The public npm README is intentionally blank ("Reserved.") until launch —
+founder decision 2026-09-07: stay lowkey, don't hand the idea to copycats.
+This file is the real one; swap it back into README.md at launch.
+
+---
+
+Drive your coding agents from your phone. `offhands` runs a small daemon on
+your computer that wraps headless agent CLIs (Claude Code today, GitHub
+Copilot CLI, more coming) and pairs with a phone app over an end-to-end
+encrypted relay — the server only ever sees ciphertext.
+
+From your phone you can:
+
+- start sessions in any workspace and prompt any installed agent
+- **approve or deny risky actions** with a diff preview before they run
+- answer the agent's questions with real option buttons
+- switch model / permission mode / thinking effort mid-session
+- watch context-window usage and per-session cost
+- get receipts (files changed, diffs, screenshots) for every run
+- **drop files and text** between phone and PC, encrypted both ways
+
+## Quick start
+
+```bash
+cd your-project
+npx offhands
+```
+
+Scan the QR it prints with your phone (or open the web app and type the
+code), match the fingerprint shown on both screens, and you're paired.
+
+Requires Node 22.5+ and at least one agent CLI installed.
+
+## Options
+
+```
+offhands [--workspace <path>]... [--dev-url <url>] [--relay <url>]
+         [--repair] [--approval-timeout <seconds>] [--local]
+offhands drop <file>     # send a file to your paired phone
+```
+
+## Security
+
+- X25519 key exchange at pairing; all traffic is libsodium secretbox
+- pairing codes are one-time; both screens show a fingerprint to verify
+- the relay stores nothing and can read nothing
+- approvals are enforced in the daemon, not in the UI

package/README.md

@@ -0,0 +1,3 @@
+# offhands
+
+Reserved.

package/approval-mcp.mjs

@@ -0,0 +1,98 @@
+// offhand approval MCP server (plain JS, zero deps — spawned BY claude).
+// Newline-delimited JSON-RPC 2.0 over stdio. Exposes one tool,
+// `approval_prompt`, named via --permission-prompt-tool
+// mcp__offhand__approval_prompt. Each call is forwarded to the daemon's
+// local HTTP endpoint (OFFHAND_APPROVAL_URL) which long-polls the phone's
+// verdict, then this returns allow/deny to claude.
+
+import { createInterface } from 'node:readline';
+
+const APPROVAL_URL = process.env.OFFHAND_APPROVAL_URL ?? 'http://127.0.0.1:4317/approval';
+
+const TOOL = {
+  name: 'approval_prompt',
+  description: 'Forwards a permission request to the offhand phone client and waits for the verdict.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tool_name: { type: 'string' },
+      input: { type: 'object' },
+      tool_use_id: { type: 'string' },
+    },
+    required: ['tool_name', 'input'],
+  },
+};
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function reply(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function callDaemon(args) {
+  const res = await fetch(APPROVAL_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ toolName: args.tool_name, input: args.input ?? {} }),
+  });
+  if (!res.ok) return { approve: false, message: `daemon said ${res.status}` };
+  return res.json();
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  void handle(msg);
+});
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  if (id === undefined || id === null) return; // notification — nothing to do
+
+  switch (method) {
+    case 'initialize':
+      reply(id, {
+        protocolVersion: params?.protocolVersion ?? '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'offhand-approvals', version: '0.0.1' },
+      });
+      return;
+    case 'tools/list':
+      reply(id, { tools: [TOOL] });
+      return;
+    case 'tools/call': {
+      if (params?.name !== TOOL.name) {
+        replyError(id, -32602, `unknown tool: ${params?.name}`);
+        return;
+      }
+      let decision;
+      try {
+        const verdict = await callDaemon(params.arguments ?? {});
+        decision = verdict.approve
+          ? { behavior: 'allow', updatedInput: params.arguments?.input ?? {} }
+          : { behavior: 'deny', message: verdict.message ?? 'denied from phone' };
+      } catch (e) {
+        decision = { behavior: 'deny', message: `approval channel error: ${e?.message ?? e}` };
+      }
+      reply(id, { content: [{ type: 'text', text: JSON.stringify(decision) }] });
+      return;
+    }
+    case 'ping':
+      reply(id, {});
+      return;
+    default:
+      replyError(id, -32601, `method not found: ${method}`);
+  }
+}

package/bin/offhands.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// offhands launcher: friendly guard rails BEFORE loading the real daemon
+// (which needs node:sqlite, Node >= 22.5 — a raw import error would be
+// unreadable for someone who just ran `npx offhands`).
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 5)) {
+  console.error(
+    `offhands needs Node 22.5 or newer (you have ${process.versions.node}).\n` +
+      `  → with nvm:      nvm install 22 && nvm use 22\n` +
+      `  → or download:   https://nodejs.org`,
+  );
+  process.exit(1);
+}
+
+// Default to the hosted relay so `npx offhands` pairs out of the box;
+// explicit --relay (or --local for localhost-only use) still wins.
+if (!process.argv.includes('--relay') && !process.argv.includes('--local')) {
+  process.argv.push('--relay', 'https://offhand-relay.onrender.com');
+}
+
+await import('../dist/daemon.mjs');