Headless Pi — SDK, RPC & JSON Modes

Lesson 8: Headless Pi — SDK, RPC & JSON Modes

Pi isn't only an interactive TUI. The same engine runs non-interactive: one-shot prompts, a JSON event stream for tooling, an RPC protocol for embedding, and a TypeScript SDK for building your own agent surfaces on top of pi.

One-shot prompts

pi -p "Summarize this repo's architecture"
pi --name "CI audit" -p "Review this build failure"

# project trust in non-interactive runs:
pi -p "..." --approve        # trust project resources for this run
pi -p "..." --no-approve     # ignore them

Non-interactive modes (-p, --mode json, --mode rpc) never show the trust prompt — they fall back to defaultProjectTrust (or your explicit --approve/--no-approve).

JSON event stream mode

--mode json emits structured events (messages, tool calls, results, notifications) as JSON lines on stdout — the standard way to drive pi from scripts, CI, or a custom frontend. --mode rpc is the richer protocol for interactive embedding (e.g. building a custom editor UI around pi). Both are documented with full event schemas.

The SDK

The @earendil-works/pi-coding-agent npm package isn't just the CLI — it exports the types and session machinery extensions use (ExtensionAPI, ExtensionContext, session types, the SessionManager API). That's the same library your own tooling can import. Extensions can also shell out with pi.exec() and register whole providers at runtime.

Sessions as data

Every session is a portable JSONL file with a documented format — export with /export, resume with /import, or /share to a private gist with a shareable HTML link. The tree structure with id/parentId is exactly what makes forking and branch summarization possible.

Further Reading

• SDK — programmatic usage
• RPC Mode
• JSON Event Stream Mode
• Session Format — JSONL reference