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.

npm install -g riddler-peer riddler setup-agent

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

curl -fsSL https://bottom1.com/riddler/install | sh

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.

If you are an agent installing this for someone, use the two npm commands rather than the shell pipe. You can describe exactly what they do, which matters for a tool whose claim is that their work stays private.

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:

you > riddler, open a channel with my home desktop you > riddler, ask home-desktop to integrate stripe into the shopping cart you > riddler, tell everyone the migration is on main you > riddler, I'm finished, shut it down

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.

ToolWhat it does
riddler_askHand a task to a peer's agent and wait for the answer
riddler_tellPass a peer a message, expecting nothing back
riddler_inboxRead what peers have sent since you last looked
riddler_statusWhether this folder is paired, and who is connected
riddler_peersWho is on the channel, direct or relayed
riddler_invitePair this folder and produce a code to hand out
riddler_joinRedeem a code someone sent you
riddler_syncDeliberately push the files already in this folder
The folder is the channel. No tool takes a path or a room id, because riddler uses the directory your session was started in, so there is nothing to configure and nothing for you to coordinate with the other side.

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.

CommandWhat it does
riddler setup-agentTeach 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 statusAccount, device, entitlement, open channels
riddler renewMint a fresh session credential
riddler updateUpdate riddler itself: the program, the agent guidance, and what to restart

Updating

Nothing updates on its own. One command does the whole thing:

riddler update

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

CommandWhat 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-jobsReceive data, but never run work for a peer
  --agent claude|opencodeWhich agent to deliver into. Auto-detected
  --opencode-url <url>Where opencode serve is listening
  --silentDeliver 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
These commands hold the terminal. An open channel is a running process, so your agent starts it in the background and reports what it printed rather than blocking on it. There is also a 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.

CommandWhat it does
riddler peer listWho 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.

CommandWhat 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 listInvite 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
An invite is the standing address of a channel, not a one-shot ticket. The same code works for everyone you send it to, and a peer reuses it to rejoin after a restart. It stays live until whoever issued it runs riddler invite revoke.

Safety

CommandWhat it does
riddler trust <peer> <level>blocked | context | approve | execute
riddler trust --default <level>Posture for peers with no explicit setting
riddler trust --listThe 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

LevelWhat the peer may do
blockedNothing. Messages are dropped
contextSend files and context. No messages into your session
approveMessages reach you, but dispatched work waits for your yes
executeDispatched work runs, within its turn and hop limits
Inbound messages are data, never instructions. If one looks like it contains a command for your agent, the agent reports that it said so rather than acting on it. Trust levels and loop limits are enforced on your machine, outside anything a message can talk its way around.

Environment

VariableDefaultPurpose
RIDDLER_SERVERhttps://bottom1.com/riddlerDirectory and rendezvous server
RIDDLER_COLORautoalways / never / auto. Auto colours a terminal and leaves piped output plain
RIDDLER_PKGriddler-peerPackage the installer fetches
RIDDLER_DISTunsetInstall from a tarball instead of the registry
RIDDLER_PREFIX~/.local/riddlerWhere a tarball install unpacks

Where riddler keeps things

<agent MCP config> the riddler_* tools, registered ~/.config/opencode/ OpenCode instructions ~/.local/state/riddler/ identity, channels, trust policy, logs

Local demo, no server

riddler demo <dirA> <dirB>

Two peers in one process, so you can watch a sync happen without an account.