@d3ara1n/pi-peek-agent

Cross-instance peek for pi — UDS mesh + peer discovery + LLM tools (peek, peek_list) for agent-to-agent coordination

Packages

Package details

extension

Install @d3ara1n/pi-peek-agent from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@d3ara1n/pi-peek-agent
Package
@d3ara1n/pi-peek-agent
Version
0.4.0
Published
Jul 22, 2026
Downloads
1,330/mo · 204/wk
Author
d3ara1n
License
MIT
Types
extension
Size
454.2 KB
Dependencies
1 dependency · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ],
  "image": "https://raw.githubusercontent.com/d3ara1n/pi-extensions/main/packages/pi-peek-agent/preview.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@d3ara1n/pi-peek-agent

Cross-instance peek for pi — let one pi instance glance at, or ask a question to, another instance without disturbing it.

Adds two tools for the main agent (peek_list, peek) and runs a lightweight Unix domain socket mesh so instances can discover and consult each other.

How it works

  • Discovery: each instance writes a tiny PID-file marker to ~/.pi/peek/registry/. Liveness is verified by kill(pid, 0) + a socket connect probe — no heartbeat drift, no stale leftovers (the kernel reclaims the socket fd on exit, including SIGKILL/crash).
  • Transport: Unix domain sockets via node:net (zero runtime dependencies). The connection is bidirectional, so the answer streams token-by-token.
  • Read-after-burn: the peeked instance's main agent is never touched. The answer comes from its side utility model via the shared pi-peek consult core.

Tools

peek_list

List other pi instances online, grouped by project. Peers appear only if they have pi-peek-agent loaded.

peek

Ask another instance a question without disturbing its main conversation.

Parameter Required Description
question yes The question to ask.
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).

Installation

pi install npm:@d3ara1n/pi-model-roles
pi install npm:@d3ara1n/pi-peek
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-peek-agent"
  ]
}

Dependencies

Configuration

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

{
  "peek": {
    "registryDir": "~/.pi/peek/registry",
    "heartbeatMs": 15000,
    "askTimeoutMs": 120000,
    "role": "utility"
  }
}

registryDir accepts a leading ~. heartbeatMs and askTimeoutMs must be positive finite numbers; invalid values fall back to their defaults.

Naming

Each instance gets a stable display name shown in peek_list. The name is derived deterministically from the session id (a hash into an adjective+noun pool) — so the same session always gets the same name across /reload, restarts, even across machines. Switching sessions (resume / fork / new) yields a different name.

Set it explicitly to override:

PI_PEEK_NAME=Fox pi

Otherwise the derived name (e.g. QuietBrook) is used. Name collisions across sessions are disambiguated by peek({sessionId}).

License

MIT