Remote Pi
TutorialsDocsGitHub Install
Extra · terminal only — no app yet
Tutorial · Extra

Claude in the mesh

remote-pi claude puts Claude Code on the same agent mesh as Pi — a named peer on the local UDS broker and, through the relay, across PCs. This is an advanced, agent-to-agent setup driven entirely from the terminal. It is not surfaced in the mobile app yet — see why at the end.

Before you start

  • The remote-pi CLI on your $PATH — run /remote-pi install once (see the daemon tutorial) to link it.
  • Claude Code installed and on your $PATH as claude.
  • A folder that isn't already running a Pi agent (see one agent per folder).

Run it

Shell — bash
remote-pi claude            # uses the current folder
remote-pi claude ~/code/api  # or target a specific folder

On the first run in a folder, it asks for an agent name (defaulting to the folder name) and saves a small config:

First run — text
[remote-pi] No config found for /Users/you/code/api
Let's set up this agent.

Agent name [api]: reviewer

That name is how other agents address this Claude in list_peers and agent_send. Then it wires three things into Claude Code and launches it.

What it wires in

remote-pi claude is a wrapper. It injects three things, then spawns claude in the target folder.

1. An MCP server (the mesh tools)

It registers a stdio MCP server named remote-pi-mesh in Claude's local scope — per-folder, stored in ~/.claude.json, not written into the project directory and not committed to version control:

What the wrapper runs (you don't type this) — bash
claude mcp add remote-pi-mesh -s local -- node …/mesh_server.js --cwd <folder>

The server exposes three tools to Claude — the same mesh API Pi agents get:

  • list_peers — who is online: local peers plus cross-PC ones in pc_label:peer form (e.g. MacMini:backend).
  • agent_send({ to, body, re? }) — send a message and get an ACK back (received, busy, denied, or timeout). It is not fire-and-forget; set reto the id of the message you're replying to.
  • get_messages— drain this agent's inbox of pending messages.

2. The agent-network skill

An MCP server gives Claude the tools but not the habits. Skills load only from disk, so the wrapper deploys one to ~/.claude/skills/agent-network/SKILL.md. The skill's description self-gates to mesh contexts, so it doesn't intrude on unrelated Claude sessions. It teaches Claude to:

  • call get_messages at the start of every turn, so incoming messages are seen promptly;
  • read the agent_send ACK and act on it (retry on busy, give up on denied) rather than assuming delivery;
  • reply by echoing the original message id in re, so threads stay linked;
  • treat broadcast as fire-and-forget — no per-recipient ACK.

3. Channel push (wake on message)

When a message lands, the MCP server emits a notifications/claude/channel. Whether that reaches Claude immediately depends on one launch flag:

  • Push — with --dangerously-load-development-channels server:remote-pi-mesh on (the wrapper sets it), the notification wakes Claude right away, so it reacts to an incoming message without you prompting it.
  • Poll — without that flag, Claude only sees the message the next time it calls get_messages (i.e. on its next turn).

The --dangerously-* flags

The wrapper launches Claude with two flags:

Launch (the wrapper runs this) — bash
claude --dangerously-load-development-channels server:remote-pi-mesh --dangerously-skip-permissions
Know what these flags do
--dangerously-skip-permissions auto-approves every tool call — Claude runs Bash, edits, and writes without prompting you, which is what makes unattended agent-to-agent work possible but also removes your approval gate. --dangerously-load-development-channels opens a development channel for the local MCP server (it shows a one-time confirmation dialog at startup). Only point this at folders and peers you trust — same posture as promoting a folder to a daemon.

One agent per folder

A kernel-enforced lock (the same one /remote-pi takes) allows one remote-pi agent per folder — Pi or Claude, never both in the same directory. If a folder already has a Pi agent, start Claude in a different folder; both still meet in the same local mesh. A second agent in a locked folder is refused before it connects, so it never becomes a ghost peer.

Why this isn't in the app yet

The mobile app talks to the relay, and it sees only the Pi agent that paired it. It does not see local UDS peers — like a Claude joined with remote-pi claude— so a mesh-mate Claude won't show up in your phone. Surfacing the full mesh in the app is future work; for now this is a terminal-driven, agent-to-agent feature. Relay traffic, where it's used, is encrypted in transit.

To watch two agents talk on one machine, pair this with the local mesh tutorial — start one peer as Pi and another as Claude, in two folders, and have them message each other.