riffpad
by silentFred
README.md
# riffpad
Point at things instead of describing them.
riffpad puts whatever your AI agent is working on (a screenshot, a mock-up, a 3D model) on your iPad. You circle the part you mean with the Apple Pencil, say or write what you want, and tap **Send**. The agent gets your marks, your words and the exact spot you pointed at, and comes back with the next version. Then you do it again.
It works with any agent that speaks MCP: Claude Code, Codex, Cursor, Claude Desktop and others.
<!-- TODO before release: add a screenshot or the trailer GIF here -->
## What you need
- A computer with [Node.js](https://nodejs.org) 20 or newer. This is where your agent runs.
- An iPad on the same Wi-Fi (or the same [Tailscale](https://tailscale.com) network). An Apple Pencil makes it better, but a finger works.
Nothing is installed on the iPad. It opens a web page that your computer serves.
## Get started
```bash
git clone https://github.com/silentFred/riffpad.git
cd riffpad
npm install
npm link # gives you the `riffpad` command
riffpad setup
```
`riffpad setup` starts riffpad and walks you through the two things left to do:
1. **Connect your agent.** It prints the one line to run for Claude Code and the snippet for Codex or any other MCP client.
2. **Open the link on your iPad.** Scan the QR code. Then use Share > **Add to Home Screen** so it opens full screen like an app.
Now ask your agent something like:
> Show me a blank canvas on riffpad and wait for my sketch.
Draw, tap Send, and the agent takes it from there.
## What you can do on the iPad
| You | On an image | On a 3D model |
|---|---|---|
| Draw with the Pencil | Marks on the image | Marks stick to the model's surface |
| Drag with one finger | Pan | Orbit |
| Pinch | Zoom | Zoom toward your fingers |
| Double-tap with a finger | | Fly in on that spot |
| Hold the Pencil still | Your rough shape snaps clean | The same, on the surface |
There is a pen, a highlighter, pins with labels, an eraser, undo and redo. 3D models also get a wireframe view and a field-of-view slider, which helps inside rooms.
You can start a round yourself too: **+ Sketch**, **+ Image** (camera or Photos) or **+ 3D**.
The **Agent** button shows what the agent asked for and what it is doing right now, so you are not left staring at a still screen.
## Voice notes
Tap the mic, talk while you draw, tap again. Your words are transcribed on your own computer and sent with your marks. The agent even gets the timing, so "make *this* bigger" lands on the stroke you were drawing when you said it.
Voice needs two extra things, both optional:
- **The Desert Ant CLI** on your computer, for the transcription. Install it from [desertant.com](https://desertant.com). `riffpad doctor` tells you whether riffpad found it.
- **HTTPS**, because Safari only opens the microphone on secure pages. riffpad makes its own local certificate. You trust it once on the iPad:
1. On the iPad, open `http://<your-computer>:7420/ca.crt` and allow the download.
2. Settings > **Profile Downloaded** > Install.
3. Settings > General > About > **Certificate Trust Settings** > turn on *riffpad local CA*.
4. Ask your agent for the HTTPS link (`riffpad_connect`) and add that one to the Home Screen.
Everything else works without these.
## Clean shapes
Hold the Pencil still at the end of a stroke and your wobbly circle becomes a clean one. The same goes for arrows, rectangles and a dozen other shapes. The agent then knows you drew "an arrow from here to there", not just some ink.
This uses [Desert Ant Labs Shapes](https://desertant.com/models/shapes/), which runs in the iPad's browser. It is free for small projects but it is not MIT licensed: see [Licence](#licence).
## Faster replies
By default your agent asks for feedback and waits. Two things make the loop quicker, and both are covered in the [reference](docs/REFERENCE.md):
- **Riff agents.** Give one item its own small, fast agent that answers each Send in seconds to a minute. Uses Claude Code.
- **Push delivery.** A Send wakes your Codex chat or Claude Code session by itself, so the agent does not have to sit and wait.
## Everyday commands
```bash
riffpad setup # start riffpad and show how to connect
riffpad url # the iPad link and QR code again
riffpad doctor # what works on this computer, and how to fix what does not
riffpad config # every setting, and how to change it
riffpad stop # stop riffpad (it starts again when your agent needs it)
```
You do not have to keep anything running. Your agent starts riffpad when it needs it.
## Settings
The defaults work for most people. If port 7420 is taken or a program lives somewhere unusual, `riffpad config` lists every setting with a one-line explanation:
```bash
riffpad config port 7500
riffpad restart
```
The full list is in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
## Is it safe?
riffpad is made for your home network or Tailscale. The link holds an access token, and anyone who has it can see and change your board, so treat it like a password and never put riffpad on the open internet. Your images, models and voice notes stay on your computer in `~/.riffpad/`.
Read [SECURITY.md](SECURITY.md) before you turn on riff agents, because they let a Send from the iPad start work on your computer.
## More
- [docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md): for agents. How to run the loop, what feedback looks like, recipes.
- [docs/REFERENCE.md](docs/REFERENCE.md): every MCP tool, the agent panel, delivery into Codex and Claude Code, 3D model updates.
- [docs/CONFIGURATION.md](docs/CONFIGURATION.md): settings and files.
- [CONTRIBUTING.md](CONTRIBUTING.md): run the tests, change the code.
## Licence
riffpad itself is [MIT](LICENSE).
Two optional parts come from [Desert Ant Labs](https://desertant.com) and have their own licence, the Desert Ant Labs Source-Available License ([license.desertant.com](https://license.desertant.com)): the Shapes model that cleans up your strokes, and the `desertant` CLI that transcribes voice notes. In short, they are free below 100,000 monthly active devices and need the credit that riffpad shows in its sidebar. Shapes makes a licence check when it loads (an install ID, the app ID and the platform, never what you draw). riffpad does not ship either of them: npm installs Shapes and builds it on your computer, and you install the CLI yourself. To leave Shapes out, remove `@desert-ant-labs/shapes` from `package.json`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues