CosmoRemote Bridge

CLI daemon that runs on your Mac and connects Claude Code / Codex to the CosmoRemote app.

Setup

npm install

Run

npm run dev                       # Development
cosmoremote start                 # Auto-detects the Appzinhos workspace root if launched inside it
cosmoremote start -w /path/to/Appzinhos  # Optional override
cosmoremote start --port 4422     # Custom port
cosmoremote start --backend wss://your-backend.com  # Enable remote relay

Local Debug Command

If you want a local command that always uses the checkout you are editing:

cd /path/to/CosmoRemote/bridge
npm install
npm run build
npm link
cosmoremote-debug                 # Auto-detects the Appzinhos workspace root if launched inside it
cosmoremote-debug --workdir /path/to/Appzinhos

cosmoremote-debug defaults to the deployed backend relay. Pass --backend only if you need to override it. Set COSMOREMOTE_WORKDIR=/path/to/Appzinhos if you want to force a specific workspace root.

Use npm run dev:debug while developing if you want to skip the global link step.

How it works

1. Open Terminal in the project folder you want to work from
2. Run cosmoremote start on your Mac, or cosmoremote-debug from a linked local checkout
3. Detects which CLIs are available (Claude Code, Codex)
4. Starts a local WebSocket server on port 4422
5. Generates a pairing QR code with the workspace embedded
6. App scans QR → connects via WebSocket
7. App sends prompts → bridge spawns CLI process → streams output back

WebSocket Protocol

All messages use JSON envelope:

{ "type": "prompt|output|error|done|kill", "sessionId": "...", "content": "..." }

Inbound (from app)

• prompt — send a prompt to the CLI (includes cli, workingDir)
• kill — kill a running session

Outbound (to app)

• paired — pairing confirmed, includes sessionToken
• output — streaming output chunk
• error — error message
• done — session complete, includes full output