Requires Paseo 0.9.1 or newer in the 0.9 line, Node.js 22 or newer, and a paseo CLI on the daemon host's PATH that connects to the same daemon as the agent. If the daemon uses a nondefault host or home, set PASEO_HOST or PASEO_HOME in the daemon's environment so the injected MCP process uses the same target.
From npm:
\npaseo plugin add npm:paseo-peer-agents@0.1.1\nFrom a local checkout:
\ncd peer-agents\nnpm ci\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/paseo-plugins/peer-agents\nReload an existing agent or start a new one after installation. It can call list_peer_projects, then pass the chosen projectId and task prompt to create_peer_agent. Omit provider and model to use the caller's provider and model; set either field to override it. For a separate checkout, specify isolation: \"worktree\" and optionally a branch name and base ref. With isolation: \"local\", the new workspace has its own Paseo identity but shares the selected project's directory.
The creator receives the peer's agent ID from the tool. The peer receives the creator's ID in its first prompt, and both agents receive send_peer_message. No human needs to detach or copy IDs.
If agent launch fails after workspace creation, the tool checks for an agent tagged with that workspace ID. It archives the empty workspace; if an agent may have started or the check fails, it keeps the workspace and reports its ID for inspection.
","readmeText":"# Peer agents\n\nPeer agents gives Paseo-managed agents three MCP tools:\n\n- `list_peer_projects` lists the registered projects and their IDs.\n- `create_peer_agent` creates a new workspace in a selected project and starts an **independent, top-level agent** there. It returns the new agent ID and puts the creator's ID in the new agent's first prompt. The creator's chat shows a pending card while creation runs, then a card with the task, project name, and a link to the new agent. The new agent's chat shows a task card with a link back to the creator, hiding the tool instructions. By default, it uses the calling agent's provider and effective model.\n- `send_peer_message` sends a prompt to an agent ID on the same Paseo host, including a peer in another workspace. Paseo's chat renders it as a **Peer agent** card showing the message and a link to the sender.\n\nThe creation, task, and message cards render Markdown in their text, including headings, lists, code, links, tables, and images.\n\n\n\n\nThe plugin injects its tools into new Claude, Codex, and OpenCode sessions and preapproves those tools through Paseo's tool policy so agents can use them without a human confirmation. Paseo 0.9.1 cannot preapprove exact MCP tools for Pi, so the plugin leaves Pi sessions alone. It does not need Paseo's global `injectIntoAgents` switch. The agent provider must accept stdio MCP servers. Existing sessions must be reloaded to receive the tools. On Linux, the tools also recover the Paseo agent ID from their provider parent process when a provider such as Codex strips environment variables from MCP children.\n\n## Install\n\nRequires Paseo 0.9.1 or newer in the 0.9 line, Node.js 22 or newer, and a `paseo` CLI on the daemon host's `PATH` that connects to the same daemon as the agent. If the daemon uses a nondefault host or home, set `PASEO_HOST` or `PASEO_HOME` in the daemon's environment so the injected MCP process uses the same target.\n\nFrom npm:\n\n```sh\npaseo plugin add npm:paseo-peer-agents@0.1.1\n```\n\nFrom a local checkout:\n\n```sh\ncd peer-agents\nnpm ci\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/paseo-plugins/peer-agents\n```\n\nReload an existing agent or start a new one after installation. It can call `list_peer_projects`, then pass the chosen `projectId` and task prompt to `create_peer_agent`. Omit `provider` and `model` to use the caller's provider and model; set either field to override it. For a separate checkout, specify `isolation: \"worktree\"` and optionally a branch name and base ref. With `isolation: \"local\"`, the new workspace has its own Paseo identity but shares the selected project's directory.\n\nThe creator receives the peer's agent ID from the tool. The peer receives the creator's ID in its first prompt, and both agents receive `send_peer_message`. No human needs to detach or copy IDs.\n\nIf agent launch fails after workspace creation, the tool checks for an agent tagged with that workspace ID. It archives the empty workspace; if an agent may have started or the check fails, it keeps the workspace and reports its ID for inspection.\n\n## How it works\n\nPaseo normally records an agent-launched session as a subagent, even when it is placed in another workspace. `create_peer_agent` calls `paseo workspace create --project