claude-remote

Self-hosted remote control for Claude Code. Wraps CLI in PTY, streams output to server, approve prompts from phone.

quick start

# 1. start the server
just dev

# 2. create a device (one-time setup)
just seed dev "My Phone"

# 3. run claude through the wrapper (from any project directory)
bun /path/to/claude-remote/src/cli.ts --secret dev -- --dangerously-skip-permissions

# 4. open browser
open http://localhost:7200

usage

server

just dev     # development with hot reload
just start   # production
just check   # lint + typecheck + test

Server runs on port 7200 (configure via PORT env var).

create device

just seed <secret> <name>

Creates a device with the given secret and name. The secret is used to authenticate the CLI wrapper.

Default if you just run just seed:

secret: "dev"
name: "dev device"

run claude

Instead of running claude directly, run it through the wrapper:

bun /path/to/claude-remote/src/cli.ts --secret <your-secret> -- <claude args>

Examples:

# basic
bun src/cli.ts --secret dev -- --dangerously-skip-permissions

# resume
bun src/cli.ts --secret dev -- --dangerously-skip-permissions -r

# any other claude args
bun src/cli.ts --secret dev -- --help

The wrapper can be run from any directory - it passes through to claude with your current working directory.

shell aliases

If you have aliases like:

alias cd!='claude --dangerously-skip-permissions'
alias cdr='cd! -r'

Create equivalent remote aliases:

alias crd='bun /path/to/claude-remote/src/cli.ts --secret dev -- --dangerously-skip-permissions'
alias crdr='crd -r'

view output

Open http://localhost:7200 in browser or phone to:

see live terminal output
approve/reject permission prompts
answer questions

docker

just build  # build image
just up     # compose up
just down   # compose down
just logs   # compose logs

architecture

Pure Bun stack:

bun-pty for PTY wrapper
bun:sqlite for persistence
Bun.serve() for HTTP + WebSocket + SSE
plain text output (mobile-friendly)

Target: ~1000-1500 lines total.

2.1 KiB Raw Blame History