pi-mesh

name	pi-mesh
description	Find, list, inspect, message, spawn, attach, and coordinate Pi sessions using pi-mesh. Use when the user asks about available, running, other, or labeled Pi sessions; session transcripts or state; messaging sessions; or coordinating Pi workers. The user does not need to mention pi-mesh explicitly.

Pi Mesh

Use the pi-mesh CLI to discover, inspect, message, spawn, attach, and delete local Pi sessions.

Assume pi-mesh is installed and ready. Do not run version checks before ordinary operations. If the command is unavailable or fails, report that directly rather than attempting package discovery or fallback parsing.

Defaults

• Discovery and inspection are read-only by default. Only send messages, spawn, attach, or delete when the user explicitly requests that action.
• Inspect only managed pi-mesh sessions unless the user explicitly asks for unmanaged, raw, or all Pi sessions.
• Use plain CLI output first. Add --json only when structured processing is necessary.
• Do not use inline Python, jq, or similar parsing when the CLI output answers the question directly.
• Use exact session IDs returned by discovery for subsequent commands. Do not guess from ambiguous names, labels, folders, or free-text queries.

For a simple request such as “sessions with label X”, run only:

pi-mesh sessions list --label <label>

Do not preflight with pi-mesh --version, use unmanaged discovery, or parse the output programmatically.

Help

Use contextual help when command syntax or output is unclear:

pi-mesh --help
pi-mesh sessions --help
pi-mesh sessions list --help
pi-mesh send --help

Mental model

• pi-mesh sessions list reads only the managed-session registry.
• pi-mesh sessions search searches managed sessions and searches recent unmanaged Pi sessions only with --include-unmanaged.
• pi-mesh run starts or resumes a vanilla Pi TUI session and keeps it live until the user exits.
• pi-mesh spawn creates a sleeping/headless managed session by default. It runs when messaged, then exits when idle.
• pi-mesh send sends a prompt to a managed session. A sleeping session wakes, runs the turn, and shuts down again.
• An unmanaged Pi session is read-only until the user closes its original Pi process and explicitly attaches it to pi-mesh.

Discover sessions

List managed sessions with optional exact filters:

pi-mesh sessions list
pi-mesh sessions list --label <label>
pi-mesh sessions list --name <name> --folder <folder>

Expected plain output is concise:

Managed sessions (1)

session-d8da4026d92b · demo-1 · interactive · running
  folder: /path/to/project
  labels: demo-ws

When answering the user, summarize the result count and each session's ID, name, kind, status, folder, and labels. Do not include JSONL paths, socket paths, timestamps, or raw JSON unless requested. Use --verbose when those operational details are needed.

For free-text search, managed sessions remain the default:

pi-mesh sessions search "auth"

Only when the user explicitly requests unmanaged/raw/all Pi sessions:

pi-mesh sessions search "auth" --include-unmanaged

Search output separates managed and unmanaged result counts and returns stable IDs. Choose an exact ID before running a follow-up command.

models list shows Pi-configured models:

pi-mesh models list sonnet --folder <session-folder> --scoped
pi-mesh models list --include-unauthenticated

Use --include-unauthenticated only when the user asks for models beyond configured authentication.

Read state and transcript

Use an exact managed session ID, exact raw Pi session ID, or .jsonl path:

pi-mesh state <session-id-or-path>
pi-mesh transcript <session-id-or-path> --last 3
pi-mesh transcript <session-id-or-path> --last 1 --show-tools

These commands do not accept fuzzy names, labels, folders, or arbitrary queries. If discovery returns multiple matches, report them and ask the user to choose when their intent is unclear.

Send a message

For one session, use its exact managed ID:

pi-mesh send <managed-session-id> "Please inspect the failing tests"
pi-mesh send <managed-session-id> "After you finish, summarize your changes" --delivery follow-up
pi-mesh send <managed-session-id> "Stop and check the logs first" --delivery steer
pi-mesh send <managed-session-id> "Use a cheaper model for this check" --model claude-haiku-4-5

Delivery modes:

• auto: safest default
• prompt: only for idle live sessions; starts a normal prompt
• steer: steer active work when live; for sleeping sessions it behaves like a normal prompt
• follow-up: queue after active work when live; for sleeping sessions it behaves like a normal prompt

Selector-based sends are broadcasts and require both --broadcast and --message:

pi-mesh send --label pi-mesh-development --broadcast --message "Report current status"

When a managed session issues a broadcast, pi-mesh automatically excludes that current session and sends only to the other matches. A direct send targeting the current session is rejected. Never add --broadcast merely to resolve ambiguity. Broadcast only when the user explicitly asks to message every matching session.

Use --model <provider/model>, --provider <name> --model <id>, or a model id/fuzzy match to select a model for spawn, run, attach, or send. Use canonical provider/model when the exact provider matters. --model model:thinking and --thinking off|minimal|low|medium|high|xhigh|max are supported; explicit --thinking wins.

Use --stream only when turn output should be displayed in the current terminal.

Spawn workers

pi-mesh spawn --name worker-api --folder ./api --label pi-mesh-development
pi-mesh spawn --name worker-api --folder ./api --prompt "Investigate the auth test failure" --stream

Spawned workers sleep by default. If --prompt is provided, the initial headless turn runs immediately. Record the returned managed session ID and use it for transcript, state, and send commands.

To create a session and immediately open vanilla Pi TUI:

pi-mesh spawn --name coordinator --folder . --label pi-mesh-development --attach

Run or attach interactive sessions

pi-mesh run --name coordinator --folder . --label pi-mesh-development
pi-mesh run --name coordinator --folder . --label pi-mesh-development --new
pi-mesh attach <raw-session-id-or-jsonl-path> --name old-session

Use unmanaged search to find a raw session ID before attaching. Ask the user to close the original Pi process first. run reuses a matching managed session by name/folder/label unless --new is passed.

Delete managed sessions

Deletion must be explicitly requested and uses an exact managed ID:

pi-mesh sessions delete <managed-session-id>
pi-mesh sessions delete <managed-session-id> --delete-file

Deleting keeps the Pi JSONL file by default. --delete-file requires interactive confirmation. Do not use --force unless the user explicitly asks to bypass that confirmation. Active sessions must be stopped before deletion.

Diagnostics

Only for troubleshooting, release/debugging work, or when the user asks which build is active:

pi-mesh --version
pi-mesh version --json

Coordination pattern

1. List managed sessions with plain output.
2. Search unmanaged sessions only if explicitly requested.
3. Select and retain exact session IDs.
4. Spawn workers only when requested, retaining each returned ID.
5. Send concrete prompts to exact managed IDs.
6. Read state or transcripts by exact ID.
7. Send follow-up prompts as needed.

Safety

Avoid two processes writing to the same Pi JSONL file. A Pi JSONL session may be managed only once. Close an unmanaged session's original Pi process before attaching it. Never guess a target for a write operation, and never broadcast unless explicitly requested.