RPC mode: subprocess integration protocol

RPC mode lets you drive Pi’s coding agent from any programming language or environment by communicating over stdin/stdout using a JSON protocol. It is the right choice when you need process isolation or are building a non-Node.js client.

If you’re building a Node.js application, use AgentSession directly from the SDK instead of spawning a subprocess. See Pi SDK for the type-safe API.

Starting RPC mode

pi --mode rpc

Common options:

Option	Description
`--provider <name>`	LLM provider (`anthropic`, `openai`, `google`, etc.)
`--model <pattern>`	Model pattern or ID, supports `provider/id` and optional `:<thinking>`
`--no-session`	Disable session persistence
`--session-dir <path>`	Custom session storage directory

For a stateless session useful during development or testing:

pi --mode rpc --no-session

Protocol overview

Commands: JSON objects sent to stdin, one per line
Responses: JSON objects with type: "response" indicating success or failure
Events: Agent events streamed to stdout as JSON lines, asynchronously during operation

All commands accept an optional id field. When provided, the matching response includes the same id for request/response correlation.

Framing

RPC mode uses strict JSONL semantics. Records are delimited by LF (\n) only.

Do not use Node.js readline or any reader that splits on Unicode line separators (U+2028, U+2029). Those characters are valid inside JSON strings. Split on \n only, and strip a trailing \r if present.

Commands

Prompting

prompt

Send a user prompt to the agent. The response is emitted once the prompt is accepted, queued, or handled. Events continue streaming asynchronously after acceptance.

{"id": "req-1", "type": "prompt", "message": "Hello, world!"}

With images:

{
  "type": "prompt",
  "message": "What's in this image?",
  "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]
}

If the agent is already streaming, specify streamingBehavior to queue the message:

{"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"}

"steer": Delivered after the current assistant turn finishes its tool calls, before the next LLM call.
"followUp": Delivered only when the agent fully stops.

If the agent is streaming and streamingBehavior is omitted, the command returns an error.Response:

{"id": "req-1", "type": "response", "command": "prompt", "success": true}

success: true means the prompt was accepted, queued, or handled. success: false means it was rejected before acceptance. Failures after acceptance appear in the normal event stream.

steer

Queue a steering message while the agent is running. Delivered after the current assistant turn finishes its tool calls, before the next LLM call. Skill commands and prompt templates are expanded. Extension commands are not allowed here — use prompt instead.

{"type": "steer", "message": "Stop and do this instead"}

With images:

{"type": "steer", "message": "Look at this instead", "images": [...]}

Response:

{"type": "response", "command": "steer", "success": true}

follow_up

Queue a follow-up message to be delivered only when the agent fully stops (no more tool calls or steering messages). Skill commands and prompt templates are expanded. Extension commands are not allowed — use prompt instead.

{"type": "follow_up", "message": "After you're done, also do this"}

Response:

{"type": "response", "command": "follow_up", "success": true}

abort

Abort the current agent operation.

{"type": "abort"}

Response:

{"type": "response", "command": "abort", "success": true}

new_session

Start a fresh session. Can be cancelled by a session_before_switch extension handler.

{"type": "new_session"}

With optional parent session tracking:

{"type": "new_session", "parentSession": "/path/to/parent.jsonl"}

Response:

{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": false}}

State

get_state

Get current session state.

{"type": "get_state"}

Response:

{
  "type": "response",
  "command": "get_state",
  "success": true,
  "data": {
    "model": {...},
    "thinkingLevel": "medium",
    "isStreaming": false,
    "isCompacting": false,
    "steeringMode": "all",
    "followUpMode": "one-at-a-time",
    "sessionFile": "/path/to/session.jsonl",
    "sessionId": "abc123",
    "sessionName": "my-feature-work",
    "autoCompactionEnabled": true,
    "messageCount": 5,
    "pendingMessageCount": 0
  }
}

sessionName is omitted when not set via set_session_name.

get_messages

Get all messages in the current conversation.

{"type": "get_messages"}

Response:

{
  "type": "response",
  "command": "get_messages",
  "success": true,
  "data": {"messages": [...]}
}

Model

set_model

Switch to a specific model.

{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}

Response includes the full model object:

{"type": "response", "command": "set_model", "success": true, "data": {...}}

cycle_model

Cycle to the next available model. Returns null data when only one model is available.

{"type": "cycle_model"}

Response:

{
  "type": "response",
  "command": "cycle_model",
  "success": true,
  "data": {"model": {...}, "thinkingLevel": "medium", "isScoped": false}
}

get_available_models

List all configured models with valid API keys.

{"type": "get_available_models"}

Response:

{"type": "response", "command": "get_available_models", "success": true, "data": {"models": [...]}}

Thinking

set_thinking_level

Set the reasoning level for models that support it.Levels: "off", "minimal", "low", "medium", "high", "xhigh"

{"type": "set_thinking_level", "level": "high"}

"xhigh" is only supported by OpenAI codex-max models.

Response:

{"type": "response", "command": "set_thinking_level", "success": true}

cycle_thinking_level

Cycle through available thinking levels.

{"type": "cycle_thinking_level"}

Response:

{"type": "response", "command": "cycle_thinking_level", "success": true, "data": {"level": "high"}}

Returns null data when the model doesn’t support thinking.

Queue modes

set_steering_mode

Control how steering messages from steer are delivered.

{"type": "set_steering_mode", "mode": "one-at-a-time"}

Modes:

"all": Deliver all queued steering messages after the current turn
"one-at-a-time": Deliver one per completed assistant turn (default)

Response:

{"type": "response", "command": "set_steering_mode", "success": true}

set_follow_up_mode

Control how follow-up messages from follow_up are delivered.

{"type": "set_follow_up_mode", "mode": "one-at-a-time"}

Modes:

"all": Deliver all follow-up messages when agent finishes
"one-at-a-time": Deliver one per agent completion (default)

Response:

{"type": "response", "command": "set_follow_up_mode", "success": true}

Compaction

compact

Manually compact conversation context to reduce token usage.

{"type": "compact"}

With custom instructions:

{"type": "compact", "customInstructions": "Focus on code changes"}

Response:

{
  "type": "response",
  "command": "compact",
  "success": true,
  "data": {
    "summary": "Summary of conversation...",
    "firstKeptEntryId": "abc123",
    "tokensBefore": 150000,
    "details": {}
  }
}

set_auto_compaction

Enable or disable automatic compaction when context is nearly full.

{"type": "set_auto_compaction", "enabled": true}

Response:

{"type": "response", "command": "set_auto_compaction", "success": true}

Retry

set_auto_retry

Enable or disable automatic retry on transient errors (overloaded, rate limit, 5xx).

{"type": "set_auto_retry", "enabled": true}

Response:

{"type": "response", "command": "set_auto_retry", "success": true}

abort_retry

Abort an in-progress retry — cancels the delay and stops retrying.

{"type": "abort_retry"}

Response:

{"type": "response", "command": "abort_retry", "success": true}

Bash

bash

Execute a shell command and add its output to the conversation context.

{"type": "bash", "command": "ls -la"}

Response:

{
  "type": "response",
  "command": "bash",
  "success": true,
  "data": {
    "output": "total 48\ndrwxr-xr-x ...",
    "exitCode": 0,
    "cancelled": false,
    "truncated": false
  }
}

When output is truncated, fullOutputPath is included in the response data.How bash output reaches the LLM: The bash command runs immediately and its result is stored as a BashExecutionMessage. On the next prompt command, all pending bash results are converted to user messages and sent to the LLM. Multiple bash commands can be queued before a prompt; all outputs are included.

abort_bash

Abort a currently running bash command.

{"type": "abort_bash"}

Response:

{"type": "response", "command": "abort_bash", "success": true}

Session

get_session_stats

Get token usage, cost statistics, and current context window usage.

{"type": "get_session_stats"}

Response:

{
  "type": "response",
  "command": "get_session_stats",
  "success": true,
  "data": {
    "sessionFile": "/path/to/session.jsonl",
    "sessionId": "abc123",
    "userMessages": 5,
    "assistantMessages": 5,
    "toolCalls": 12,
    "toolResults": 12,
    "totalMessages": 22,
    "tokens": {
      "input": 50000,
      "output": 10000,
      "cacheRead": 40000,
      "cacheWrite": 5000,
      "total": 105000
    },
    "cost": 0.45,
    "contextUsage": {
      "tokens": 60000,
      "contextWindow": 200000,
      "percent": 30
    }
  }
}

contextUsage is omitted when no model is available. contextUsage.tokens and contextUsage.percent are null immediately after compaction until the next fresh assistant response.

switch_session

Load a different session file. Can be cancelled by a session_before_switch extension handler.

{"type": "switch_session", "sessionPath": "/path/to/session.jsonl"}

Response:

{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": false}}

fork

Create a fork from a previous user message on the active branch. Returns the text of the message being forked from.

{"type": "fork", "entryId": "abc123"}

Response:

{
  "type": "response",
  "command": "fork",
  "success": true,
  "data": {"text": "The original prompt text...", "cancelled": false}
}

clone

Duplicate the current active branch into a new session at the current position.

{"type": "clone"}

Response:

{"type": "response", "command": "clone", "success": true, "data": {"cancelled": false}}

get_fork_messages

Get user messages available for forking.

{"type": "get_fork_messages"}

Response:

{
  "type": "response",
  "command": "get_fork_messages",
  "success": true,
  "data": {
    "messages": [
      {"entryId": "abc123", "text": "First prompt..."},
      {"entryId": "def456", "text": "Second prompt..."}
    ]
  }
}

get_last_assistant_text

Get the text content of the last assistant message. Returns {"text": null} when no assistant messages exist.

{"type": "get_last_assistant_text"}

Response:

{"type": "response", "command": "get_last_assistant_text", "success": true, "data": {"text": "..."}}

set_session_name

Set a display name for the current session. Appears in session listings and get_state.

{"type": "set_session_name", "name": "my-feature-work"}

Response:

{"type": "response", "command": "set_session_name", "success": true}

export_html

Export the session to an HTML file.

{"type": "export_html"}

With a custom output path:

{"type": "export_html", "outputPath": "/tmp/session.html"}

Response:

{"type": "response", "command": "export_html", "success": true, "data": {"path": "/tmp/session.html"}}

Commands

get_commands

Get available commands: extension commands, prompt templates, and skills. These can be invoked via prompt by prefixing with /.

{"type": "get_commands"}

Response:

{
  "type": "response",
  "command": "get_commands",
  "success": true,
  "data": {
    "commands": [
      {
        "name": "session-name",
        "description": "Set or clear session name",
        "source": "extension",
        "path": "/home/user/.pi/agent/extensions/session.ts"
      },
      {
        "name": "fix-tests",
        "description": "Fix failing tests",
        "source": "prompt",
        "location": "project",
        "path": "/home/user/project/.pi/agent/prompts/fix-tests.md"
      },
      {
        "name": "skill:brave-search",
        "description": "Web search via Brave API",
        "source": "skill",
        "location": "user",
        "path": "/home/user/.pi/agent/skills/brave-search/SKILL.md"
      }
    ]
  }
}

source values: "extension", "prompt", "skill". location values: "user", "project", "path". Built-in TUI commands like /settings are not included.

Events

Events stream to stdout as JSON lines during agent operation. Events do not include an id field — only responses do.

Event	Description
`agent_start`	Agent begins processing
`agent_end`	Agent completes; includes all generated messages
`turn_start`	New turn begins
`turn_end`	Turn completes; includes assistant message and tool results
`message_start`	Message begins
`message_update`	Streaming update (text, thinking, or toolcall deltas)
`message_end`	Message completes
`tool_execution_start`	Tool begins execution
`tool_execution_update`	Tool execution progress (streaming output)
`tool_execution_end`	Tool completes
`queue_update`	Pending steering/follow-up queue changed
`compaction_start`	Compaction begins
`compaction_end`	Compaction completes
`auto_retry_start`	Auto-retry begins after a transient error
`auto_retry_end`	Auto-retry completes (success or final failure)
`extension_error`	An extension threw an error

message_update streaming

message_update events carry a message (the partial assistant message) and an assistantMessageEvent delta:

{
  "type": "message_update",
  "message": {...},
  "assistantMessageEvent": {
    "type": "text_delta",
    "contentIndex": 0,
    "delta": "Hello ",
    "partial": {...}
  }
}

Example stream for a text response:

{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0,"partial":{...}}}
{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello","partial":{...}}}
{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world","partial":{...}}}
{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world","partial":{...}}}

tool_execution events

Use toolCallId to correlate start, update, and end events. The partialResult in tool_execution_update contains accumulated output so far — replace your display on each update rather than appending.

{"type": "tool_execution_start", "toolCallId": "call_abc123", "toolName": "bash", "args": {"command": "ls -la"}}
{"type": "tool_execution_update", "toolCallId": "call_abc123", "toolName": "bash", "args": {"command": "ls -la"}, "partialResult": {"content": [{"type": "text", "text": "partial output..."}], "details": {}}}
{"type": "tool_execution_end", "toolCallId": "call_abc123", "toolName": "bash", "result": {"content": [{"type": "text", "text": "total 48\n..."}], "details": {}}, "isError": false}

compaction_end

{
  "type": "compaction_end",
  "reason": "threshold",
  "result": {
    "summary": "...",
    "firstKeptEntryId": "abc123",
    "tokensBefore": 150000,
    "details": {}
  },
  "aborted": false,
  "willRetry": false
}

reason is "manual", "threshold", or "overflow". When reason is "overflow" and compaction succeeds, willRetry is true and the agent automatically retries the prompt.

Extension UI sub-protocol

Extensions can request user interaction in RPC mode via a request/response sub-protocol layered on top of the base command/event flow. Dialog methods (select, confirm, input, editor) emit an extension_ui_request on stdout and block until the client sends back an extension_ui_response with the matching id. If the request includes a timeout field, the agent auto-resolves with a default value when it expires — the client does not need to track timeouts. Fire-and-forget methods (notify, setStatus, setWidget, setTitle, set_editor_text) emit an extension_ui_request on stdout but expect no response.

Requests (stdout)

select

{
  "type": "extension_ui_request",
  "id": "uuid-1",
  "method": "select",
  "title": "Allow dangerous command?",
  "options": ["Allow", "Block"],
  "timeout": 10000
}

Expected response: extension_ui_response with value (selected option string) or cancelled: true.

confirm

{
  "type": "extension_ui_request",
  "id": "uuid-2",
  "method": "confirm",
  "title": "Clear session?",
  "message": "All messages will be lost.",
  "timeout": 5000
}

Expected response: extension_ui_response with confirmed: true/false or cancelled: true.

input

{
  "type": "extension_ui_request",
  "id": "uuid-3",
  "method": "input",
  "title": "Enter a value",
  "placeholder": "type something..."
}

Expected response: extension_ui_response with value (entered text) or cancelled: true.

editor

{
  "type": "extension_ui_request",
  "id": "uuid-4",
  "method": "editor",
  "title": "Edit some text",
  "prefill": "Line 1\nLine 2\nLine 3"
}

Expected response: extension_ui_response with value (edited text) or cancelled: true.

notify (fire-and-forget)

{
  "type": "extension_ui_request",
  "id": "uuid-5",
  "method": "notify",
  "message": "Command blocked by user",
  "notifyType": "warning"
}

notifyType is "info", "warning", or "error". Defaults to "info".

setStatus (fire-and-forget)

Set or clear a status entry. Omit or set statusText to undefined to clear.

{
  "type": "extension_ui_request",
  "id": "uuid-6",
  "method": "setStatus",
  "statusKey": "my-ext",
  "statusText": "Turn 3 running..."
}

setWidget (fire-and-forget)

Set or clear a widget displayed above or below the editor. Only string arrays are supported in RPC mode.

{
  "type": "extension_ui_request",
  "id": "uuid-7",
  "method": "setWidget",
  "widgetKey": "my-ext",
  "widgetLines": ["--- My Widget ---", "Line 1", "Line 2"],
  "widgetPlacement": "aboveEditor"
}

widgetPlacement is "aboveEditor" (default) or "belowEditor".

setTitle (fire-and-forget)

{
  "type": "extension_ui_request",
  "id": "uuid-8",
  "method": "setTitle",
  "title": "pi - my project"
}

set_editor_text (fire-and-forget)

{
  "type": "extension_ui_request",
  "id": "uuid-9",
  "method": "set_editor_text",
  "text": "prefilled text for the user"
}

Responses (stdin)

Send responses only for dialog methods. The id must match the request.

{"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}

{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}

To dismiss any dialog:

{"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}

Error handling

Failed commands return success: false:

{
  "type": "response",
  "command": "set_model",
  "success": false,
  "error": "Model not found: invalid/model"
}

Parse errors:

{
  "type": "response",
  "command": "parse",
  "success": false,
  "error": "Failed to parse command: Unexpected token..."
}

Client examples

Python
Node.js

import subprocess
import json

proc = subprocess.Popen(
    ["pi", "--mode", "rpc", "--no-session"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True
)

def send(cmd):
    proc.stdin.write(json.dumps(cmd) + "\n")
    proc.stdin.flush()

def read_events():
    for line in proc.stdout:
        yield json.loads(line)

send({"type": "prompt", "message": "Hello!"})

for event in read_events():
    if event.get("type") == "message_update":
        delta = event.get("assistantMessageEvent", {})
        if delta.get("type") == "text_delta":
            print(delta["delta"], end="", flush=True)
    if event.get("type") == "agent_end":
        print()
        break

This example uses StringDecoder and manual buffer splitting on \n to comply with the framing rules.

const { spawn } = require("child_process");
const { StringDecoder } = require("string_decoder");

const agent = spawn("pi", ["--mode", "rpc", "--no-session"]);

function attachJsonlReader(stream, onLine) {
  const decoder = new StringDecoder("utf8");
  let buffer = "";

  stream.on("data", (chunk) => {
    buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);

    while (true) {
      const newlineIndex = buffer.indexOf("\n");
      if (newlineIndex === -1) break;

      let line = buffer.slice(0, newlineIndex);
      buffer = buffer.slice(newlineIndex + 1);
      if (line.endsWith("\r")) line = line.slice(0, -1);
      onLine(line);
    }
  });

  stream.on("end", () => {
    buffer += decoder.end();
    if (buffer.length > 0) {
      onLine(buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer);
    }
  });
}

attachJsonlReader(agent.stdout, (line) => {
  const event = JSON.parse(line);
  if (event.type === "message_update") {
    const { assistantMessageEvent } = event;
    if (assistantMessageEvent.type === "text_delta") {
      process.stdout.write(assistantMessageEvent.delta);
    }
  }
});

agent.stdin.write(JSON.stringify({ type: "prompt", message: "Hello" }) + "\n");

process.on("SIGINT", () => {
  agent.stdin.write(JSON.stringify({ type: "abort" }) + "\n");
});

RPC vs SDK

Use RPC mode when

Integrating from Python, Go, Rust, or another language
You want process isolation between your app and the agent
You’re building a language-agnostic client

Use the SDK when

You’re in a Node.js process and want type safety
You need direct access to agent state and messages
You want to customize tools or extensions programmatically

See Pi SDK for the Node.js API.

Get Started

Using Pi

Customization

Programmatic Usage

RPC mode: subprocess integration protocol

Starting RPC mode

Protocol overview

Framing

Commands

Prompting

State

Model

Thinking

Queue modes

Compaction

Retry

Bash

Session

Commands

get_commands

Events

message_update streaming

tool_execution events

compaction_end

Extension UI sub-protocol

Requests (stdout)

Responses (stdin)

Error handling

Client examples

RPC vs SDK

Use RPC mode when

Use the SDK when

Build docs developers (and LLMs) love

Get Started

Using Pi

Customization

Programmatic Usage

Documentation Index

​Starting RPC mode

​Protocol overview

​Framing

​Commands

​Prompting

​State

​Model

​Thinking

​Queue modes

​Compaction

​Retry

​Bash

​Session

​Commands

​get_commands

​Events

​message_update streaming

​tool_execution events

​compaction_end

​Extension UI sub-protocol

​Requests (stdout)

​Responses (stdin)

​Error handling

​Client examples

​RPC vs SDK

Use RPC mode when

Use the SDK when

Build docs developers (and LLMs) love

Starting RPC mode

Protocol overview

Framing

Commands

Prompting

State

Model

Thinking

Queue modes

Compaction

Retry

Bash

Session

Commands

get_commands

Events

message_update streaming

tool_execution events

compaction_end

Extension UI sub-protocol

Requests (stdout)

Responses (stdin)

Error handling

Client examples

RPC vs SDK