# claude-remote

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

## quick start

```bash
# 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

```bash
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

```bash
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:

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

Examples:

```bash
# 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:

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

Create equivalent remote aliases:

```bash
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

```bash
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.