pi-xfer

Cross-context handoff extension for pi coding agents: structured markdown handoffs over local sockets, cross-machine mesh transport, async board, and web picker.

Packages

Package details

extension

Install pi-xfer from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-xfer
Package
pi-xfer
Version
0.6.0
Published
Oct 14, 2026
Downloads
592/mo · 592/wk
Author
azzgo
License
MIT
Types
extension
Size
5.9 MB
Dependencies
0 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-xfer

npm version license

Structured markdown handoff between pi coding agents. Instead of chat fragments, agents exchange a document — Context / Problem / Requirements / a return address — that the receiving agent can actually act on. Local Unix-socket delivery works out of the box; the Mesh adds opt-in cross-machine transport; the web picker pulls structured context straight from the browser.

Intro Demo

Chat Logs Are Not a Handoff — pi-xfer Sends Documents

~76s of two real pi sessions exchanging handoffs.

▶ Watch on YouTube →

Quickstart

pi install npm:pi-xfer
pi --xfer alpha   # terminal 1
pi --xfer beta    # terminal 2

Then tell alpha:

/xfer beta Summarize this repo and send it back as a handoff

Full walkthrough in docs/guides/quickstart.md · cross-machine setup in docs/guides/mesh-setup.md.

Capabilities

Capability What it does
Local transport Unix-socket peers at ~/.pi/xfer/<name>.sock; /xfer list, zombie GC (/xfer gc), metadata files, install self-check (/xfer doctor); `/xfer broker start
Mesh transport Opt-in cross-machine delivery over RivetKit (/xfer mesh up/down/list); one in-process actor per instance, engine-side discovery, durable queue, bundle + on-demand native runtime (see docs/adr/0013)
Node descriptions Self-declared capability note per mesh node (/xfer desc <text>, no text clears); stored on the node's actor, read per node and attached to the broker's targets listing so a picker user can pick by fit. Unverified self-declaration — routing stays with the consumer
Board Machine-local async collaboration cards (/xfer board); append-only entries, human-cleaned (see docs/adr/0014)
Web picker Tampermonkey userscript + local broker: pick page elements, record interaction spans, submit as handoff (see docs/dev/web-picker.md)

Install the userscript straight from the raw URL (the .user.js suffix triggers Tampermonkey's install prompt): https://raw.githubusercontent.com/azzgo/pi-xfer/main/web-picker.user.js

Positioning

pi-xfer covers heavy-context handoff: structured documents, cross-machine transport, and browser capture. For lightweight same-machine notes ("check this file", quick questions), pi-intercom is the better fit — the two coexist naturally.

Docs

User guides

Development

Layout

  • docs/guides/ — user guides (quickstart, mesh setup, agent host setup)
  • docs/adr/ — decision records (mesh transport, board scope, web-picker record philosophy)
  • CONTEXT.md — glossary (Mesh, Node, Board, Card, Marker, …)
  • mesh-runtime.src/ + mesh-runtime.cjs — bundled mesh engine, source and committed build product
  • web-picker.src/ + web-picker.user.js — userscript source and committed build product
  • broker-main.ts + broker.cjs, admin-main.ts + admin.cjs — the two daemons, source and committed build products (npm run build produces all four)

pi-xfer was formerly maintained inside azzgo/dotfiles (pi/agent/extensions/xfer/); history preserved from the initial commit.

Development

npm install
npm test
npm run build

The committed bundles (broker.cjs, admin.cjs, mesh-runtime.cjs, web-picker.user.js) are built with esbuild targeting Node 20+; the extension host runs on whatever Node pi requires (engines: >=22). npm test fails if a committed bundle is stale — run npm run build and commit the artifacts.

Acknowledgements

License

MIT