Claude Code Remote

Project Overview

Claude Code Remote lets you control Claude Code from your Android phone over your Tailscale network. A lightweight Node.js daemon runs on your PC and relays a full terminal session to the mobile app via WebSocket - letting you take over existing Claude Code sessions or start new ones directly from your phone.

Why I Built It

I use Claude Code constantly for development, but I'm not always at my desk. I wanted a way to check in on long-running AI coding sessions, review progress, or nudge the agent from my phone - without exposing my machine to the public internet. Tailscale made the network security trivial, so I focused on building a clean terminal relay and a native Android app with a proper xterm.js terminal.

Architecture

The system has two components that communicate over WebSocket, encrypted end-to-end by Tailscale's WireGuard tunnel:

• PC Daemon (Node.js + node-pty): A small Node.js server that spawns a real PTY (pseudo-terminal) and streams it over WebSocket. On first run it generates a 32-byte auth token and prints a QR code. It binds only to localhost and your Tailscale IP - never to the public internet.
• Android App (Expo + React Native): A native Android app with a full xterm.js terminal. Scan the QR code from the daemon to connect. Supports taking over existing Claude Code sessions or launching new ones.
• Transport Security (Tailscale): All traffic between phone and PC flows through Tailscale's WireGuard encryption. No TLS is implemented directly - the project is designed to run exclusively behind Tailscale.
• Authentication: Every WebSocket and API request must carry the daemon's auto-generated Bearer token. Localhost requests skip auth since they are already on the machine.

Key Features

• Full terminal in your pocket - real xterm.js PTY session on your Android phone
• Take over or start Claude Code sessions remotely
• Zero-config security - QR code pairing + Tailscale WireGuard encryption
• One-command start: npx @dinko_abdic/claude-code-remote
• PM2 support for running the daemon as a persistent background service
• Configurable shell, port, working directory, and session keep-alive timeout
• Cross-platform daemon - runs on Windows and Linux
• Open source - MIT licensed

Quick Start

Getting started takes under a minute. Run the daemon on your PC with a single npx command, scan the QR code with the Android app, and you're in:

• 1. Start the daemon: npx @dinko_abdic/claude-code-remote — generates an auth token and prints a QR code on first run.
• 2. Install the Android APK from the GitHub Releases page (debug build, enable developer settings if needed).
• 3. Scan the QR code in the app to connect. You now have a full terminal to your PC's Claude Code session.

Known Limitations

• Android only - no iOS app yet
• Requires Tailscale - not designed for use on untrusted networks without it
• Single user - built for personal use, not multi-tenant
• Windows NDK quirk - non-ASCII characters in the project path can break the Android build (use the clean-path workaround in the README)