|
| 1 | +# Pi |
| 2 | + |
| 3 | +Create agents that run Pi on your computer, with any provider Pi supports, and answer you in Buzz. Each conversation continues its own Pi conversation. |
| 4 | + |
| 5 | +## Getting started |
| 6 | + |
| 7 | +1. Turn on **Pi** in **Settings** → **Plugins**. Pi needs Node.js 22.19 or later on this computer. |
| 8 | +2. Choose **New agent** → **Create a new agent**, pick **Pi** as the **Harness**, and choose its provider and model. |
| 9 | +3. Mention your agent in a conversation to give it work. |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +# Pi for Agents |
| 14 | + |
| 15 | +A desktop plugin that ships with Buzz on macOS, Linux and Windows, off until |
| 16 | +turned on in **Settings → Plugins**. Its agents run on |
| 17 | +[Pi durable](https://earendil.com/posts/pi-1-0/) (`@earendil-works/pi-durable`), |
| 18 | +not the Pi coding agent, with any provider Pi supports. |
| 19 | +Agents owns the identity, admission, configuration, and signed Buzz actions. This |
| 20 | +plugin owns Pi work after delivery handover. One Pi host process ([`host.mjs`](host.mjs)) |
| 21 | +runs every Pi agent here. Each agent has its own SQLite storage, and each Buzz |
| 22 | +conversation the agent is in is one durable Pi conversation. |
| 23 | + |
| 24 | +## Try it |
| 25 | + |
| 26 | +From the feature worktree: |
| 27 | + |
| 28 | +```sh |
| 29 | +source bin/activate-hermit |
| 30 | +BUZZODZ_PROFILE=pi-agents BUZZ_DEV_VIEWER= bin/just desktop |
| 31 | +``` |
| 32 | + |
| 33 | +Pi needs Node.js 22.19 or later on this computer (`node:sqlite`). On macOS and |
| 34 | +Linux the app's PATH is searched first, then an interactive login shell's, so |
| 35 | +Homebrew, nvm, fnm and similar installs work. On Windows, `node` must be on the PATH Buzz |
| 36 | +starts with. |
| 37 | + |
| 38 | +1. Turn on **Pi** in **Settings → Plugins**. Then open **Agents → New agent** |
| 39 | + and choose **Pi** as the **Harness**. Its **Model** starts on **Pi default**: |
| 40 | + the `defaultProvider` and `defaultModel` in `~/.pi/agent/settings.json`, as |
| 41 | + the `pi` command sets them. The first time Buzz asks Pi anything, it |
| 42 | + installs Pi's packages (a few seconds). |
| 43 | +2. Click the model (marked with Pi, and with the provider when Buzz has its |
| 44 | + mark) and choose a provider. A provider Pi has no key for shows an |
| 45 | + **API key** field; **Save to Pi** stores it in |
| 46 | + `~/.pi/agent/auth.json`, shared with the `pi` command. A provider that signs |
| 47 | + in some other way (OAuth, cloud credentials) says to run `pi`, then `/login`. |
| 48 | + Choose a model, click **Test connection**, then **Use**. Name the agent and |
| 49 | + click **Create agent**. Its library card shows the same control. |
| 50 | +3. Open the agent. Its **Identity** tab has the **Provider**, **Model**, |
| 51 | + **Thinking** level (Pi's default, or one the model has) and |
| 52 | + **Instructions**. Its **Settings** tab has the provider's key with **Test |
| 53 | + connection**, the **Workspace** (default `~/.buzz`), and thread or channel |
| 54 | + **Conversations**. |
| 55 | +4. In a channel, send: `@Pi create hello.txt containing hello in the workspace, |
| 56 | + read it back, and report what you found` (use the agent's actual name). |
| 57 | + Expect steps under your message, one reply in the thread, and the file in the |
| 58 | + workspace. Then reply in the same thread: `@Pi what did you write?`. It |
| 59 | + remembers, because the thread is the same Pi conversation. |
| 60 | +5. While it works, send another mention in the thread. It steers the running |
| 61 | + turn: Pi reads it at its next step. The activity moves to the newer message. |
| 62 | +6. Quit Buzz during a long turn, start it again, and mention the agent in that |
| 63 | + thread. Pi continues the interrupted run from its storage, and the new |
| 64 | + mention steers it. |
| 65 | +7. Choose **View activity** on one of its messages in that thread, or open the |
| 66 | + agent's **Activity** tab from there. **This thread** is its Pi conversation, |
| 67 | + with the agent's other recent ones below. **View transcript** shows each |
| 68 | + turn's prompt, thinking, tool calls with their output, and what it sent, |
| 69 | + read from Pi's storage. |
| 70 | + |
| 71 | +The composer's model picker offers the agent's provider's models, and each |
| 72 | +model's thinking levels, for one turn. Without a pick, a turn runs the |
| 73 | +agent's saved model and Thinking level. |
| 74 | + |
| 75 | +## Checks |
| 76 | + |
| 77 | +```sh |
| 78 | +bin/pnpm exec vitest run src/bundled/pi |
| 79 | +PI_DEPS="$HOME/Library/Application Support/Buzz/pi/deps/<sum>" bin/pnpm exec vitest run src/bundled/pi/host.live.test.ts |
| 80 | +``` |
| 81 | + |
| 82 | +The unit tests cover the stdio protocol (`pi.ts`), the runtime against a fake |
| 83 | +host, the install script in a throwaway home, and the New agent and Settings |
| 84 | +fields. The opt-in live test runs the real `host.mjs` on Pi durable, using Pi's |
| 85 | +faux provider as the model. It checks that a final `send` ends the run, that the |
| 86 | +model reads what a Buzz tool answered, that a plain answer comes back as text, |
| 87 | +that a request steers a working run, that a run cut off by a stop continues in |
| 88 | +the next host, that aborting a run leaves it unanswered, and that a deferred |
| 89 | +Buzz tool is offered once `tool_search` finds it. `PI_DEPS` is any folder |
| 90 | +the launcher installed Pi's packages in. |
| 91 | + |
| 92 | +## Buzz's copy of Pi's packages |
| 93 | + |
| 94 | +[`launch.mjs`](launch.mjs) runs the host on this computer's Node. On macOS and |
| 95 | +Linux, [`pi.sh`](pi.sh) finds that Node and starts the launcher on it; Windows, |
| 96 | +which has no bash, starts `node` itself. The launcher's first line on stdin |
| 97 | +carries the host source and the packages to install, since together they pass |
| 98 | +Windows' 32 KB command line. On first use it runs `npm ci` with |
| 99 | +[`deps/package-lock.json`](deps/package-lock.json), which pins every package and |
| 100 | +its integrity hash. Install scripts are off, and npm uses the registry it is |
| 101 | +configured for. Each lock gets its own folder under |
| 102 | +`~/Library/Application Support/Buzz/pi/deps/` |
| 103 | +(`${XDG_DATA_HOME:-~/.local/share}/buzz/pi/deps/` on Linux, |
| 104 | +`%LOCALAPPDATA%\Buzz\pi\deps\` on Windows). The folder appears |
| 105 | +whole or not at all, and is shared by every Buzz build. An install removes the |
| 106 | +folders no build has started for 30 days. Agents' storage is in `agents/<pubkey>.sqlite` |
| 107 | +beside it. A lock on each agent's storage keeps a second Buzz build from opening |
| 108 | +it; that build's turns fail and say so. It also keeps Pi's `auth.json` writes |
| 109 | +from colliding with the `pi` command's. |
| 110 | + |
| 111 | +To update Pi, change the versions in [`deps/package.json`](deps/package.json), |
| 112 | +then regenerate the lock without registry URLs: |
| 113 | + |
| 114 | +```sh |
| 115 | +cd src/bundled/pi/deps |
| 116 | +npm install --package-lock-only --ignore-scripts --omit-lockfile-registry-resolved |
| 117 | +``` |
| 118 | + |
| 119 | +## Limits and boundaries |
| 120 | + |
| 121 | +- Only the owner's events, or ones the owner delegated, start work. Watches, |
| 122 | + timers and catch-ups run as standalone turns, each a one-off Pi |
| 123 | + conversation, in the lanes and with the 5-minute deadline Buzz's agent |
| 124 | + runner gives every harness. |
| 125 | +- Pi has the coding tools `read`, `write`, `edit` and `bash`, in the workspace, |
| 126 | + with no sandbox or approvals, like Claude's `bypassPermissions`. Buzz's tools |
| 127 | + are offered as `buzz_<name>` (`buzz_send`, `buzz_read`, …), since `read` and |
| 128 | + `edit` would collide. They run inside Buzz through the agent's native-held |
| 129 | + handle, so the host holds no Buzz key. A final `buzz_send` ends the run. |
| 130 | + The Buzz tools Claude and Codex load on search (the attention tools, and |
| 131 | + those plugins add) are deferred: Pi's `tool_search` loads them when the |
| 132 | + model looks for them, and they stay loaded in that conversation. |
| 133 | +- **Stop** on a turn's activity aborts the Pi run it is in, and posts |
| 134 | + nothing. |
| 135 | +- A turn that answered in text and never called `buzz_send` has its answer |
| 136 | + posted in the thread, as goose does. A turn that fails posts `⚠️ I couldn't |
| 137 | + finish that: …` and tags the owner. |
| 138 | +- A Buzz tool call that a stop cuts off runs again when the run continues, so a |
| 139 | + `send` may be posted twice. |
| 140 | +- Pi's storage keeps every conversation, including each one-off watch or timer |
| 141 | + turn; nothing prunes it. The Activity tab lists thread and channel |
| 142 | + conversations only, and rereads an open transcript when its turn ends, not |
| 143 | + as it streams. |
| 144 | +- A host that stops while a turn waits is started again once and waits for it |
| 145 | + there. A run resumed that way shows no steps. |
| 146 | +- Runs left unfinished when the app quit continue at the first turn after it |
| 147 | + starts again, in whatever thread. A mention's run shows as working and its |
| 148 | + answer or failure is posted where it would have been, but it shows no steps |
| 149 | + and Stop does not reach it. A watch's or timer's run is ended instead, as |
| 150 | + quitting ends other harnesses' turns: continued, it would have no deadline. |
| 151 | +- Pi durable records some requests that have no answer, such as compaction's, |
| 152 | + only in its totals. Usage counts each model's share of those as one more |
| 153 | + request, at the newest compaction. |
| 154 | +- A provider that needs more than a key, such as Bedrock or Vertex, is set up |
| 155 | + with the `pi` command. Signing in from Buzz is not supported. |
| 156 | +- A `!command` or `$NAME` key in `auth.json`, which the `pi` command runs or |
| 157 | + reads from its environment to get the key, is not used: one host serves |
| 158 | + every agent, and a command would hold them all, and the desktop app often |
| 159 | + lacks the shell's environment. Its turns fail and say so; enter the key in |
| 160 | + Buzz instead. |
| 161 | +- Only Pi's built-in providers run. One that a Pi package adds (`packages` in |
| 162 | + Pi's settings), such as databricks, is not loaded: the provider field, the |
| 163 | + New agent Model field and a turn's error say so, and Use and Save wait for another. |
| 164 | +- On Windows, Pi's `bash` tool needs a bash, such as Git for Windows'; the |
| 165 | + other tools work without one. |
| 166 | +- Windows, Linux, packaged-app behavior, and human acceptance need separate |
| 167 | + validation. |
0 commit comments