riffpad
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 · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add riffpad/riffpad --skill riffpad技能说明
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:
# 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)
- Install the daemon (above), then
riffpad versionto confirm. - 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, thenriffpad login --username.
- Opens a browser for GitHub authorization (like
- 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.
- Start a session:
riffpad run codex(orclaude/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) — notrun.
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