Two humans + one AI agent. 30 minutes. Build something fun.

CodeRoulette pairs you with a random developer for a timeboxed, AI-assisted pair programming session powered by Claude Code. One person hosts, the other joins through the browser — both see the same terminal, collaborate on prompts, and build something together in 30 minutes.

Think Omegle meets hackathons, but for coding with AI.

Website · Vision · Host Agent · Contributing · Security

1. Match — Sign in with GitHub, hit "Find a partner," get randomly paired
2. Plan — Vote on a fun project idea (or bring your own)
3. Build — Take turns driving Claude Code in a shared terminal session

Host Machine              Relay Server              Both Browsers
+--------------+         +--------------+         +--------------+
| Claude Code  |         | WebSocket Hub|         | xterm.js     |
|   (in PTY)   |         | - Matchmaking|         | terminal view|
|      |       |   WS    | - Prompt mgmt|   WS    |              |
| Host Agent   |-------->| - Byte relay |<--------|  Next.js App |
| (node-pty)   |         | - Chat/Timer |         |              |
+--------------+         +--------------+         +--------------+

The host runs a lightweight CLI agent that spawns Claude Code locally. Terminal output streams through a WebSocket relay server to both browsers. The navigator joins with zero setup — just a browser.

• Random matchmaking — FIFO queue with latency-based host selection
• Driver/Navigator model — take turns driving Claude Code, request role swaps anytime
• Shared terminal — real-time xterm.js rendering of the host's Claude Code session
• Chat sidebar — coordinate what to build, suggest prompts, share ideas
• Project suggestions — vote on fun 30-minute project ideas to beat the blank canvas
• 30-minute timer — 15-min check-in, 5-min warning, optional +15min extension
• No-fault re-match — not vibing? Try a different match in the first 3 minutes
• Direct invite links — pair with a friend instead of a stranger
• Prompt safety checks — warnings when prompts reference sensitive paths

• Node.js >= 18
• Claude Code installed (for hosting)
• GitHub account (for authentication)

git clone https://github.com/coderoulette/coderoulette.git
cd coderoulette
npm install

cp .env.example apps/web/.env.local
cp .env.example apps/server/.env

Edit both files with your GitHub OAuth credentials (create an app at github.com/settings/developers) and generate secrets:

# Generate random secrets
openssl rand -base64 32  # Use for NEXTAUTH_SECRET and JWT_SECRET

npm run dev       # Starts server (port 3001) + web app (port 3000)

To also run the host agent for a full demo:

npm run demo      # Starts server + web + host agent

Open http://localhost:3000 in two browser windows to test.

This is the main monorepo containing the server, web app, and shared types. The host agent lives in a separate repo.

coderoulette/
├── apps/
│   ├── server/          # Express + WebSocket relay server
│   │   └── src/
│   │       ├── ws/          # WebSocket handlers, rooms, agent pool
│   │       ├── matchmaking/ # Queue and matching logic
│   │       ├── session/     # Session lifecycle and timers
│   │       └── chat/        # Chat message broadcasting
│   └── web/             # Next.js 15 frontend
│       ├── app/             # Pages (home, queue, session, invite, host)
│       ├── components/      # Terminal, ChatSidebar, PromptInput, etc.
│       ├── hooks/           # useWebSocket, useTimer
│       └── lib/             # Auth config, WS URL builder
├── packages/
│   └── shared/          # Types, constants, project ideas, safety checks
└── .env.example         # Environment variables template

The host agent is a separate CLI tool that spawns Claude Code locally and relays terminal I/O. It lives in its own repo: coderoulette/host.

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

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

See .env.example for all required variables:

See CONTRIBUTING.md for guidelines. PRs welcome!

See SECURITY.md for reporting vulnerabilities.

MIT