---

⚡ Quick Start

Assumes you already have Claude Code installed.

# Start a duet session (run from your terminal, NOT inside Claude Code)
npx claude-duet host --name Alice
Your partner joins (copy the command from your terminal)
npx claude-duet join <offer-code> --password abc123

Send the join command to your partner via Slack, Discord, whatever works.

P2P mode (default): After your partner runs the join command, they'll get an answer code to share back with you. Paste it into your terminal — that's it, you're connected directly peer-to-peer via WebRTC. No server needed.

Step by Step

1. Exit Claude Code if you're in an active session (Ctrl+C or /exit)
2. Start a duet session from your regular terminal:
   • npx claude-duet host — fresh session
   • npx claude-duet host --continue — resume your most recent Claude Code conversation
3. Share the join command that appears in your terminal with your partner
4. Your partner runs the join command from their own terminal
5. Chat freely — plain text goes between you two, @claude <prompt> sends to Claude

Context is preserved. Because claude-duet wraps Claude Code in headless mode, your Claude Code conversation history carries over. Use --continue to pick up where you left off, and after the duet session ends, run claude --continue to keep going solo. Claude remembers everything — before, during, and after the duet.

Heads up: claude-duet gives your partner the ability to run prompts on your machine through Claude Code. Approval mode is on by default so you review every prompt — but only share sessions with people you trust. Think of it like handing someone a terminal.

✦ What Is This

A shared terminal session where two people can chat with each other and invoke Claude together using @claude <prompt>.

Just type normally to talk to your partner. Prefix with @claude to send a prompt to Claude. Both of you see everything in real time.

⟩ hey, do you see the bug in auth.ts?          ← chat (just between you two)
⟩ @claude look at src/auth.ts and fix the bug  ← sent to Claude (both see the response)

That's the whole idea. You decide when to bring Claude in.

When to use it

• Brainstorm mid-session. Deep in a Claude Code session and want a second brain? Invite your colleague to jump in for 5 minutes, riff on the approach together, then they leave and you keep going.
• Demo Claude to your boss. Instead of an hour-long screen share explaining what AI coding looks like — just send them a join command and let them see it live.
• Pair program across offices. You're in Tel Aviv, your partner is in New York. One Claude, both driving.
• Code review with context. Walk through a PR together with Claude explaining the changes in real time.
• Onboard a teammate. Let them watch (and participate) as Claude sets up a new service, so they learn the codebase while it's being built.

☯︎ How It Works

┌──────────────────┐  WebRTC P2P (default)  ┌──────────────────┐
│   You (host)     │◄══════════════════════►│   Partner        │
│   Claude Code    │    E2E encrypted       │   Terminal       │
│   (headless)     │    NAT hole-punching   │   Client         │
└──────────────────┘                        └──────────────────┘

• Host runs Claude Code on their machine in headless mode
• Partner connects directly via WebRTC data channel (no server in between)
• Chat goes between you two — Claude doesn't see it
• @claude <prompt> sends to Claude — both of you see the response streaming
• Approval mode (on by default) — host reviews partner's Claude prompts before they run

Type @ and ghost text will suggest the completion. Press Tab to accept. Same for commands: /h → /help, /s → /status, etc. A typing indicator appears inline on the prompt line when your partner is typing.

⌘ Commands

CLI

npx claude-duet                          # Interactive wizard
npx claude-duet host                     # Start a session (P2P default)
npx claude-duet host --continue          # Resume your most recent Claude Code session
npx claude-duet host --resume <id>       # Resume a specific session
npx claude-duet host --no-approval       # Trust mode — skip prompt review
npx claude-duet host --tunnel cloudflare # Remote access via Cloudflare tunnel
npx claude-duet join <offer-code> --password <pw>           # P2P join
npx claude-duet join <session-code> --password <pw> --url <url>  # WebSocket join

In-Session

What you type	What happens
hello!	Chat with your partner — Claude doesn't see this
@claude fix the bug	Sent to Claude — both of you see the response
/help	Show commands
/status	Who's connected, session duration
/clear	Clear the terminal
/leave	Leave the session
/trust	(host) Let partner's prompts skip approval
/approval	(host) Re-enable approval
/kick	(host) Disconnect the partner

⚙︎ Configuration

claude-duet config set name "Eliran"              # your name
claude-duet config set approvalMode false          # skip prompt review
claude-duet config set permissionMode interactive  # approve each tool use
claude-duet config                                 # see current config

Project-level config (.claude-duet.json) overrides user config. CLI flags override everything.

☷ Connection Modes

Mode	Command	When
P2P (default)	npx claude-duet host	Any network — direct WebRTC connection
LAN	npx claude-duet host --tunnel localtunnel	Same Wi-Fi / VPN (fallback)
SSH Tunnel	ssh -L 3000:localhost:3000 host	Remote, secure
Cloudflare	npx claude-duet host --tunnel cloudflare	Remote, no server needed

⊘ Security

• E2E Encrypted — NaCl secretbox + scrypt key derivation
• Approval Mode — host reviews partner's Claude prompts (on by default)
• P2P Direct — WebRTC data channel by default, no server or relay in the data path
• Host Controls Everything — Claude runs on your machine, your API key

⌥ Development

git clone https://github.com/elirang/claude-duet.git
cd claude-duet
npm install
npm run build
npm test                # 150 tests across 20 files

Requires Node.js 18+ and Claude Code CLI.

❓ FAQ

See the FAQ for common questions about security, remote access, permissions, and more.

License

MIT

---