riffpad git:20260814.5cad4beC

Immutable. This exact content never changes and is served at /api/v1/blob/618f68f474bc9ece.

---
name: riffpad
description: Control AI coding agents (Claude Code, Codex, Kimi) from your phone via Riffpad. Use when the user wants to watch, approve, or steer a coding agent remotely / set up Riffpad / pair their phone / keep a long-running agent session going while away from the computer.
---

# riffpad

Watch, approve, and steer AI coding agents (Claude Code, Codex, Kimi) from your phone. A local daemon bridges the CLI agents running on the user's own machine to their phone, end-to-end encrypted through a zero-knowledge relay. **Not a cloud IDE** — agents keep running on the user's machine with their own API keys and repos; the phone is just a mirror + remote control.

## Install

If `riffpad` is not installed:

```bash
# macOS / Linux
curl -fsSL https://riffpad.ai/install.sh | sh

# Windows (PowerShell)
irm https://riffpad.ai/install.ps1 | iex
```

Verify with `riffpad version`. If still not found after install, open a new terminal.

---

## Onboarding flow (run these in order)

1. **Install** the daemon (above), then `riffpad version` to confirm.
2. **Sign in on the computer**: `riffpad login`
   - Opens a browser for GitHub authorization (like `gh auth login`). The **user** completes it in the browser; the daemon registers this machine and restarts automatically.
   - Non-GitHub / password login: set `RIFFPAD_RELAY_USER` + `RIFFPAD_RELAY_PASSWORD`, then `riffpad login --username`.
3. **Pair the phone**: `riffpad pair`
   - Prints a 6-char code + QR. **The user** must open https://app.riffpad.ai on their phone, sign in with the same account, and enter the code (or scan the QR). You can't complete this step for them — tell them what to do.
4. **Start a session**: `riffpad run codex` (or `claude` / `kimi`)
   - The terminal stays visible and interactive. The session mirrors to the phone immediately; the user can watch progress, approve permission prompts, and send new instructions from the phone.

> To capture a Claude session the user **already started themselves** (instead of launching a new one), use `riffpad attach` (injects Claude hooks) — not `run`.

---

## CLI reference

| Command | Description |
|---|---|
| `riffpad login [--url wss://…]` | GitHub device sign-in (default); `--username` for password login |
| `riffpad logout` | Sign out and revoke the relay token |
| `riffpad auth` | Show the current account (live validation) |
| `riffpad pair` | Print a 6-char pairing code and QR |
| `riffpad run [claude\|codex\|kimi] [--name N] [--prompt P] [--cwd D]` | Create a hosted session; terminal stays visible/interactive |
| `riffpad attach` / `detach` | Inject/remove Claude hooks to capture the user's own running session |
| `riffpad sessions` | List sessions |
| `riffpad status` | Daemon status |
| `riffpad setup [--remove]` | Install/remove the Linux systemd autostart |
| `riffpad kill` | Kill switch — stop all sessions + revoke all paired devices |
| `riffpad update` | Replace with the latest version (SHA256 + atomic swap) |
| `riffpad logs` | Show daemon logs |
| `riffpad version` | Print the version |

### `run` options
- `--name N` — label the session
- `--prompt P` — start with an initial prompt
- `--cwd D` — set the working directory

### Languages
Output defaults to English. Use `--lang zh` to switch to Chinese; `--lang en` explicitly selects English.

### Environment variables
| Variable | Default | Purpose |
|---|---|---|
| `RIFFPAD_RELAY_URL` | `wss://api.riffpad.ai` | Relay address (change to self-host) |
| `RIFFPAD_RELAY_USER` / `RIFFPAD_RELAY_PASSWORD` | — | Password-login credentials |
| `RIFFPAD_URL` | `http://127.0.0.1:8787` | Local daemon address |
| `RIFFPAD_DIR` | `~/.config/riffpad` | Data directory |

---

## Self-host the relay (optional)
The relay is the only server component, and it's zero-knowledge — it forwards ciphertext and stores nothing. To point Riffpad at your own relay, set `RIFFPAD_RELAY_URL` before `login`. Relay source + self-host notes: https://github.com/riffpad/riffpad (`apps/relay`).

---

## Common pitfalls

| Pitfall | Correct approach |
|---|---|
| Treating it like a cloud IDE | Agents run on the user's machine with their own keys; the phone only mirrors + sends approvals/instructions. Don't try to move the session to the cloud. |
| Skipping pairing | `riffpad pair` must run, and the user must complete pairing on their phone at app.riffpad.ai. Without it, nothing reaches the phone. |
| Using `run` for a session the user already started | Use `riffpad attach` (injects Claude hooks into an existing session), not `run` (which starts a new one). |
| Approvals not showing on the phone | Confirm `riffpad status` is healthy and the phone is paired; check `riffpad logs`. |
| `login` can't open a browser (headless) | Use `--username` with `RIFFPAD_RELAY_USER` / `RIFFPAD_RELAY_PASSWORD`. |
| Need to stop everything immediately | `riffpad kill` — stops all sessions + revokes all paired devices (kill switch). |

---

## Notes
- **Local-first**: code, repos, and API keys never leave the user's machine.
- **End-to-end encrypted** (X25519 + AES-256-GCM); the relay is zero-knowledge.
- **Read-only by default** on the phone — every approve/reject/prompt is an explicit tap.
- Docs: https://www.riffpad.ai/docs/guide/quickstart · Repo: https://github.com/riffpad/riffpad · App: https://app.riffpad.ai