@d3ara1n/pi-peek-agent

Cross-instance peek for pi — ask another pi instance a question without disturbing its main conversation. Built on @d3ara1n/pi-mesh for discovery and transport.

Adds the peek tool. Discovery, identity, and the socket mesh live in pi-mesh — load pi-mesh alongside this package.

How it works

• Read-after-burn: the peeked instance creates a temporary consult via pi-peek, makes one streaming completion, then disposes its reference and history. Its main agent is never touched. The caller receives a normal tool result that may be saved in its own session; model-provider retention is separate.
• Full context: the large-context utility model receives the complete supported current-branch text, including full saved tool arguments/results. No internal tools, retrieval loop, pagination, or local content budget. Thinking is excluded unless the caller explicitly sets includeThinking: true.
• Independent calls: every request captures a fresh snapshot. There is no remote conversation handle, so include sufficient context when asking a follow-up.
• Progress and limits: plain-text tool updates work in TUI and non-TUI hosts. Final result details include the snapshot time, usage, and stop reason when supplied by the peer. An upstream output limit adds a separate notice alongside the unchanged answer; context overflow is surfaced as an error without automatic compression or retry.
• On the mesh: this package registers an "ask" handler on the pi-mesh transport; a remote peek call routes there and is answered locally. Identity, discovery, and peer listing are pi-mesh's job — use mesh_list to see who's online.

Tool

peek

Ask another instance a question without disturbing its main conversation.

Parameter	Required	Description
question	yes	What you want to find out about that instance's session (e.g. "What are you working on right now?").
includeThinking	no	Include readable thinking saved in the session. Defaults to false; missing/redacted thinking cannot be recovered.
at	no	Target instance name (e.g. "Fox"). Omit to auto-pick the other same-project instance.
sessionId	no	Pin a specific instance by sessionId (use when names collide).

Peer discovery moved to pi-mesh — use mesh_list (provided by pi-mesh) to see who's online.

Installation

pi install npm:@d3ara1n/pi-model-roles
pi install npm:@d3ara1n/pi-peek
pi install npm:@d3ara1n/pi-mesh
pi install npm:@d3ara1n/pi-peek-agent

Or add to ~/.pi/agent/settings.json:

{
  "extensions": [
    "/absolute/path/to/pi-extensions/packages/pi-model-roles",
    "/absolute/path/to/pi-extensions/packages/pi-peek",
    "/absolute/path/to/pi-extensions/packages/pi-mesh",
    "/absolute/path/to/pi-extensions/packages/pi-peek-agent"
  ]
}

Dependencies

• @d3ara1n/pi-mesh — peer discovery + transport
• @d3ara1n/pi-peek — temporary full-context consults

Configuration

Optional, in ~/.pi/agent/settings.json under peek:

{
  "peek": {
    "askTimeoutMs": 120000,
    "timeoutMs": 90000,
    "role": "utility"
  }
}

askTimeoutMs is the caller's transport wait timeout. timeoutMs is the serving instance's independent request deadline, including authentication and streaming. Set the caller's wait timeout longer than the serving instance's investigation timeout, allowing for transport overhead.

Cancelling a caller's request or disconnecting does not currently propagate cancellation to the serving handler through the mesh protocol. Remote work is bounded by its own deadline and is aborted on session shutdown. No mesh protocol changes are required.

See pi-peek configuration for model role and request deadline settings. Discovery/registry/heartbeat configuration belongs to pi-mesh's mesh block.

Naming

Names are managed by pi-mesh — see the pi-mesh README. Each instance gets a stable name derived from its session id; override at startup with PI_MESH_NAME, or rename at runtime with /mesh:rename.

License

MIT