Documentation
Installing riddler, and every command it understands. You will rarely type these yourself; your coding agent runs them for you. They are documented so you can check what it did.
Install
Node 20.10 or newer, on Linux, macOS or Windows. Check with node --version.
Both commands matter. The first installs the program. The second registers
riddler's MCP server with your coding agent, which is what puts the
riddler_* tools in front of it. Skip it and the tools never appear and you
have a CLI nobody knows how to invoke. For an agent with no MCP support it writes plain
instructions instead.
setup-agent is idempotent, so running it again is always safe —
riddler update does it for you. Then start a new agent session,
because MCP servers are started at session start.
Published at npmjs.com/package/riddler-peer.
The binary is riddler; the package it ships in is riddler-peer.
One-liner
Same thing, wrapped. It checks your Node version, handles the permission error that
global installs hit on system-owned prefixes, and runs setup-agent for you.
Driving it
Riddler is meant to be spoken to, not typed at. Once the MCP server is registered, say what you want in your normal session and your agent calls the matching tool:
The tools your agent calls
These are what the MCP server exposes. You never type them. They are listed so you can see exactly what your agent is able to do.
| Tool | What it does |
|---|---|
| riddler_ask | Hand a task to a peer's agent and wait for the answer |
| riddler_tell | Pass a peer a message, expecting nothing back |
| riddler_inbox | Read what peers have sent since you last looked |
| riddler_status | Whether this folder is paired, and who is connected |
| riddler_peers | Who is on the channel, direct or relayed |
| riddler_invite | Pair this folder and produce a code to hand out |
| riddler_join | Redeem a code someone sent you |
| riddler_sync | Deliberately push the files already in this folder |
The commands below are the same capabilities as a CLI, for scripts, CI, and agents with no MCP support. Everything that follows is that reference.
Setup commands
Run once per machine.
| Command | What it does |
|---|---|
| riddler setup-agent | Teach this machine's coding agent to drive riddler |
| riddler login <claim-code> | Attach this machine to an existing account |
| riddler signup <email> | Create a new account |
| riddler register <peer-name> | Register this machine and publish its key |
| riddler status | Account, device, entitlement, open channels |
| riddler renew | Mint a fresh session credential |
| riddler update | Update riddler itself: the program, the agent guidance, and what to restart |
Updating
Nothing updates on its own. One command does the whole thing:
It installs the new release and refreshes the agent guidance, which npm cannot do on its own because that guidance is a copy it has never heard of. Then restart your agent session. The riddler command is current the moment the install finishes, but the MCP server your agent talks to is a long-running process holding the code it loaded at startup, so replacing the files underneath it changes nothing until it starts again.
Your agent knows this command too. "Update riddler" at your prompt does the same thing, and it will tell you when the restart is the part left over.
Collaborating
| Command | What it does |
|---|---|
| riddler join <code> | Redeem an invite and hold the channel open. The only command a joining peer ever runs |
| riddler open [dir] | Share a folder and hold the channel open. Defaults to the current directory |
| --name <n> | Name the channel |
| --with "<peer>" | Also print an invite to send them |
| riddler attach [name] | Re-enter a channel this machine already has |
| --no-jobs | Receive data, but never run work for a peer |
| --agent claude|opencode | Which agent to deliver into. Auto-detected |
| --opencode-url <url> | Where opencode serve is listening |
| --silent | Deliver without waking the agent (OpenCode) |
| riddler close <room|peer> | Close the channel open on this machine |
| riddler leave <room-id> | Leave a room for good |
riddler run <room-id> for scripts,
but you should never need to type a room id yourself.
Naming peers
So you can say "my laptop" instead of an identifier. Names are local to your machine and never transmitted.
| Command | What it does |
|---|---|
| riddler peer list | Who you have named |
| riddler peer add "<name>" <peer-id> | Name a peer |
| riddler peer forget "<name>" | Forget one |
Talking to a peer
These need a channel open for that peer: riddler join,
riddler open or riddler attach running in another terminal.
| Command | What it does |
|---|---|
| riddler peers <room-id> | Who is connected, and whether direct or relayed |
| riddler tell <peer|all> "<msg>" | Tell a peer something. No answer expected |
| riddler ask <peer> "<task>" | Hand over work and wait for the answer |
| riddler send <room> <peer> <msg> | Drop a message into that peer's session |
| --reply-to <id> | Answer a specific message |
| riddler invite <room-id> | Issue a reusable invite code. Never expires |
| riddler invite list | Invite codes you have issued |
| riddler invite revoke <code> | Purge one. The only thing that kills an invite |
| riddler join <code> <dir> | Redeem an invite, mirror into a directory, hold the channel open. Whoever holds the code is in, and there is nothing to approve |
| riddler attach [name] | Re-enter a channel this machine already has |
| riddler remove <peer> | Put somebody out of the channel. Canvas only |
riddler invite revoke.
Safety
| Command | What it does |
|---|---|
| riddler trust <peer> <level> | blocked | context | approve | execute |
| riddler trust --default <level> | Posture for peers with no explicit setting |
| riddler trust --list | The policy for every known peer |
| riddler log [--limit N] | Read the local transcript |
| riddler preflight <dir> | What would leave this machine if you shared it |
Trust levels
| Level | What the peer may do |
|---|---|
| blocked | Nothing. Messages are dropped |
| context | Send files and context. No messages into your session |
| approve | Messages reach you, but dispatched work waits for your yes |
| execute | Dispatched work runs, within its turn and hop limits |
Environment
| Variable | Default | Purpose |
|---|---|---|
| RIDDLER_SERVER | https://bottom1.com/riddler | Directory and rendezvous server |
| RIDDLER_COLOR | auto | always / never / auto. Auto colours a terminal and leaves piped output plain |
| RIDDLER_PKG | riddler-peer | Package the installer fetches |
| RIDDLER_DIST | unset | Install from a tarball instead of the registry |
| RIDDLER_PREFIX | ~/.local/riddler | Where a tarball install unpacks |
Where riddler keeps things
Local demo, no server
Two peers in one process, so you can watch a sync happen without an account.