pi-telephone
Agent sessions call each other across machines on your Tailscale network, in Pi and Claude Code.
Package details
Install pi-telephone from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-telephone- Package
pi-telephone- Version
0.3.2- Published
- Nov 15, 2026
- Downloads
- 2,026/mo · 694/wk
- Author
- ordinath
- License
- MIT
- Types
- extension, skill
- Size
- 1.6 MB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"skills": [
"./skills"
],
"extensions": [
"./pi/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-telephone
Agent sessions call each other across machines on your Tailscale network. Works with Pi, Claude Code and pi-fleet in any combination, on one machine or across machines, including machines shared from someone else's tailnet. Other Node programs can host sessions too; see Use from another host.
A session is unreachable until you turn its telephone on. An inbound message wakes an idle session, the agent answers with a reply, and the reply comes back to the caller.
How it works
- Every machine runs one small exchange daemon, started on demand by the first session that needs it.
- Sessions talk to their local exchange over a Unix socket; exchanges talk to each other over HTTP on port 47474, bound only to the machine's Tailscale IP.
- The caller of every network request is identified by
tailscale whois, never by what the request claims. - A machine accepts calls only from its owner's Tailscale login and from logins you trust.
- Each session has an allowlist of callers; the default admits only your own sessions.
- A reply to a message your session sent is always accepted.
Requirements
- Node.js 20 or later.
- Tailscale, logged in.
- Claude Code 2.1.224 or later (2.1.248 or later when
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICis set).
Install
Pi:
pi install npm:pi-telephone
Claude Code:
claude plugin marketplace add Ordinath/pi-telephone
claude plugin install telephone@pi-telephone
The command-line tool for status and trust comes with the npm package: npx pi-telephone status.
Use
Addresses are session@machine, for example reviewer@bobs-mbp; a bare reviewer means this machine.
| Pi | Claude Code | |
|---|---|---|
| Turn on | /telephone on [name] or ctrl+alt+t |
/telephone:on [name], or start with PI_TELEPHONE_NAME=<name> claude |
| Turn off | /telephone off |
/telephone:off |
| See who is reachable | /telephone list |
/telephone:list |
| Send a message yourself | /telephone call <address> <message> |
/telephone:call <address> <message> |
| Allow a caller | /telephone allow <entry> |
/telephone:allow <entry> |
| Trust a person's machines | /telephone trust <login> |
/telephone:trust <login> |
Agents use the telephone tool: send delivers and returns, ask waits for the answer, reply answers an inbound message, list shows reachable sessions.
A Pi session that turns its telephone back on at start, while another live session on the machine holds its name (for example a fork of it), answers as <name>-<last 6 characters of its session id> instead.
Allowlist entries: owner (your own sessions, the default), local (this machine), user:<login> (every session of that Tailscale user), <session>@<machine> (* works in either part; a short machine name matches only inside your own tailnet), and * (anyone this machine trusts).
Files
Agents send images, audio, documents and archives with files on send, ask
or reply, for example { action: "send", to: "reviewer", files: ["./photo.png"], message: "What do you see?" }. The message is optional with files. Paths expand
~ and resolve relative to the session's working directory. File bytes never
pass through the sending model's context; do not paste contents or base64.
- Pi:
/telephone file <address> "path with spaces.png" [message]. - Claude Code:
/telephone:file <address> "path with spaces.png" [message].
Files arrive under ~/.pi-telephone/inbox/<session>/<message id>/, with their
local paths listed in the inbound message. Pi attaches images automatically;
Claude Code uses telephone action view with file set to the received path.
Pi draws received images inline when the terminal supports images (for example iTerm2, Kitty, Ghostty or WezTerm) and the show-images setting is on, and otherwise shows a placeholder.
view shows images up to 3.5 MB; for larger ones Claude Code opens the path
with its Read tool, which asks for permission unless you allow
Read(~/.pi-telephone/inbox/**) in your Claude Code permission settings.
Treat received files as untrusted data and never run them.
Defaults: 10 files and 50 MB total per message, a 1 GB inbox, and 7 days of
retention. Copy anything worth keeping. The exchange's config.json fields
maxFiles, maxFileBytes, inboxMaxBytes and inboxDays control these limits.
Both exchanges and receiving sessions need 0.2.0 or later for files; text
messages still work with older versions.
From another Pi extension
An extension in the same Pi process can control that session's telephone, for example to hand a name over to a fork and take it back later:
let telephone: TelephoneApiV1 | undefined;
pi.events.emit('pi-telephone:api', { version: 1, provide: api => { telephone = api; } });
await telephone?.on('assistant-main'); // turn on, or rename while on
await telephone?.status(); // { on, name, address }
await telephone?.off();
provide runs synchronously when pi-telephone is loaded, and telephone stays undefined otherwise.
Calls made before the session starts wait for it.
A name held by another live session on the machine rejects with code: 'name_taken', and calls after the session closed reject with code: 'not_active'.
The types are TelephoneApiV1 in pi/index.ts.
Use from another host
A Node program that hosts agent sessions, such as pi-fleet, uses the same session client as the Pi extension and the Claude Code plugin, from pi-telephone/host.
It gets the same exchange, the same start on demand, and the same caller identity and policy.
import { TelephoneClient, type InboundMessage } from 'pi-telephone/host';
const line = new TelephoneClient({
harness: 'pi-fleet', version: '0.6.5',
onMessage: async (message: InboundMessage) => ({ accepted: true }), // or { accepted: false, reason }
});
const address = await line.register({ key: 'pi-fleet:<session id>', name: 'secretary', harness: 'pi-fleet', cwd, hostPid: process.pid }, ['owner']);
await line.send({ to: 'reviewer@bobs-mbp', text: 'Hello' });
const { reply } = await line.ask({ to: 'reviewer@bobs-mbp', text: 'Ready?', timeoutMs: 600_000 });
await line.send({ to: message.from.address, replyTo: message.id, text: 'Answer' }); // a reply
await line.update({ status: 'busy' }); // 'idle' when the session waits for input
await line.close(); // unregisters the line
- Use one
TelephoneClientfor each line (session name); one process can hold many. - The first client that finds no exchange starts
dist/exchange.mjsfrom its package with Node.js 20 or later, detached, under~/.pi-telephone(PI_TELEPHONE_HOMEoverrides it). - When the client runs inside a systemd unit (
INVOCATION_IDis set), it starts the exchange withsystemd-run --useras its own transient unit,pi-telephone-exchange-<first 8 hex digits of the SHA-256 of the home path>, because systemd stops even detached processes with their unit. Ifsystemd-runfails, it starts the exchange detached as above. onMessageis the acknowledgement: return{ accepted: true }or{ accepted: false, reason }. The exchange has already checked trust and the line's allowlist.fromcarriesaddress,session,machine,fqdn,login,displayName,harnessandlocal.connect()returns the exchange:version,featuresandmachine, whoseloginis the machine's owner.- A client reconnects and registers again by itself after the exchange restarts. It emits
connected,reconnected,disconnectedandretrying(with the error). - Send
towith every reply, as above: after an exchange restart the exchange no longer knows where a message id came from. features: []marks a host that cannot receive files; the exchange then refuses file sends to its lines.deferReplies: truealso passes replies to the host's own asks toonMessage, and the ask returns only afterresolveReply(message), so a host can store a reply before the asking tool sees it.ask({ id })sets the call's message id up front;waiting(id)tells whether that ask still waits.- Errors are
TelephoneErrorobjects with acode. - Do not call
shutdownExchange()when the host stops: other sessions share the exchange. Close the host's own lines.
Version skew:
- A machine runs one exchange, from whichever installed copy of pi-telephone started it. After an upgrade, run
npx pi-telephone stoponce when no call is pending; the next client starts the exchange from its own copy. - A 0.3 client works with a 0.2.x exchange. A line with a harness name that 0.2.x does not know, such as
pi-fleet, registers there ascliuntil the exchange restarts on 0.3. - A 0.3 exchange shows such names only to peers on 0.3 or later; 0.2.x peers see
cli. Its messages carrycliuntil it has seen the peer's hello, whichlistand file sends fetch.
Upgrading
After updating the package, run npx pi-telephone stop once so the exchange
restarts on the new version (or /telephone restart in Pi). Restart sessions
that should send or receive files.
stop returns after the exchange process has exited, and it never starts one: with none running, it prints "No exchange is running".
Connecting two people
- In Tailscale, share a machine with each other, in both directions.
- Each side trusts the other's Tailscale login:
/telephone trust friend@example.comin Pi,/telephone:trust friend@example.comin Claude Code, ornpx pi-telephone trust friend@example.com. - In each session that should take their calls:
/telephone allow user:friend@example.com.
Security model
- Only Tailscale peers can reach an exchange, and the caller's identity comes from Tailscale.
- Machine trust and the session allowlist both have to admit a caller; replies to your own calls are the only exception.
- Only a human widens access: through a command, or by approving a confirmation dialog when an agent asks.
- Inbound text is framed as another agent's message, not the user's; Claude Code adds its own guard for messages from other sessions.
- A session that is not listening does not exist to callers: "not reachable" never reveals whether a session exists.
Troubleshooting
npx pi-telephone statusshows the exchange, its Tailscale address, trusted users and local sessions;npx pi-telephone listshows every reachable session.- The exchange logs to
~/.pi-telephone/exchange.log. - With the macOS application firewall on, allow incoming connections for
node. - Claude Code's
crossSessionInboundsetting applies to telephone calls:refusedrops them andholdwaits for your approval.