n2n-nexus 0.12.6 → 0.13.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.13.1] - 2026-11-15
+
+Upgrade the host; the client needs nothing (contract version 5). Start new conversations afterwards: one started before keeps the old `peers` definition, whose `includeOffline` the host now ignores.
+
+### Removed
+
+- `peers` no longer takes `includeOffline` and never lists offline sessions: AI work starts new conversations far more often than it resumes old ones, so listing the ones that ended in the last 24 hours to leave them a message was little used. A message sent to an offline session by its session ID still waits for it (a reply to a sender that ended its conversation, a session that only looked offline after 30 minutes without activity). The contract's `timing.peerWindowMs` is gone with it.
+
+## [0.13.0] - 2026-11-15
+
+Upgrade the host and the client together for pi (the contract version stays 5: an older host answers a pi hook with 400, which the hook ignores). The database is upgraded in place: keep `nexus.db`. An older host refuses the upgraded database. After upgrading the host, start new Claude Code and Codex conversations: one started before keeps the old tool definitions, in which a session's client is only claude or codex, so its `peers` fails as soon as a pi session is listed (with `includeOffline`, also an offline one).
+
+### Added
+
+- pi as a client: `n2n-nexus install pi` writes a pi extension (`~/.pi/agent/extensions/n2n-nexus.ts`, or under `$PI_CODING_AGENT_DIR`) that runs `n2n-nexus hook pi` on pi's session start, prompt, tool result, end of run and shutdown, continues a run when messages arrive during it and wakes an idle pi session through the background wait, and registers the MCP server with `pi mcp add`; `uninstall pi` removes both and `doctor pi` checks them. pi's MCP tool calls carry no session, so the MCP server started by pi names the processes above it (pi starts it through npx and a shell) and its machine, and the host attributes the call to the session the nearest pi process among them on that machine reported last.
+
 ## [0.12.6] - 2026-11-10
 
 Upgrade the host and the client together (contract version 5), then run `n2n-nexus install <client>` again so the background wait hook gets its new timeout. The database is upgraded in place: keep `nexus.db`. An older host refuses the upgraded database.

package/README.md

@@ -53,7 +53,7 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 
 **Quick summary**
 
-- **Install**: the host `n2n-nexus-host` with Scoop / Homebrew / a Releases archive; the client with `npm i -g n2n-nexus@latest`, then `n2n-nexus install <claude|codex>`
+- **Install**: the host `n2n-nexus-host` with Scoop / Homebrew / a Releases archive; the client with `npm i -g n2n-nexus@latest`, then `n2n-nexus install <claude|codex|pi>`
 - **Protocol**: Model Context Protocol (MCP); the adapters reach the host over HTTP
 - **Storage**: one SQLite database in the host's data directory
 - **Good for**: multi-assistant coding sessions, project handoffs, shared decisions, meeting records, task tracking, project manifests
@@ -62,7 +62,7 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 ## 🎯 Why use it?
 
 - Coordinate multiple AI assistants working on the same project.
-- Let Claude Code and Codex conversations message each other directly: a message arrives whole through the client's hooks, wakes a waiting conversation, and is answered with `reply`; each session shows the machine and environment it runs on.
+- Let Claude Code, Codex and pi conversations message each other directly: a message arrives whole through the client's hooks, wakes a waiting conversation, and is answered with `reply`; each session shows the machine and environment it runs on.
 - Hold meetings among assistants and keep their decisions. When you take part, your conversation holds the user's seat: you decide each draft and end the meeting, and the assistants' consensus is only reported.
 - Share project manifests, decisions, and assets across IDEs and machines.
 - Keep decisions, proposals, and updates in a local meeting and message log; old data is cleaned up after the retention you set.
@@ -87,13 +87,13 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 
 - **The host is the source of truth**: install it once and keep it running, as a tray app or as a background service.
 - **MCP adapters are stateless**: each IDE starts an adapter (`n2n-nexus mcp`), which forwards tool calls to the host.
-- **Every Claude Code and Codex conversation has its own identity**: client hooks register the conversation with the host and deliver new direct messages and meeting messages to it; each tool call names its conversation through the request metadata the client attaches, never through model-supplied arguments.
+- **Every Claude Code, Codex and pi conversation has its own identity**: client hooks (for pi, an extension) register the conversation with the host and deliver new direct messages and meeting messages to it; each tool call names its conversation through the request metadata the client attaches (for pi, the pi process above the MCP server), never through model-supplied arguments.
 - **Cross-environment by design**: point `NEXUS_ENDPOINT` at the same host from different machines or shells. The host listens on `127.0.0.1` by default; turn on LAN access only on a trusted network.
 
 ## 🚀 Quick start
 
 1. Install and start the host, `n2n-nexus-host`, with Scoop, Homebrew or an archive from [Releases](https://github.com/n2ns/n2n-nexus/releases): [Installation guide, steps 1–2](docs/INSTALL.md#1-install-the-host).
-2. Install the client and connect Claude Code or Codex (`npm i -g n2n-nexus@latest`, then `n2n-nexus install claude` or `n2n-nexus install codex`): [step 3](docs/INSTALL.md#3-install-the-client-for-claude-code-and-codex).
+2. Install the client and connect Claude Code, Codex or pi (`npm i -g n2n-nexus@latest`, then `n2n-nexus install claude`, `n2n-nexus install codex` or `n2n-nexus install pi`): [step 3](docs/INSTALL.md#3-install-the-client-for-claude-code-codex-and-pi).
 3. Codex only: `install codex` trusts the n2n-nexus hooks in Codex; if it says it could not, trust them by hand: [step 4](docs/INSTALL.md#4-turn-on-the-codex-hooks-one-time-required).
 
 Other MCP clients and several machines: see the [Installation guide](docs/INSTALL.md). Using it, troubleshooting and configuration: see the [User guide](docs/USER_GUIDE.md).
@@ -108,7 +108,7 @@ The host exposes 36 tools, grouped by purpose:
 | **Projects & assets** | `search_projects`, `get_project`, `update_project`, `rename_project`, `sync_project_assets`, `upload_project_asset` | Find, read, update, and rename projects; sync manifests and internal docs; upload binary assets. |
 | **Global docs** | `list_global_docs`, `get_global_doc`, `sync_global_doc`, `get_global_strategy`, `update_global_strategy` | List, read, create and update shared global documents and the master strategy document. |
 | **Messaging** | `send_message`, `read_messages`, `list_events` | Post meeting or global messages; read them and the activity log. |
-| **Direct messages** | `peers`, `send`, `read`, `reply`, `broadcast`, `listen`, `set_profile` | Find other Claude Code / Codex conversations, message them, read and answer what arrives, notify every online conversation, wait for messages, and name yourself. |
+| **Direct messages** | `peers`, `send`, `read`, `reply`, `broadcast`, `listen`, `set_profile` | Find other Claude Code / Codex / pi conversations, message them, read and answer what arrives, notify every online conversation, wait for messages, and name yourself. |
 | **Meetings** | `list_meetings`, `start_meeting`, `join_meeting`, `leave_meeting`, `stance`, `end_meeting`, `archive_meeting`, `reopen_meeting` | List and open meetings; join (woken by new messages) or leave them; endorse or object to the current draft, which closes the meeting by consensus or, with the user's seat, is decided by the user; close, archive, and reopen them. |
 | **Tasks** | `create_task`, `get_task`, `list_tasks`, `update_task`, `cancel_task` | Create, update and track tasks that assistants manage themselves. |
 | **Maintenance** | `host_maintenance`, `host_delete_project` | Prune or clear the global chat stream; run the retention cleanup now; export a meeting as markdown; delete a project. |

package/SECURITY.md

@@ -28,7 +28,7 @@ n2n-nexus runs a local HTTP host, `n2n-nexus-host`, that stores coordination dat
 Key boundaries to be aware of:
 
 - **Unsigned binaries**: The `n2n-nexus-host` release binaries are not code-signed yet. Verify a download with the release's `SHA256SUMS` and `gh attestation verify <file> --repo n2ns/n2n-nexus` (build provenance), or install through Homebrew, which builds from source.
-- **Local trust model**: Every process running as the same operating-system user is trusted. The host has no authentication; such a process can call it directly or read and write `nexus.db` and the client transcripts under `~/.claude` and `~/.codex`. Conversation IDs and Claude tool-use bindings route direct messages between conversations; they are not credentials, so an AI session with shell access can act as another conversation of the same user. Checks inside the host cannot prevent that while the data stays readable to that user. The barrier that matters is the client's permission to run commands, which the user controls. To isolate agents from each other, run them as different operating-system users, each with its own host and data directory.
+- **Local trust model**: Every process running as the same operating-system user is trusted. The host has no authentication; such a process can call it directly or read and write `nexus.db` and the client transcripts under `~/.claude`, `~/.codex` and `~/.pi`. Conversation IDs, Claude tool-use bindings and pi process IDs route direct messages between conversations; they are not credentials, so an AI session with shell access can act as another conversation of the same user. Checks inside the host cannot prevent that while the data stays readable to that user. The barrier that matters is the client's permission to run commands, which the user controls. To isolate agents from each other, run them as different operating-system users, each with its own host and data directory.
 
 - **Host network exposure**: The host binds to `127.0.0.1` by default. LAN access (the tray's **Allow LAN access**, `"host": "0.0.0.0"` in `settings.json`, or `--host 0.0.0.0`) exposes it to your local network, and it then answers LAN discovery on UDP `discoveryPort`. There is no authentication layer in the open-source baseline — only expose the host beyond localhost on networks you control.
 - **Browser requests**: The host has no authentication, so it refuses requests that carry a browser `Origin` header or a cross-site `Sec-Fetch-Site` header (403), requires `Content-Type: application/json` on POST (415) and caps request bodies at 16 MB (413). It also rejects any `Host` header that is not an IP literal, `localhost`, `host.docker.internal` or a name listed in `allowedHosts` in `settings.json`, which closes DNS-rebinding attacks where a page reaches the host as a same-origin request under the attacker's domain. MCP adapters and scripts are unaffected.

package/build/cli/client-command.js

@@ -1,5 +1,5 @@
 /**
- * Run the `claude` / `codex` command without a shell. On Windows npm installs
+ * Run the `claude` / `codex` / `pi` command without a shell. On Windows npm installs
  * them as `.cmd` shims, which Node cannot start without cmd.exe, and cmd.exe
  * would parse the arguments again: a message text from another session could
  * end a quoted argument and run commands, and a newline ends the command line.

package/build/cli/client-dirs.js

@@ -1,5 +1,5 @@
 /**
- * Where Claude Code and Codex keep their configuration. Node built-ins only:
+ * Where Claude Code, Codex and pi keep their configuration. Node built-ins only:
  * the hook command uses this to read a Codex conversation's title.
  */
 import os from "node:os";
@@ -10,3 +10,5 @@ export const claudeConfigDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(
 export const claudeJsonDir = () => process.env.CLAUDE_CONFIG_DIR || os.homedir();
 /** Codex's hooks.json, config.toml and state databases: CODEX_HOME, else ~/.codex. */
 export const codexHome = () => process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+/** pi's agent directory (extensions, mcp.json, settings.json): PI_CODING_AGENT_DIR, else ~/.pi/agent. */
+export const piAgentDir = () => process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");

package/build/cli/client-process.js

@@ -47,6 +47,31 @@ function describe(pid) {
         throw new Error(`no process ${pid}`);
     return { name: name.toLowerCase(), ppid };
 }
+/** The most processes ancestorPids lists (contract/hook.json caller.clientPids maxItems). */
+const MAX_ANCESTORS = 16;
+/**
+ * This process's parent, its parent and so on up to (not including) init,
+ * nearest first; on Windows, or where a parent cannot be read, the list ends
+ * there. pi starts the MCP adapter through npx and a shell, so the pi process
+ * is one of them (the host finds it among them).
+ */
+export function ancestorPids() {
+    const pids = [process.ppid];
+    if (process.platform === "win32")
+        return pids;
+    try {
+        while (pids.length < MAX_ANCESTORS) {
+            const { ppid } = describe(pids[pids.length - 1]);
+            if (ppid <= 1 || pids.includes(ppid))
+                break;
+            pids.push(ppid);
+        }
+    }
+    catch {
+        // Not readable: the processes found so far.
+    }
+    return pids;
+}
 /**
  * The process that ran this hook, past the shells it went through: the
  * nearest ancestor that is not a shell; undefined when it cannot be told.

package/build/cli/doctor.js

@@ -1,6 +1,6 @@
 /**
- * `n2n-nexus doctor [claude|codex]`: check that the Node path and the entry
- * script in the hook commands, and the Node path and npm's npx script in the
+ * `n2n-nexus doctor [claude|codex|pi]`: check that the Node path and the entry
+ * script in the hook commands (for pi, in its extension file), and the Node path and npm's npx script in the
  * MCP server command (`"<node>" "<npx>" -y n2n-nexus@latest mcp`), that
  * `install` wrote still exist and run, that the host those commands talk to answers
  * GET /health as n2n-nexus-host with this client's contract version, that
@@ -17,6 +17,7 @@ import { pkg } from "../config/index.js";
 import { hookEndpoint, isOurs, ourCommands, parseHookCommand } from "./hook-command.js";
 import { MCP_PACKAGE, VERSIONED_NODE_DIR, configFile, probeNode, readConfig } from "./install.js";
 import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
+import { PI_EXTENSION_MARK, piExtensionFile, readPiExtension, readPiExtensionFile } from "./pi.js";
 const ok = (text) => ({ ok: true, text });
 const bad = (text) => ({ ok: false, text });
 const VERSIONED_NOTE = "in a version directory that an upgrade may remove";
@@ -92,7 +93,72 @@ async function doctorHosts(endpoints) {
  * Check one client; prints the report and returns whether everything passed, or undefined when nothing is installed.
  * Adds the endpoints its hook and MCP commands use to `endpoints`, falling back to defaultEndpoint.
  */
+/** The MCP server registration of `client`: whether there is one (reported), and the endpoints it names. */
+function doctorMcp(client, endpoints, defaultEndpoint, report, mcp) {
+    const mcpFile = mcpConfigFile(client);
+    if (!mcp) {
+        report(`MCP server ${MCP_SERVER_NAME} in ${mcpFile}`, bad("not registered"));
+        return;
+    }
+    endpoints.add(mcp.endpoint === undefined ? defaultEndpoint : mcp.endpoint || LOCAL_ENDPOINT);
+    report(`MCP Node ${mcp.command}`, checkNode(mcp.command));
+    const [npx, ...rest] = mcp.args;
+    if (npx && rest.join(" ") === `-y ${MCP_PACKAGE} mcp`)
+        report(`MCP npx ${npx}`, checkEntry(npx));
+    else
+        report(`MCP command in ${mcpFile}`, bad(`not in the form "<node>" "<npx>" -y ${MCP_PACKAGE} mcp`));
+}
+/** pi: the extension file that carries the hooks, and the MCP server. */
+function doctorPi(endpoints, defaultEndpoint) {
+    const file = piExtensionFile();
+    const mcp = readMcpCommand("pi", mcpConfigFile("pi"));
+    const text = readPiExtensionFile(file);
+    if (text === undefined && !mcp)
+        return undefined;
+    const lines = [];
+    let failed = false;
+    let versioned = false;
+    const report = (label, check) => {
+        lines.push(`  ${check.ok ? "ok  " : "FAIL"} ${label}: ${check.text}`);
+        if (!check.ok)
+            failed = true;
+        if (check.text.includes(VERSIONED_NOTE))
+            versioned = true;
+    };
+    lines.push("pi");
+    if (text === undefined) {
+        report(`extension in ${file}`, bad("not installed"));
+    }
+    else if (!text.startsWith(PI_EXTENSION_MARK)) {
+        report(`extension in ${file}`, bad("not written by n2n-nexus"));
+    }
+    else {
+        const command = readPiExtension(text);
+        if (!command) {
+            report(`extension in ${file}`, bad("its Node path and entry script cannot be read"));
+        }
+        else {
+            if (command.endpoint)
+                endpoints.add(command.endpoint);
+            else
+                endpoints.add(defaultEndpoint);
+            report(`extension Node ${command.node}`, checkNode(command.node));
+            report(`extension entry ${command.entry}`, checkEntry(command.entry));
+        }
+    }
+    doctorMcp("pi", endpoints, defaultEndpoint, report, mcp);
+    if (failed) {
+        lines.push(`  fix: run "n2n-nexus install pi" again (add --node <path> to use a stable Node path such as /usr/local/bin/node).`);
+    }
+    else if (versioned) {
+        lines.push(`  note: after upgrading Node, run "n2n-nexus install pi" again, or install with --node <path> pointing at a stable entry such as /usr/local/bin/node.`);
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+    return !failed;
+}
 function doctorClient(client, endpoints, defaultEndpoint) {
+    if (client === "pi")
+        return doctorPi(endpoints, defaultEndpoint);
     const hooksFile = configFile(client);
     const mcpFile = mcpConfigFile(client);
     const lines = [];
@@ -126,18 +192,7 @@ function doctorClient(client, endpoints, defaultEndpoint) {
     }
     if (client === "claude" && commands.size > 0)
         report(`background wait hook in ${hooksFile}`, checkClaudeWait(config));
-    if (!mcp) {
-        report(`MCP server ${MCP_SERVER_NAME} in ${mcpFile}`, bad("not registered"));
-    }
-    else {
-        endpoints.add(mcp.endpoint === undefined ? defaultEndpoint : mcp.endpoint || LOCAL_ENDPOINT);
-        report(`MCP Node ${mcp.command}`, checkNode(mcp.command));
-        const [npx, ...rest] = mcp.args;
-        if (npx && rest.join(" ") === `-y ${MCP_PACKAGE} mcp`)
-            report(`MCP npx ${npx}`, checkEntry(npx));
-        else
-            report(`MCP command in ${mcpFile}`, bad(`not in the form "<node>" "<npx>" -y ${MCP_PACKAGE} mcp`));
-    }
+    doctorMcp(client, endpoints, defaultEndpoint, report, mcp);
     if (failed) {
         lines.push(`  fix: run "n2n-nexus install ${client}" again (add --node <path> to use a stable Node path such as /usr/local/bin/node).`);
     }
@@ -178,11 +233,11 @@ async function doctorCodexTrust() {
         + `  fix: run "n2n-nexus install codex" again, or ${MANUAL_TRUST}.\n`);
     return false;
 }
-/** Parse `[claude|codex]`, run the checks and return the exit code. */
+/** Parse `[claude|codex|pi]`, run the checks and return the exit code. */
 export async function runDoctor(argv) {
     const client = argv[0];
     if (client !== undefined && !isHookClient(client)) {
-        process.stderr.write("Usage: n2n-nexus doctor [claude|codex]\n");
+        process.stderr.write("Usage: n2n-nexus doctor [claude|codex|pi]\n");
         return 1;
     }
     try {

package/build/cli/hook.js

@@ -1,5 +1,5 @@
 /**
- * `n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]`: forward one client
+ * `n2n-nexus hook <claude|codex|pi> [--endpoint <url>] [--wait]`: forward one client
  * hook event to the daemon and print its output, or with `--wait` run the
  * background wait that wakes an idle conversation. Runs on every tool call, so
  * it loads only node built-ins (no MCP SDK or zod; node:sqlite only to read a
@@ -35,7 +35,7 @@ function argValue(argv, name) {
 function clientAndEndpoint(argv) {
     const client = argv[0];
     if (!isHookClient(client))
-        throw new Error(`unknown client "${client ?? ""}" (expected claude or codex)`);
+        throw new Error(`unknown client "${client ?? ""}" (expected claude, codex or pi)`);
     return { client, configured: configuredEndpoint(argValue(argv, "--endpoint")) };
 }
 /** Returns the text to print on stdout ("" for nothing); throws on any failure. */
@@ -57,6 +57,12 @@ async function forward(argv) {
     }
     // Every event says where the conversation runs; the host refuses one without it.
     input.machine = machineInfo();
+    // A pi process names itself (--client-pid, its extension passes it): tool calls from it find the session.
+    if (client === "pi") {
+        const pid = parsePid(argValue(argv, "--client-pid"));
+        if (pid !== undefined)
+            input.client_pid = pid;
+    }
     // SessionEnd must finish within Codex's 3 s hook limit (discovery included): a short budget and a single attempt.
     const sessionEnd = stdin.hook_event_name === "SessionEnd";
     const timeoutMs = stdin.hook_event_name === "Stop" ? HOOK_STOP_REQUEST_TIMEOUT_MS : sessionEnd ? SESSION_END_REQUEST_TIMEOUT_MS : HOOK_REQUEST_TIMEOUT_MS;

package/build/cli/install.js

@@ -1,9 +1,10 @@
 /**
- * `n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]` and
- * `n2n-nexus uninstall <claude|codex>`: register the hooks and the MCP server
- * with Claude Code or Codex. Our hook entries are recognised by a command that
+ * `n2n-nexus install <claude|codex|pi> [--endpoint <url>] [--node <path>]` and
+ * `n2n-nexus uninstall <claude|codex|pi>`: register the hooks and the MCP server
+ * with Claude Code, Codex or pi. Our hook entries are recognised by a command that
  * contains both `n2n-nexus` and ` hook <client>`; everything else in the
- * configuration file is kept as it is.
+ * configuration file is kept as it is. pi has no hook configuration: its hooks
+ * are an extension file (pi.ts), which install writes and uninstall removes.
  *
  * For Claude Code, install also writes a marked block into the user's
  * CLAUDE.md that makes direct messages count as the user's own requests
@@ -28,9 +29,11 @@ import { claudeConfigDir, codexHome } from "./client-dirs.js";
 import { entryScript } from "./entry.js";
 import { hookCommand, isOurs, windowsHookCommand } from "./hook-command.js";
 import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
+import { PI_EXTENSION_MARK, piExtensionFile, readPiExtensionFile, renderPiExtension, writePiExtension } from "./pi.js";
 const EVENTS = {
     claude: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"],
-    codex: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PostToolUse", "Stop"]
+    codex: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PostToolUse", "Stop"],
+    pi: []
 };
 class InstallError extends Error {
 }
@@ -155,6 +158,8 @@ function checkNodePath(given) {
     return node;
 }
 export function configFile(client) {
+    if (client === "pi")
+        return piExtensionFile();
     return client === "claude" ? path.join(claudeConfigDir(), "settings.json") : path.join(codexHome(), "hooks.json");
 }
 export function readConfig(file) {
@@ -323,6 +328,30 @@ function mcpRemoveArgs(client) {
         ? ["mcp", "remove", "--scope", "user", MCP_SERVER_NAME]
         : ["mcp", "remove", MCP_SERVER_NAME];
 }
+/**
+ * Write (install) or remove (uninstall) the pi extension that carries the hooks. An extension file that is not
+ * ours is never overwritten or removed. Returns whether an extension of ours was there before.
+ */
+function piExtensionStep(action, command) {
+    const file = piExtensionFile();
+    const text = readPiExtensionFile(file);
+    const ours = text !== undefined && text.startsWith(PI_EXTENSION_MARK);
+    if (text !== undefined && !ours) {
+        if (action === "install")
+            throw new InstallError(`${file} exists and is not written by n2n-nexus; move it aside and run again.`);
+        process.stdout.write(`Left ${file} alone: it is not written by n2n-nexus.\n`);
+        return false;
+    }
+    if (action === "install") {
+        writePiExtension(file, renderPiExtension(command));
+        process.stdout.write(`Wrote the pi extension to ${file}\n`);
+    }
+    else if (ours) {
+        fs.rmSync(file, { force: true });
+        process.stdout.write(`Removed the pi extension from ${file}\n`);
+    }
+    return ours;
+}
 /**
  * `<client> mcp add` for `"<node>" "<npx>" -y n2n-nexus@latest mcp`. PATH starts with `bin` (see npxFor): npx starts
  * the package's bin, `#!/usr/bin/env node` (Unix) or a .cmd shim running `node` (Windows), which looks Node up on
@@ -377,7 +406,7 @@ function removeMcpServer(client, action, hooksRemoved) {
             return;
         if (action === "uninstall" && error.code === "ENOENT") {
             const file = mcpConfigFile(client);
-            const what = client === "claude" ? `the "${MCP_SERVER_NAME}" entry under "mcpServers"` : `the [mcp_servers.${MCP_SERVER_NAME}] table`;
+            const what = client === "codex" ? `the [mcp_servers.${MCP_SERVER_NAME}] table` : `the "${MCP_SERVER_NAME}" entry under "mcpServers"`;
             process.stdout.write(`Skipped "${client} ${removeArgs.join(" ")}": the "${client}" command could not be run (not on PATH, or not runnable without a shell). `
                 + `The MCP server is still registered in ${file}; run that command once ${client} can be run, or delete ${what} from ${file}.\n`);
             return;
@@ -403,22 +432,28 @@ export function runInstall(options) {
         if (action === "install") {
             const probe = spawnClientSync(client, ["--version"], { stdio: "ignore" });
             if (probe.error || probe.status !== 0) {
-                throw new InstallError(`The "${client}" command was not found on PATH; install ${client === "claude" ? "Claude Code" : "Codex"} first.`);
+                throw new InstallError(`The "${client}" command was not found on PATH; install ${CLIENT_NAMES[client]} first.`);
             }
         }
         const node = action === "install" ? (options.node ? checkNodePath(options.node) : stableNodePath()) : undefined;
         const npm = node ? npxFor(node) : undefined;
-        const file = configFile(client);
-        const config = readConfig(file);
-        const removed = removeOurEntries(config, client, file);
-        if (action === "install") {
-            const command = hookCommand(node, entry, client, endpoint);
-            const commandWindows = client === "codex" ? windowsHookCommand(node, entry, client, endpoint) : undefined;
-            addOurEntries(config, client, command, commandWindows);
+        let removed;
+        if (client === "pi") {
+            removed = piExtensionStep(action, node ? { node, entry, endpoint } : undefined);
         }
-        if (action === "install" || removed) {
-            writeConfig(file, config);
-            process.stdout.write(`${action === "install" ? "Wrote hooks to" : "Removed hooks from"} ${file}\n`);
+        else {
+            const file = configFile(client);
+            const config = readConfig(file);
+            removed = removeOurEntries(config, client, file);
+            if (action === "install") {
+                const command = hookCommand(node, entry, client, endpoint);
+                const commandWindows = client === "codex" ? windowsHookCommand(node, entry, client, endpoint) : undefined;
+                addOurEntries(config, client, command, commandWindows);
+            }
+            if (action === "install" || removed) {
+                writeConfig(file, config);
+                process.stdout.write(`${action === "install" ? "Wrote hooks to" : "Removed hooks from"} ${file}\n`);
+            }
         }
         if (client === "claude" && writeInstructions(action === "install")) {
             process.stdout.write(`${action === "install" ? "Wrote the n2n-nexus instructions to" : "Removed the n2n-nexus instructions from"} ${instructionsFile()}\n`);
@@ -440,11 +475,13 @@ export function runInstall(options) {
         return 1;
     }
 }
-/** Parse `<claude|codex> [--endpoint <url>] [--node <path>]` and run. */
+/** The product names the installer's messages use. */
+const CLIENT_NAMES = { claude: "Claude Code", codex: "Codex", pi: "pi" };
+/** Parse `<claude|codex|pi> [--endpoint <url>] [--node <path>]` and run. */
 export async function runInstallCommand(action, argv) {
     const client = argv[0];
     if (!isHookClient(client)) {
-        process.stderr.write(`Usage: n2n-nexus ${action} <claude|codex>${action === "install" ? " [--endpoint <url>] [--node <path>]" : ""}\n`);
+        process.stderr.write(`Usage: n2n-nexus ${action} <claude|codex|pi>${action === "install" ? " [--endpoint <url>] [--node <path>]" : ""}\n`);
         return 1;
     }
     const option = (name, what) => {

package/build/cli/mcp-config.js

@@ -1,17 +1,21 @@
 /**
- * Where Claude Code and Codex keep their MCP server registrations, and how to
- * read the n2n-nexus entry: `~/.claude.json` (user scope) and
- * `$CODEX_HOME/config.toml`. `claude mcp get` is not used for this because it
+ * Where Claude Code, Codex and pi keep their MCP server registrations, and how to
+ * read the n2n-nexus entry: `~/.claude.json` (user scope), `$CODEX_HOME/config.toml`
+ * and pi's `mcp.json`. `claude mcp get` is not used for this because it
  * looks in every scope, not only the user scope that install writes to, and
  * it starts the server for a health check.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { MCP_SERVER_NAME } from "../contract.js";
-import { claudeJsonDir, codexHome } from "./client-dirs.js";
+import { claudeJsonDir, codexHome, piAgentDir } from "./client-dirs.js";
 /** Where the client keeps the MCP server command. */
 export function mcpConfigFile(client) {
-    return client === "claude" ? path.join(claudeJsonDir(), ".claude.json") : path.join(codexHome(), "config.toml");
+    if (client === "claude")
+        return path.join(claudeJsonDir(), ".claude.json");
+    if (client === "pi")
+        return path.join(piAgentDir(), "mcp.json");
+    return path.join(codexHome(), "config.toml");
 }
 /** The MCP server command the client has for n2n-nexus, or undefined when not registered. */
 export function readMcpCommand(client, file) {
@@ -24,7 +28,7 @@ export function readMcpCommand(client, file) {
             return undefined;
         throw error;
     }
-    if (client === "claude") {
+    if (client === "claude" || client === "pi") {
         let parsed;
         try {
             parsed = JSON.parse(text);