Claude Remote

Control Claude Code from your phone. Send prompts, receive responses, and approve actions - all from your couch.

Uses your existing Claude subscription - no additional API tokens required.

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Your PC                          Your Phone               │
│   ┌─────────────┐                 ┌─────────────┐          │
│   │ Claude      │◄───WebSocket───►│ Mobile PWA  │          │
│   │ Remote CLI  │                 │             │          │
│   └──────┬──────┘                 └─────────────┘          │
│          │                                                  │
│          ▼                                                  │
│   ┌─────────────┐                                          │
│   │ Claude Code │ ◄── Your Claude subscription             │
│   └─────────────┘                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Features

• Mirror Mode: Both PC and mobile can send prompts and approve actions
• QR Code: Scan to connect your phone in 2 seconds
• Notifications: Vibration + notification when Claude requests approval
• Secure: Unique token per session, local network only
• Lightweight: ~50KB PWA, no Electron
• Conversation Continuity: Uses -c flag to maintain context between prompts

Prerequisites

• Node.js 18.19+ (check with node --version)
• Claude Code installed and connected to your account

# Check if Claude Code is installed
claude --version

# If not installed (Windows)
winget install Anthropic.ClaudeCode

# Or (Mac/Linux)
curl -fsSL https://claude.ai/install.sh | bash

Installation

# Clone the repo
git clone https://github.com/your-user/claude-remote.git
cd claude-remote

# Install and build (single command)
npm run setup

Usage

Start the application

npm start

You'll see:

╔══════════════════════════════════════════════════════════╗
║           Claude Remote CLI                              ║
║           (uses your Claude subscription)                ║
╠══════════════════════════════════════════════════════════╣
║  URL:     http://192.168.1.42:38471
║  Token:   ABC123
║  Project: my-project
╠══════════════════════════════════════════════════════════╣

   ▄▄▄▄▄▄▄  ▄    ▄ ▄▄▄▄▄▄▄
   █ ▄▄▄ █ ██▄█ █ █ ▄▄▄ █      <- QR Code
   █ ███ █ ▄▄ ▄▄▄ █ ███ █
   █▄▄▄▄▄█ ▄▀█▀▄ ▄█▄▄▄▄▄█

╠══════════════════════════════════════════════════════════╣
║  Mirror mode: PC and Mobile                              ║
║    - Send prompts                                        ║
║    - View responses                                      ║
║    - Approve/deny (y/n)                                  ║
╚══════════════════════════════════════════════════════════╝
>

From your phone

1. Scan the QR code with your camera
2. The PWA opens in your browser
3. Send a prompt to Claude!

From PC

Type your prompt directly in the terminal:

> Create a file hello.py that prints "Hello World"

Approving actions

When Claude wants to execute an action (create a file, run a command...), you receive an approval request:

On PC:

[HIGH] Bash
  Command: echo "Hello World" > hello.py
Waiting for approval (y/n)...
[y/n] Approve Bash? y
[CLI] Bash: APPROVED

On mobile: A modal appears with details and Approve/Deny buttons.

Exit

Type exit, quit, or q from PC or mobile to quit the application.

Available commands

Command	Description
npm run setup	First-time install (deps + build)
npm start	Start the application
npm run dev	Development mode (hot reload)
npm run cli	Start CLI only
npm run build:web	Rebuild PWA only

Architecture

claude-remote/
├── apps/
│   ├── web/                 # Mobile PWA (Preact + Tailwind)
│   │   ├── src/
│   │   │   ├── app.tsx              # Main router
│   │   │   ├── components/          # UI (Chat, Modal, etc.)
│   │   │   ├── hooks/               # useWebSocket
│   │   │   └── stores/              # State (Preact Signals)
│   │   └── public/                  # PWA assets
│   │
│   └── cli/                 # Node.js CLI
│       └── src/
│           └── cli.ts               # Servers + Claude bridge
│
├── package.json             # Root scripts
├── CLAUDE.md                # Technical doc for Claude
└── README.md

Tech stack

Component	Technologies
PWA	Preact, Preact Signals, Tailwind CSS, Vite, marked
CLI	Node.js, TypeScript, ws, Express, node-pty, qrcode-terminal

Configuration

Default ports

Port	Usage
38470	WebSocket (PWA communication)
38471	HTTP (serves PWA)

Change ports

Edit the constants in apps/cli/src/cli.ts:

const WS_PORT = 38470;
const HTTP_PORT = 38471;

Troubleshooting

"claude: command not found"

Claude Code is not installed or not in PATH.

# Windows
winget install Anthropic.ClaudeCode

# Mac/Linux
curl -fsSL https://claude.ai/install.sh | bash

QR code doesn't work

1. Make sure your phone is on the same WiFi network
2. Try manual connection: enter the URL and token shown in terminal

"EADDRINUSE: address already in use"

Another process is using the port.

# Find the process (Windows)
netstat -ano | findstr :38470

# Find the process (Mac/Linux)
lsof -i :38470

PWA doesn't update

Clear browser cache or open in private/incognito mode.

Contributing

Contributions are welcome!

1. Fork the project
2. Create your branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For major changes, please open an issue first to discuss what you'd like to change.

License

This project is licensed under MIT - see the LICENSE file for details.

Author

Created with Claude

---

Star this repo if you find it useful!