| name | pi-send |
| description | Send a message to another running pi session via its Unix socket. Use when the user wants to hand off context to another session, continue a conversation elsewhere, or notify another pi instance. |
Pi Send
Send a message to another active pi session using the pi-socket extension. Each pi session exposes a Unix socket at <cwd>/.local/share/pi/socket and a metadata file at <cwd>/.local/share/pi/socket.info.json.
Finding the target session
Sessions always run from a project directory at $WORKSPACE/<owner>/<repo>. The socket info file is at:
cat $WORKSPACE/<owner>/<repo>/.local/share/pi/socket.info.json
Fields: socketPath, cwd, pid, sessionFile, startedAt.
Sending a message
Protocol: newline-delimited JSON over the Unix socket. Send a send_user_message request:
echo '{"type":"send_user_message","message":"your message here"}' | nc -U <socketPath>
Response: {"ok":true,"result":{"accepted":true,"delivery":"immediate"}} on success.
Build the JSON payload safely to handle special characters:
PAYLOAD=$(python3 -c "import json,sys; msg=sys.stdin.read(); print(json.dumps({'type':'send_user_message','message':msg}))" <<< "$MESSAGE")
echo "$PAYLOAD" | nc -U <socketPath>
Other request types
{"type":"ping"} — check if session is alive, returns pong{"type":"get_state"} — returns cwd, idle, sessionName, sessionFile{"type":"abort"} — abort current operation{"type":"shutdown"} — shut down the session
Gotchas
nc must be used, not socat (not available)- The message must be a single JSON line terminated with
\n — nc -U handles this
- If the session is busy,
delivery will be followUp (queued) instead of immediate
- Max message size is 256KB
