coderoulette-host

CLI host agent for CodeRoulette — spawns Claude Code locally and streams your terminal session to a partner.

What is this?

When you host a CodeRoulette session, this agent runs on your machine. It:

1. Spawns Claude Code in an isolated temp directory
2. Streams terminal output to the CodeRoulette relay server over WebSocket
3. Receives prompts and input from your pair partner
4. Auto-reconnects on connection drops

Your partner sees your terminal in real-time through their browser — no setup needed on their end.

Install & run

npx coderoulette-host --server wss://coderoulette.ee/ws --token <your-token>

Get your token from coderoulette.ee/host after signing in.

Prerequisites

• Node.js >= 18
• Claude Code installed (npm install -g @anthropic-ai/claude-code)

Options

-s, --server <url>    Relay server WebSocket URL (default: ws://localhost:3001)
-w, --workdir <path>  Working directory for Claude Code (default: fresh temp dir)
-t, --token <token>   Auth token from CodeRoulette web app

The token can also be set via the CODEROULETTE_TOKEN environment variable.

Security

• Outbound WebSocket only — no ports exposed on your machine
• Isolated working directory — Claude Code runs in a temp directory, never your home directory
• Claude Code permissions — every command still needs your explicit approval in the terminal
• Open-source and auditable — this is a thin PTY wrapper, not a general-purpose tool

Architecture

+-------------------+         +------------------+         +----------------+
|   Your Machine    |         |  Relay Server    |         |  Partner's     |
|                   |   WS    |                  |   WS    |  Browser       |
|  Claude Code      |-------->|  coderoulette/   |<--------|                |
|  (in PTY)         |         |  coderoulette    |         |  xterm.js      |
|       ^           |         |                  |         |  terminal view |
|       |           |         +------------------+         +----------------+
|  coderoulette-host|
+-------------------+

Development

git clone https://github.com/coderoulette/host.git
cd host
npm install
npm run dev    # Watch mode with auto-reload
npm run build  # Build dist/cli.js

The build uses esbuild to bundle everything into a single file. node-pty stays external (native module). Shared types from the main repo are inlined at build time from packages/shared/.

Related

• coderoulette/coderoulette — Main server and web app
• coderoulette.ee — Live site

License

MIT