Drive pm7Code without the GUI

The remote motor is a long-lived process that owns sessions. It is deliberately decoupled from any single connection, so a dropped socket never cancels a running turn — you can disconnect and reconnect without losing work. You reach it either through the CLI or straight over its WebSocket API.

When one-shot prompts are not enough — you want to keep a session open, read the live event stream, answer approvals, or reconnect and replay — connect to the motor directly. It speaks JSON text frames over a single WebSocket. Every message is a small tagged object; the tag field t tells you what it is.

// 1. Open a WebSocket to ws://127.0.0.1:8787, then send the hello FIRST.
//    Loopback may send device: null; a remote motor requires a paired device.
{ "t": "hello", "protocolVersion": 2, "capabilities": [], "appVersion": "2.x",
  "device": null }
// non-loopback: "device": { "id": "<device-id>", "key": "<device-key>" }
// server -> { "t": "helloAck", "protocolVersion": 2, "capabilities": [...] }

// 2. Start a session. persist:true mints a durable, resumable pm7SessionId.
{ "t": "req", "id": "1", "op": "init",
  "params": { "cwd": "/path/to/repo", "agent": "claude-sdk", "persist": true } }
// server -> { "t": "res", "id": "1", "ok": true,
//             "result": { "sessionId": "...", "pm7SessionId": "..." } }

// 3. Run one turn. Events stream while it runs; the res arrives at turn end.
{ "t": "req", "id": "2", "op": "chat",
  "params": { "sessionId": "...", "text": "your prompt" } }
// server -> { "t": "evt", "sessionId": "...", "seq": 7, "evt": "status", "data": {...} }
// server -> { "t": "res", "id": "2", "ok": true,
//             "result": { "finalText": "...", "messageCount": 12, "interrupted": false } }

// 4. Close the session when the turn is done.
{ "t": "req", "id": "3", "op": "close", "params": { "sessionId": "..." } }

Because the motor is long-lived and can outlive an app update, every connection starts with a version handshake so a new client never talks silently to an old motor. The hello must be the first frame you send. The motor answers with a helloAck; on any mismatch it sends a fatalError and closes the socket — fail-fast, with a machine-readable code.

After the handshake, you drive a session with a handful of ops. Each is a req frame with an op name and params; the motor answers on the same id.

While a turn runs, the motor pushes evt frames so you can render progress live. Each frame has the session id, a monotonic seq, an evt kind, and a data payload.

A session is owned by the motor, not by your connection. Pass persist: true on init and the motor mints a durable pm7SessionId that survives a restart. Later you can resume it — by id, or by asking for the latest session in a working directory.

For local use you rarely start the motor by hand — the CLI does it for you. You run it explicitly when you want a remote motor on another machine, reachable over your tailnet.

# Loopback only — local clients connect auth-free
node remote/server.cjs

# Reachable over your tailnet — remote clients must present a paired device key
M2_HOST=0.0.0.0 node remote/server.cjs