CCM Remote

Control Claude Code on your PC from your phone, over the internet. Step away from your desk without losing the ability to continue AI-powered coding tasks.

Access via mobile browser (with PWA install support), while the PC side runs as a single command window. No Docker, no public IP required.

Features

• Remote Chat — Start new conversations, send messages, and read Claude's replies on your phone. Full Markdown rendering with syntax-highlighted code blocks.
• Resume Tasks — Pick up any existing Claude Code session from your PC. Continue exactly where you left off.
• History Viewer — Import past conversations and browse complete message history, including all user prompts and assistant responses.
• Multi-Conversation — Switch between multiple conversations in the sidebar. Search and delete as needed.
• Internet Access — Built-in Cloudflare Tunnel. Connect from anywhere — coffee shop, commute, or travel — no port forwarding needed.
• Model Agnostic — Runs your local claude CLI directly. Whatever model or API provider you've configured just works.
• Authentication — JWT-protected login. Random initial password generated on first launch.

Architecture

Phone Browser (Chat UI / PWA)
    │ HTTPS
    ▼
Cloudflare Tunnel (cloudflared)
    │ localhost:3000
    ▼
CCM Remote (Node.js + Express + node-pty)
    │ PTY stdin / JSONL monitoring
    ▼
Claude Code CLI (installed on your machine)

• Backend: Node.js + Express 5 + node-pty (pseudo-terminal)
• Storage: SQLite via sql.js (WASM — zero native dependencies)
• Frontend: Vanilla JS + Vite + marked.js + highlight.js
• Tunneling: Cloudflare Tunnel (free, auto-assigned *.trycloudflare.com subdomain)

Prerequisites

• Windows 10/11 (other platforms may work but require adapting cloudflared and node-pty paths)
• Node.js 22+ (must be in PATH)
• Claude Code CLI (claude command must work in terminal)
• cloudflared (optional — only needed for internet access; LAN access works without it)

Installation

Download from GitHub

git clone https://github.com/your-username/ccm-remote.git
cd ccm-remote
npm install
cd frontend && npm install && npx vite build && cd ..

Create a Desktop Shortcut (Windows)

$WshShell = New-Object -ComObject WScript.Shell
$Shortcut = $WshShell.CreateShortcut("$env:USERPROFILE\Desktop\CCM Remote.lnk")
$Shortcut.TargetPath = "D:\ccm-remote\start.bat"
$Shortcut.WorkingDirectory = "D:\ccm-remote"
$Shortcut.IconLocation = "C:\Windows\System32\SHELL32.dll,13"
$Shortcut.Description = "Launch CCM Remote"
$Shortcut.Save()

Replace D:\ccm-remote with your actual installation directory.

Usage

1. Launch

Double-click the CCM Remote desktop shortcut (or double-click start.bat). A console window appears with connection info:

╔══════════════════════════════════════════╗
║         CCM Remote — Started             ║
╚══════════════════════════════════════════╝

  Local:     http://localhost:3000
  Public:    https://xxx-xxx.trycloudflare.com

  ┌─────────┐
  │ QR CODE │  ← scan with phone
  └─────────┘

  Initial password:  a3f8c2e1d9b0    ← random, generated on first launch
  (Change it immediately after first login)
  Press Ctrl+C to exit

Do not close this window. Closing it stops the server.

2. Connect from Phone

• Same Wi-Fi → Open http://<PC-IP>:3000 in phone browser
• Different network → Open https://xxx.trycloudflare.com in phone browser
• Scan the QR code displayed in the console window

3. Log In

Enter the initial password shown in the console. You'll be prompted to change it on first login — pick something memorable.

4. Start Chatting

• Click "+ New Chat" in the sidebar → wait ~10 seconds for Claude to initialize → type your message
• Claude's responses appear as chat bubbles. Code blocks get automatic syntax highlighting.

5. Import Existing Sessions

Click "Import from Claude" → choose a past session from the list → the conversation and its full context are restored.

Or type a session ID manually (UUID only — do not include the claude --resume prefix):

fe5f4bd3-e0b6-472e-bdf1-f2b2e732aa83   ← Correct
claude --resume fe5f4bd3-...           ← Rejected with a hint to remove the prefix

6. Install as Mobile App (PWA)

• iPhone Safari: Tap Share → "Add to Home Screen"
• Android Chrome: Menu → "Add to Home Screen"

The CCM Remote icon appears on your home screen. One tap to launch — feels like a native app.

7. Shut Down

Press Ctrl+C in the console window to stop the server.

Change Password

Click the 🔒 icon in the sidebar header (next to the logout button). You'll need to confirm your current password.

Configuration

Environment Variables (Optional)

Create a .env file (see .env.example for reference):

# Server port
PORT=3000

# JWT signing secret (auto-generated on first run if not set)
# JWT_SECRET=

# Initial password on first run (random if not set)
INITIAL_PASSWORD=claude

cloudflared

The project searches for cloudflared.exe in the following locations automatically:

• Current working directory
• D:\tools\cloudflared.exe
• System PATH

If not found, the console will show "Tunnel disconnected" — LAN access is unaffected.

FAQ

The shortcut flashes and closes immediately

A previous CCM Remote instance is still running. Open Task Manager → Details → find node.exe → End Task, then double-click the shortcut again.

Can't connect

1. Make sure the console window is still open on your PC.
2. For public access: verify cloudflared is installed and the trycloudflare.com URL appeared in the console.
3. For LAN access: make sure your phone and PC are on the same Wi-Fi network.

I changed my password and forgot it

Passwords are stored as bcrypt hashes and cannot be recovered. Delete data/database.sqlite and restart — a new random password will be generated.

Import says "Please remove the claude --resume prefix"

You pasted the full command. Just keep the UUID part.

Connection shows "Disconnected"

This version uses HTTP polling (every 2 seconds) rather than WebSocket. If the status indicator shows disconnected, check that your firewall isn't blocking port 3000.

License

MIT