pi-lattice
Agent-to-agent messaging, session trees, composable roles and shared ownership for Pi
Package details
Install pi-lattice from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-lattice- Package
pi-lattice- Version
0.11.0- Published
- Nov 17, 2026
- Downloads
- 1,350/mo · 1,350/wk
- Author
- hedgecoin
- License
- MIT
- Types
- extension
- Size
- 1.1 MB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"extensions": [
"./extensions/launcher.js",
"./extensions/pane.js",
"./extensions/canopy.js",
"./extensions/a2a.js",
"./extensions/roles.js",
"./extensions/graph.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-lattice
Agent-to-agent messaging, session trees, composable roles and shared ownership for Pi.
Use it
Install it into Pi once:
pi install npm:pi-lattice
From a checkout of this repository, pi install /path/to/pi-lattice does the same from source.
Then open pi as you always do, in any directory. Where you have sessions, in this repository or any other, Pi opens on the canopy: all the work as a tree, the same one wherever you opened it, with the session you open in a box over it.
enteron a session opens its chat over the tree, with all of Pi. The top of the box says whose session it is and what it is doing.alt+lcloses it back into the tree. The session carries on either way.- The arrows move over the tree: along a level, up into what is under an item, down to what it belongs to.
/goes to an item by part of its name. What is selected has▸before its name. ffolds what is under an item into it, and the tree draws in;fagain unfolds it. A tree that does not fit the terminal draws in by itself before anything has to be scrolled to.?lists every key, and the foot of the screen always ends with it.- Colour says whose a piece is, a ring that an agent is on it, amber that it needs someone.
tabgoes to the next thing that does, and what it asks is drawn under the tree with the keys that answer it (y/n,a/x).ois always among them: type something else instead, and the session reads that rather than an answer. plists the sessions in a pane instead, where they are made, stopped, archived and answered:
◆ shop 3 sessions
▸ ⠹ checkout feature
├ ● payments ✉1 task
└ ○ impl @sam offline
──────────────────────────────────
alt+l to answer 1 waiting
- To open on the chat with that pane always on its left, as before, set
pane.hometochat(,in the pane, or/lattice config). Thenalt+lgives the pane the keyboard andcopens the canopy. - In a git repository there is nothing to set up: Pi opens on an empty canopy that says your first message starts the tree, and you type or paste it there. With work in another repository already, that work is drawn and this repository is one item on it, selected:
enteris the chat, and your first message there starts its tree. Each new session joins with its first message. Elsewhere, run/latticeonce. - What needs you is listed above the tree: questions a background session is stuck on, messages to approve.
alt+lgives the pane the keyboard, and you answer them where they are (y/n,a/x, oroto say something else instead). - With the keyboard, the chat steps aside to show the selected session in full.
enteropens it in this terminal, with all of Pi. You can switch at any time, even mid-turn: the work you leave carries on in the background. ncreates a child session from one form. Agents can also delegate on their own. Children run in the background, each on the model you choose. A child can be told to wait on others: it shows in the tree at once and starts by itself when they have finished.copens the canopy: all the work as a tree, the team at the root and tasks at the tips. Colour says whose a piece is, a ring that an agent is on it, amber that it needs someone. Work can be planned before anyone is on it;sputs a session on a planned item.- A project too large for the screen folds around your work: the way to your sessions is open, and everything else is one line each that says how far along it is, what in it needs someone, and whose agents are in it.
enterunfolds a line; a teammate's number opens the tree around theirs. /lattice server startstarts a board on your machine, where work is tracked as issues: epics, features, stories, tasks and bugs by default, or whatever structure you define with/lattice scheme edit. There is nothing to deploy. The canopy then draws the issues, with the sessions on them.- Agents keep the issues: they file them, break them down, order them, take the next one that is ready, check each other's results and close them. You do not edit issues. You say what you want:
spaceon anything in the tree opens a line to the session tending that branch ("this first", "drop this", "ask me before anything here lands"). It changes the work to match and answers in a sentence at the foot of the tree. A line that is a rule stays on the item as a direction (⚑), and every session working under it is told. +beside an item means an agent changed it since you last looked.ugoes through what changed, with who did it and why;xthere puts it back.- Agents that are not Pi sessions use the same work from a shell:
pi-lattice work nexttakes the next ready issue and prints its brief and the directions above it;pi-lattice work primeprints what to put in such an agent's instructions. /lattice server shareopens your board to teammates and prints the address they join with (/lattice server <address>); it is there while your machine is on. For a machine that stays on, runpi-lattice serveron it instead and have everyone join that.rrenames a session,darchives it,sstops what it is doing.?lists every key, and/lattice helpevery command.,in the pane, or/lattice config, opens the settings: models, roles, limits and the pane itself, for this repository or for all of yours./lattice doctorchecks the setup.- Sessions are told how to talk to each other, and you can read and change all of it:
/lattice promptshows what a session has been told and the file each part comes from. - Work in several repositories shows on one canopy and in one pane, whichever of them the terminal is in. A repository whose host has gone to sleep is one item;
enterwakes it. Opening a session from another repository moves this terminal there;-goes back. - Once you and a teammate are on the same server, their sessions show in your pane with nothing more to set up, in every repository you share, and the pane's first line says who is around. What teammates are running in repositories you do not have is listed too; a session under the cursor is kept up to date as it goes.
ooffers one of yours to a teammate andtasks for one of theirs, on the tree or in the pane, cloning the repository first if you do not have it. The offer and the request go through the server; the session itself goes straight from one machine to the other, so both of you must be online and your machines must be able to reach each other. The server never sees a conversation.
See the pane readme for keys, and a feature through the full lifecycle for a walkthrough.
What is here
| Package | What it does |
|---|---|
pane |
Pi extension. The session trees of every repository as a left pane inside Pi, and the /lattice command. |
canopy |
Pi extension. All the work as a tree that grows upward: who owns each piece, which agent is on it, how far along it is. c in the pane. space says what you want about any item to whatever tends it. |
a2a |
Pi extension. Sessions message each other; inbound mail can require human approval. Also works alone (try it). |
roles |
Pi extension. Compose a session's role from markdown fragments and change it mid-session. Also works alone (guide). |
graph |
Pi extension. Lets an agent spawn child sessions and see the tree. |
host |
Library. Owns the tree and runs the sessions you are not in. |
collab |
Library. Shares trees between the people of a team, machine to machine, with signed ownership handoff. |
app |
Everything assembled: the Pi package, the launcher, the background host, the command line. |
protocol |
The contracts everything else shares: envelope, events, wire types, state machines. |
Each package depends only on protocol and works on its own; app is the one place they are put together. A test enforces this (ADR 0014).
Documentation
- Architecture
- Decisions
- Testing by hand with a real model
- Envelope specification
- Settings, roles files and environment variables
- Roles
- Roles, as composed
- Ownership and handoff
Development
npm install
npm run check # typecheck and tests
npm run dev # open Pi on this checkout, in a scratch repository under .dev/ (-- --faux for the scripted model)
npm run eval # the scenarios with a real model: what sessions did, checked against what their roles say (spends tokens)
npm run docs # rewrite docs/settings.md from the settings table, and docs/roles-composed.md from the role fragments
npm run build # build the package that is published into dist/pi-lattice
npm run spike:phase0 # re-run the Phase 0 verification against real Pi processes
Requires Node 22.19 or newer and git. Tests and spikes run real Pi processes against a scripted model: no network, no tokens, and they do not read your Pi configuration. The canopy is also held to being read: its colours to a contrast on dark and light backgrounds, every line to the width of the terminal, a small project to fitting it, and every key to being listed (ADR 0042). The tests of the pane in Pi's terminal interface need script (util-linux) for a pseudo-terminal and are skipped where it is missing.
Releasing
Pushing to main releases. GitHub Actions works out the next version from the conventional commits since the last release:
| The commits since the last release include | The next version |
|---|---|
a breaking change (feat!:, or a BREAKING CHANGE: footer) |
a major version; a minor one while the version is 0.x |
a feat |
a minor version |
a fix or a perf |
a patch |
only docs, test, chore, ci, refactor and the like |
nothing is released |
The workflow runs the whole suite on the pushed commit, builds the package, publishes it to npm, tags the commit v1.2.3 and writes a GitHub release that lists the features and fixes. Nothing is committed back, so there is nothing to pull afterwards: the version is in the tags, not in a package.json. To see what the next push would release:
node scripts/release.ts
Not done yet
- Models of other providers, and larger work. The mechanics are tested against a scripted model. Whether a model does what the roles, the notes and the tool guidelines say is checked with eleven small scenarios on Claude Haiku 5.5 and Sonnet 5.5, which pass (ADR 0039). Nothing has been run on another provider's models, or on work the size of a real feature. The hand test has the steps for the pane.
- Two real machines. Sharing is tested with two isolated hosts on one machine (manual script).
- Sharing across arbitrary networks. The two machines must reach each other directly (LAN, VPN, SSH tunnel). Hole-punching is not built (ADR 0012).
- The side pane relies on Pi internals. It falls back to a compact list if they change (ADR 0013).
- Licence. None has been chosen.