diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c9f0262
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+# 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.