pi-mesh is a local CLI and Agent Skill for discovering, inspecting, and messaging multiple Pi coding-agent sessions.

It keeps the normal Pi TUI for interactive work, while giving agents and scripts a small command-line surface for coordination.

Installation

npm install -g @streichsbaer/pi-mesh --ignore-scripts

The package installs the pi-mesh binary and does not require npm install scripts.

Install or refresh the global Agent Skill after installation or upgrade:

pi-mesh setup skill

This always writes ~/.agents/skills/pi-mesh and also writes ~/.claude/skills/pi-mesh when ~/.claude exists. To install into a custom skills root instead, use pi-mesh setup skill --folder <skills-root>.

How it works

• pi-mesh run starts or resumes an interactive Pi TUI session and keeps it live.
• pi-mesh spawn creates a sleeping/headless managed session that wakes when messaged.
• pi-mesh send delivers work to an exact managed session ID; selector-based sends require an explicit broadcast.
• Existing Pi sessions can be inspected read-only; close and attach one before sending to it.

Common use cases

# Check the installed version and refresh the Agent Skill.
pi-mesh version
pi-mesh setup skill

# Discover managed sessions, or explicitly include unmanaged Pi sessions in search.
pi-mesh sessions list
pi-mesh sessions search auth
pi-mesh sessions search auth --include-unmanaged

# Inspect a session.
pi-mesh transcript <session-id-or-path> --last 3
pi-mesh state <session-id-or-path>

# Start a sleeping worker and send it follow-up work.
pi-mesh spawn --name worker-api --folder ./api --label pi-mesh-development --model anthropic/claude-sonnet-4-5 --prompt "Inspect the auth tests"
pi-mesh send <managed-session-id> "Fix the failing auth test" --stream

# Broadcast intentionally to every other matching session.
# When run from a managed session, that current session is automatically excluded.
pi-mesh send --label pi-mesh-development --broadcast --message "Please report status."

# Change model or thinking level for a turn.
pi-mesh send <managed-session-id> "Use a cheaper model for this check" --model claude-haiku-4-5
pi-mesh send <managed-session-id> "Think deeply about this migration" --thinking high

# Start a live coordinator TUI, or attach an existing Pi JSONL session.
pi-mesh run --name coordinator --folder . --label pi-mesh-development
pi-mesh attach /path/to/session.jsonl --name existing-session

Names and labels are not unique. Discover sessions with filters, then use the returned stable session ID for state, transcript, send, and delete operations. Selector-based sends require --broadcast --message <text>. A broadcast issued from a managed session excludes that current session and targets only the other matches; a direct send to the current session is rejected.

Programmatic discovery

The supported package API keeps discovery and exact resolution separate:

import { loadSessionDataForSession, searchSessions } from "@streichsbaer/pi-mesh";

const match = (await searchSessions({ query: "auth" }))[0];
if (!match) throw new Error("No matching Pi session");
const session = await loadSessionDataForSession(match);

Session discovery and reading exports:

• searchSessions
• resolveExactSessionSpec
• loadSessionData
• loadSessionDataForSession

Managed-session discovery exports:

• resolveMesh
• listManagedSessions
• filterManagedSessions
• findManagedSessionById

The corresponding constants and data types are exported explicitly from the package root. loadSessionData does not perform fuzzy search: pass an exact raw session ID or JSONL path. Locks, sockets, registry mutation, Pi runners, and formatting helpers are internal. Operational session control remains a CLI feature.

More docs

• Development
• Release process
• Security

License

MIT