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.

pm7codeis a one-shot, scriptable entrypoint that ships with pm7Code. Give it a prompt and it runs a single turn, prints the agent's final answer to stdout, and exits — the same shape as claude -p, but through the pm7Code motor. Pass the prompt as an argument or pipe it on stdin.

# One-shot against the local motor (auto-started if needed)
pm7code "summarize what changed in this repo"

# Pipe the prompt via stdin, run it through Codex
echo "write a haiku about pty buffers" | pm7code --agent codex

When you point it at a loopback address and nothing is listening yet, the CLI starts a local motor for you and reuses it on the next call. Pointed at a remote address, it never spawns anything — it only connects.

# Machine-readable output for scripts/CI: NDJSON events + a final result line
pm7code --json --agent claude "list the open TODOs"

# Continue the most recent session in this folder, then resume an exact one
pm7code --continue "now add tests for it"
pm7code --resume <pm7SessionId> "follow up on that"

# Talk to a remote motor over your tailnet (paired device + opt-in full-auto)
pm7code --server ws://100.x.y.z:8787 \
        --device-id "$PM7CODE_DEVICE_ID" \
        --device-key "$PM7CODE_DEVICE_KEY" \
        --full-auto "deploy the site"

The CLI reads a few environment variables so you can keep the server URL and device credential out of every command line.

Exit codes make the CLI safe to branch on in scripts and CI.

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