# Pi Rpc Sdk

> Pi headless RPC JSONL over stdin/stdout, strict LF framing, --mode json event streaming, and Node SDK alternatives (AgentSession). Use when integrating pi --mode rpc, pi --mode json, writing a client that speaks the protocol, reading JSON event streams, or choosing RPC vs in-process SDK. Use for "pi rpc client", "JSONL framing", "readline rpc", "--mode json", "json events", "embed pi without subprocess", "createAgentSession", "AgentSessionRuntime", "ModelRegistry", "embed pi", "SDK factory", even if the user only pasted JSON lines.

- Skill: `romiluz13/pi-rpc-sdk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add romiluz13/pi-rpc-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/romiluz13/pi-rpc-sdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: romiluz13 (https://skillmd.com/u/romiluz13)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/romiluz13/pi-rpc-sdk

---


# Pi RPC and SDK integration

## Grounding

1. `pi-mono/packages/coding-agent/docs/rpc.md` — **Framing** section (LF-only record delimiter; `readline` incompatibility with U+2028/U+2029).
2. `pi-mono/packages/coding-agent/docs/sdk.md` — programmatic session patterns plus `createAgentSession`, `AgentSession`, `createAgentSessionRuntime`, `ModelRegistry.create()`, `AuthStorage.create()`, and `SessionManager.inMemory()`.
3. `pi-mono/packages/coding-agent/docs/json.md` — `--mode json` event stream: session header, `agent_*`/`turn_*`/`message_*`/`tool_execution_*` events, `jq` filtering examples.
4. `pi-mono/packages/coding-agent/src/modes/rpc/rpc-client.ts` — reference TypeScript client mentioned from `rpc.md` intro when applicable.
5. `pi-mono/packages/coding-agent/src/core/agent-session.ts` — API surface for in-process embedding (per `rpc.md` note to TypeScript users).

## Invariants

- Framing rules are normative text in `pi-mono/packages/coding-agent/docs/rpc.md`; quote or paraphrase strictly from that file when advising client implementers.
- Skill commands and prompt templates are expanded for RPC prompts per `rpc.md` **Input expansion** bullet under `prompt` command.
- `--mode json` is read-only observation (stdout events); `--mode rpc` is bidirectional control (stdin commands + stdout responses). Different use cases, same framing caveats for U+2028/U+2029.
- For TypeScript/Node embedding, `createAgentSession()` is the primary factory; it requires `sessionManager`, `authStorage`, and `modelRegistry`. For advanced multi-session hosting, use `createAgentSessionRuntime()` which returns `AgentSessionRuntime` with lower-level access to `agent`, `sessionManager`, `settingsManager`, `modelRegistry`, `extensions`, `bashExecutor`, `resourceLoader` — `pi-mono/packages/coding-agent/docs/sdk.md`.

## Workflows

- **Choose integration**: If user is on Node/TS, point to `rpc.md` recommendation to prefer `AgentSession` vs subprocess; cite the file’s opening **Note for Node.js/TypeScript users**.
- **Debug framing**: Re-read **Framing** section; do not suggest generic line readers as compliant.
- **JSON event stream**: For read-only observation of agent activity, point to `json.md` (`--mode json`); for bidirectional control, point to `rpc.md` (`--mode rpc`).
- **In-process embedding**: For TypeScript/Node users who don't need subprocess isolation, prefer `createAgentSession()` over `--mode rpc`. Import from `@mariozechner/pi-coding-agent`. See `pi-mono/packages/coding-agent/docs/sdk.md` and `pi-mono/packages/coding-agent/examples/sdk/`.

## Anti-patterns

- Do not describe delimiter behavior contradicting `rpc.md` (only `\n` as record delimiter; optional `\r` strip on input).