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. build the binary + symlink to ~/bin
bun build --compile src/cli.ts --outfile claude-remote
ln -sf $(pwd)/claude-remote ~/bin/claude-remote

# 4. set your secret
export CLAUDE_REMOTE_SECRET=dev  # add to .bashrc/.zshrc

# 5. use it like claude
claude-remote
claude-remote -r
claude-remote --dangerously-skip-permissions

# 6. open browser/phone
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

With the binary installed and CLAUDE_REMOTE_SECRET set, just use claude-remote like claude:

claude-remote                    # interactive
claude-remote -r                 # resume
claude-remote --help             # shows help
claude-remote -p "explain this"  # print mode

All arguments pass through to claude.

configuration

Environment variables (add to .bashrc/.zshrc):

export CLAUDE_REMOTE_SECRET=dev                    # required
export CLAUDE_REMOTE_SERVER=ws://localhost:7200/ws # optional, this is the default

Or use flags to override:

claude-remote --secret other-device --server ws://remote:7200/ws

shell aliases

alias cr='claude-remote'
alias crr='claude-remote -r'
alias crd='claude-remote --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.