RPC commands

This page lists the commands an RPC client writes to PiG on standard input, with example records and their responses. RPC mode describes how to start the process and frame records.

Supported commands

Unknown command types return success:false.

Prompt

{"id":"prompt-1","type":"prompt","message":"Find the test entry points"}

PiG acknowledges the prompt after extension input handling and model authentication preflight succeed. The response arrives before model events finish:

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

metadata is an optional JSON object:

{"id":"prompt-2","type":"prompt","message":"Review this change","metadata":{"task_id":"task-42"}}

RPC prompt input accepts text and optional images. If the Agent is already running, set streamingBehavior to steer or followUp. PiG rejects a second prompt without this field.

A registered extension command such as /review strict runs immediately through the prompt command. Prompt templates and /skill:<name> expand before model submission.

Abort

{"id":"abort-1","type":"abort"}

PiG cancels the current prompt context and acknowledges the command:

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

State

{"id":"state-1","type":"get_state"}

The response data contains:

{
  "sessionId":"...",
  "sessionFile":"...",
  "sessionName":"...",
  "model":{"id":"gpt-5","provider":"openai"},
  "thinkingLevel":"medium",
  "steeringMode":"all",
  "followUpMode":"one-at-a-time",
  "isStreaming":false,
  "isCompacting":false,
  "autoCompactionEnabled":true,
  "messageCount":5,
  "pendingMessageCount":0
}

sessionFile and sessionName can be absent.

Select a model

{"id":"model-1","type":"set_model","provider":"openai","modelId":"gpt-5"}

A successful response contains the full selected model record.

List available models:

{"id":"models-1","type":"get_available_models"}

The result is a models array of full Pi model records.

Thinking level

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

Accepted values are off, minimal, low, medium, high, xhigh, and max. Model capabilities can clamp the effective level.

Cycle the configured level:

{"type":"cycle_thinking_level"}

The response contains the next level.

Compaction and retry

Start compaction:

{"id":"compact-1","type":"compact","customInstructions":"Keep file names and unresolved errors."}

The response arrives after compaction finishes. It contains summary, firstKeptEntryId, tokensBefore, and estimatedTokensAfter. It can also contain usage and details. A compaction failure returns success:false.

Set automatic compaction:

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

Set automatic retry for the current Session:

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

Steer and follow up

{"type":"steer","message":"Stop and inspect the parser first."}

PiG queues this message after the current tool batch and before the next model call.

{"type":"follow_up","message":"Then update the documentation."}

PiG queues this message after the active turn settles. queue_update events report both queues when a message enters or leaves them.

Clear the queue

{"id":"clear-1","type":"clear_queue"}

PiG removes every queued steering and follow-up message. It writes a queue_update event with both queues empty, and then the response. The response data contains the text of the removed messages:

{"id":"clear-1","type":"response","command":"clear_queue","success":true,"data":{"steering":["Stop and inspect the parser first."],"followUp":["Then update the documentation."]}}

Bash

{"id":"bash-1","type":"bash","command":"go test ./...","excludeFromContext":false}

The final response data contains output, exitCode, cancelled, truncated, and optional fullOutputPath.

Cancel active Bash work:

{"type":"abort_bash"}

Session data

Get current Agent messages:

{"type":"get_messages"}

Get entries after a known entry:

{"type":"get_entries","since":"a1b2c3d4"}

The response contains entries and leafId. An unknown since ID returns an error.

Get the complete tree:

{"type":"get_tree"}

Get the last assistant text:

{"type":"get_last_assistant_text"}

The response data is empty when no assistant text exists.

Set a Session name:

{"id":"name-1","type":"set_session_name","name":"Review authentication"}

PiG writes session_info_changed before the success response.

An extension can also change Session metadata. appendEntry persists a custom entry and then writes entry_appended. setSessionName writes session_info_changed. An empty extension-defined name clears the Session name, and the event omits name.

Session replacement and export

Start a new Session:

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

Switch to an existing Session:

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

PiG keeps the startup project Resources when the target Session uses a different working directory. Direct RPC Bash uses the target working directory. Built-in tools, project settings, context files, prompts, skills, themes, and the system prompt still use the startup project. See D61.

Fork before a user message:

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

The fork response contains the selected user text. clone forks at the active leaf instead:

{"type":"clone"}

Each replacement can return data.cancelled:true when an extension cancels its session_before_switch or session_before_fork event.

Export the current persisted Session:

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

Omit outputPath to use the default export path.

Command catalogue

{"type":"get_commands"}

Each result contains:

• name;
• optional description;
• source, such as extension, prompt, or skill;
• sourceInfo with path, source, scope, origin, and optional baseDir.

Built-in interactive slash commands are not RPC commands.