@claudecollab/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,124 +1,111 @@
 # ✦ claudecollab
 
-**Multiplayer for your Claude Code session.** You run one command. Friends open a link — no install — and drive the same Claude with you: live cursors, shared drafts, a visible queue, roles.
+**Use Claude Code with your friends.** You run one command. Your friends open a link and can collaborate with the same Claude as you.
 
-Think **screen-share where they can type too**.
-
-<!-- demo gif goes here once captured: docs/demo.gif (host shares a session; a guest joins from a browser and types into the same Claude) -->
-
-```mermaid
-flowchart LR
-    H["you (host)<br/>terminal runs Claude"] <--> R["relay<br/>forwards bytes, nothing to disk"]
-    R <--> HT["your host tab<br/>(admit · roles · pause · end)"]
-    R <--> G["friends' browsers"]
+```
+   You                 a helper server            Your friends
+(you run Claude)  <-->  (passes messages)   <-->  (open a link)
 ```
 
-Your terminal stays plain Claude plus one status line. Everything multiplayer happens in the browser.
+Your terminal looks like normal Claude, just one extra line at the bottom. All the sharing happens in the web browser.
 
-## Host a session
+## Start a session
 
 ```bash
 npm install -g @claudecollab/cli
 collab
 ```
 
-That's it. `collab` wraps your normal `claude` and prints your room link on the status line — that's **your** tab (admit people, manage roles). The invite link lands on your clipboard — that's the one you share. Friends need nothing but a browser.
+That's it. Run `collab` instead of `claude`. It works the same, but now it makes two links:
+
+- A **private link** — that's your control panel (you let people in and manage them).
+- A **share link** — this one gets copied for you. Send it to your friends.
+
+Your friends just open the share link in a browser. They don't install anything.
 
 ## Two links — don't mix them up
 
 | Link | Who it's for |
 |---|---|
-| `…/room?host=abc` | **you only** — opening it grants the host seat |
-| `…/room` | **share this** — friends land on the request-to-join flow |
+| the one ending in `?host=…` | **Just you.** Opening it makes you the boss of the room. |
+| the plain one | **Share this.** Friends use it to ask to join. |
 
-The Invite button and your clipboard always hold the safe one.
+The Invite button adds the plain one to your clipboard.
 
-Want a lock in front of the knock? Host with `collab --room-password <pw>` — guests must enter it before their request ever reaches you. Admitting stays your call either way.
+Want an extra guardrail? Start with `collab --room-password <pw>`. Then friends have to type the password before they can even ask to join. You still choose who gets admitted.
 
 ## Roles
 
-| Role | See | Type · answer asks · slash/bash | Admit · kick · pause · end |
+| Role | Can watch | Can type | Can run the room |
 |---|---|---|---|
-| 👁 viewer | ✅ | ❌ | ❌ |
-| ✎ prompter *(default)* | ✅ | ✅ | ❌ |
-| ★ host | ✅ | ✅ | ✅ |
+| 👁 viewer | yes | no | no |
+| ✎ prompter *(normal)* | yes | yes | no |
+| ★ host *(you)* | yes | yes | yes |
+
+"Run the room" means let people in, remove them, pause, or end it.
 
-## How it feels
+## How it works
 
-- The whole page is the terminal. Type with no draft open → keys go **straight into Claude** — menus, asks, everything.
-- **+ draft** (or double-click) opens a floating glass box. Everyone's caret shows; Enter sends; Esc steps out; drag ⠿ to move, ◢ to resize, ✕ to delete.
-- Sent while Claude is busy? It waits in the **queue** chip — edit or delete before it fires.
-- Scroll the mirror like a real terminal. Scrolling is shared — one screen for everyone.
-- Reloaded guests glide straight back in. Kicked guests lose the room; a room password (below) is the real lock if you need one.
+- Everyone who can type gets their own little box at the bottom to write in. Type there and press Enter to send. Your box stays open, so you can keep going. If Claude is busy, your message will get queued.
+- Want to write a message *together* with someone? Click **+ draft** to open a shared box you both type in.
+- To talk to Claude directly (to approve y/n questions, answer questions, etc) click Claude's CLI text line.
+- Everyone sees the same screen, and scrolling is shared.
 
-## The one thing to really understand
+## Important note
 
-A guest prompt **runs on your machine, as you**. Admitting someone = trusting them with your Claude under the current mode. The relay sees your screen — treat a room like a screen-share, not a vault. You have **Pause** and **End** (with an optional `session.md` receipt).
+When a friend types something, **it runs on your computer, as if you typed it.** So only let in people you trust. You can hit **Pause** anytime, or **End** to close the room.
 
-## Self-host the relay
+## Run your own server (optional)
 
-`collab` defaults to the community relay at claudecollab.org. Rather run your own? The same package ships the server:
+By default, `collab` uses our free server at claudecollab.org. Want to run your own instead? The same install includes it:
 
 ```bash
-collab-relay                              # local: ssh :2222 · web :8787
-collab --relay ssh://127.0.0.1:2222       # host through it
+collab-relay                              # start your own server
+collab --relay ssh://127.0.0.1:2222       # use it
 ```
 
-For a permanent public relay (Fly.io, any VPS — see `fly.toml` in this repo):
+To put your server online for good (on Fly.io or any host — see `fly.toml`):
 
 ```bash
 fly launch --no-deploy
 fly secrets set HOST_KEY="$(collab-relay --make-key)"
-fly secrets set ROOM_SECRET="$(openssl rand -hex 16)"   # optional: gate room creation
+fly secrets set ROOM_SECRET="$(openssl rand -hex 16)"   # optional lock (see below)
 fly deploy
 ```
 
-Two protections are built in:
+Two safety features come built in:
 
-- **Room secret** — with `ROOM_SECRET` set, only hosts that present it (`CLAUDE_SHARE_SECRET` env or `--secret`) can create rooms. Guests are unaffected — they enter with a room link.
-- **Identity pinning** — the CLI pins the relay's ssh key fingerprint on first connect (like ssh's `known_hosts`) and refuses to connect if it ever changes. The relay prints its fingerprint at boot; pin explicitly with `--fingerprint SHA256:…`.
+- **Room password** (`ROOM_SECRET`) — if you set this, only people who know it can *start* rooms on your server. People *joining* a room don't need it.
+- **Server ID check** the first time you connect, the app remembers your server's ID. If it ever changes, it stops and warns you, so nobody can pretend to be your server.
 
-## Flags
+## All the options
 
-| Flag | What it does |
+| Option | What it does |
 |---|---|
-| `--relay <url>` | relay to use (`ssh://host:port`); default is the community relay |
-| `--no-relay` | solo mode — no room, no relay, just Claude with the band |
-| `--room-password <pw>` | guests must present this before they can knock |
-| `--guests <role>` | role given to newly admitted guests (default `prompter`) |
-| `--secret <s>` | room-creation credential for a `ROOM_SECRET`-gated relay (or `CLAUDE_SHARE_SECRET` env) |
-| `--fingerprint <fp>` | pin the relay's ssh key explicitly (default: trust-on-first-use) |
-| `--cmd <program>` | wrap something other than `claude` |
-| `-- <args…>` | everything after `--` passes through to the wrapped program |
-
-## Develop
-
-```bash
-npm install
-npm test           # full suite: protocol, relay, brain, e2e
-scripts/rig.sh     # local relay + host wrapping a fake claude (UI work)
-```
+| `--relay <url>` | which server to use; defaults to ours |
+| `--no-relay` | go solo — just Claude, no room, no sharing |
+| `--room-password <pw>` | friends must type this before they can ask to join |
+| `--guests <role>` | what new people can do when let in (default: prompter) |
+| `--secret <s>` | the password for a locked server (or use `CLAUDE_SHARE_SECRET`) |
+| `--fingerprint <fp>` | lock onto a specific server's ID |
+| `--cmd <program>` | run something other than `claude` |
+| `-- <args…>` | anything after `--` is passed to the program you're running |
 
 <details>
-<summary>Architecture</summary>
+<summary>How it's built</summary>
 
-Three packages, plain ESM JavaScript, Node 22, no build step.
+Three parts, plain JavaScript, no build step:
 
 ```
-packages/shared/   protocol.js — host↔relay wire messages
-packages/relay/    server.js (ssh door) · web.js (browser door) · public/ (client)
-packages/cli/      bin/claude-share.js — the "brain": drafts, queue, roles, gate
-test/              end-to-end: host + host tab + guest on localhost
+packages/shared/   the messages the app and server send each other
+packages/relay/    the server (one door for terminals, one for browsers)
+packages/cli/      the main program you run — the brain
 ```
 
-- The CLI wraps Claude in a PTY one row short — the bottom row is the status line.
-- State (busy/idle/ask) comes from injected Claude Code hooks, never screen-scraping. Ambiguity fails closed.
-- The relay persists nothing to disk — rooms, names, and any room password live only in process memory (kill it and the host reconnects; kill the host and the room is over). It does relay your screen bytes in transit, so treat it like a screen-share, not a vault — or self-host your own.
-
 </details>
 
 ## License
 
-[MIT](LICENSE). claudecollab is an independent open-source project — not affiliated with or endorsed by Anthropic. *Claude* is a trademark of Anthropic, PBC; this tool wraps the official Claude Code client you already have installed.
+[MIT](LICENSE) — free to use and change. This is an independent project, not made or approved by Anthropic.
 
-**TL;DR:** `npm i -g @claudecollab/cli` → `collab` → share the invite link. Guests need nothing. Roles keep control; prompts are real — admit people you trust.
+Contributions are welcome! Please open a PR and add @ir272 as a reviewer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudecollab/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/packages/cli/src/pty.js

@@ -10,8 +10,45 @@
 // node-pty is a native module and is imported lazily inside startPty, so this
 // file (and FrameSplitter's tests) load fine even where node-pty isn't built.
 
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
 /** Synchronized-update END marker. Claude ends every repaint frame with this. */
 export const SU_END = '\x1b[?2026l';
+
+// node-pty forks a small `spawn-helper` binary to launch the child, and that file
+// must be executable. Installers that skip package build scripts (npm's
+// allow-scripts / ignore-scripts policies, pnpm by default) ship it WITHOUT the
+// execute bit, so the very first spawn dies with "posix_spawnp failed". A
+// postinstall script can't fix this — those same policies block it — so we restore
+// the bit at RUNTIME, right before spawning. Best-effort and idempotent: if the
+// bit is already set (or we can't touch the file) we do nothing and let spawn
+// surface the real error. macOS/Linux only; Windows has no such helper.
+export function ensureSpawnHelperExecutable(requireFn) {
+  if (process.platform === 'win32') return;
+  try {
+    const req = requireFn ?? createRequire(import.meta.url);
+    const ptyDir = path.dirname(req.resolve('node-pty/package.json'));
+    const candidates = [path.join(ptyDir, 'build', 'Release', 'spawn-helper')];
+    const prebuilds = path.join(ptyDir, 'prebuilds');
+    try {
+      for (const d of fs.readdirSync(prebuilds)) candidates.push(path.join(prebuilds, d, 'spawn-helper'));
+    } catch {
+      /* no prebuilds dir on this layout */
+    }
+    for (const f of candidates) {
+      try {
+        const { mode } = fs.statSync(f);
+        if (!(mode & 0o111)) fs.chmodSync(f, mode | 0o111); // add u+g+o execute
+      } catch {
+        /* not present here, or not ours to chmod — skip */
+      }
+    }
+  } catch {
+    /* couldn't even resolve node-pty — the import below throws the real error */
+  }
+}
 /** Synchronized-update BEGIN marker (exported for reference / future use). */
 export const SU_BEGIN = '\x1b[?2026h';
 
@@ -78,6 +115,7 @@ export async function startPty({
   cwd,
   flushMs = 8,
 } = {}) {
+  ensureSpawnHelperExecutable(); // fix node-pty's spawn-helper exec bit before spawning
   const mod = await import('node-pty');
   const spawn = mod.spawn ?? mod.default?.spawn;
   if (typeof spawn !== 'function') {