This reference lists commands accepted on stdin in RPC mode. Each command and response is one JSON object. Shared message values use the message types.

Send a user prompt to the agent. The command response is emitted after 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"}]}

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

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

• "steer": Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
• "followUp": Wait until the agent finishes. Message is delivered only when agent stops.

If the agent is streaming and no streamingBehavior is specified, the command returns an error.

Extension commands: If the message is an extension command (e.g., /mycommand), it executes immediately even during streaming. Extension commands manage their own LLM interaction via $pig->sendMessage().

Input expansion: Skill commands (/skill:name) and prompt templates (/template) are expanded before sending/queueing.

Response:

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

data.disposition is "handled" if an extension command or input handler consumed the prompt, "queued" if pig queued it during a run, or "started" if pig accepted it to start a run. This describes the submitted prompt, not independent work started by an extension or a guarantee of completion.

success: true means the prompt was accepted, queued, or handled immediately. success: false means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second response for the same request id.

The images field is optional. Each image uses ImageContent format: {"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}.

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

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

With images:

{"type": "steer", "message": "Look at this instead", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}

The images field is optional. Each image uses ImageContent format (same as prompt).

Response:

{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}

data.disposition is "handled" if an input handler consumed this steer, or "queued" if pig queued it (including after a handler transformed it). It does not guarantee this message remains queued.

See set_steering_mode for controlling how steering messages are processed.

Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has 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"}

With images:

{"type": "follow_up", "message": "Also check this image", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}

The images field is optional. Each image uses ImageContent format (same as prompt).

Response:

{"type": "response", "command": "follow_up", "success": true, "data": {"disposition": "queued"}}

data.disposition has the same "handled" or "queued" meaning as for steer, applied to this follow-up.

See set_follow_up_mode for controlling how follow-up messages are processed.

Abort the current operation and wait for the session to become idle before responding.

{"type": "abort"}

Response:

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

Remove queued steering and follow-up messages and return their text.

{"type": "clear_queue"}

Response:

{
  "type": "response",
  "command": "clear_queue",
  "success": true,
  "data": {
    "steering": ["Change direction"],
    "followUp": ["Summarize when finished"]
  }
}

To implement interactive Esc behavior, send clear_queue before abort, then restore the returned text in the client editor. abort continues queued messages when they remain in the session.

Start a fresh session. Can be canceled by a session_before_switch extension event handler.

{"type": "new_session"}

With optional parent session tracking:

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

Response:

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

If an extension canceled:

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

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
  }
}

The model field is a full Model object, or omitted when no model is selected. The sessionName field is the display name set via set_session_name, or omitted if not set. sessionFile is omitted with --no-session; sessionId is then the in-memory session's ID.

pig adds fields of its own after these, which upstream clients can ignore: isBashRunning, isPersisted, contextTokens, autoRetryEnabled, isRetrying, routedModel ({provider, id, thinkingLevel} of the model a virtual model last routed to, or null), cwd, and opening (the first 60 characters of the first user message).

Get all messages in the conversation.

{"type": "get_messages"}

Response:

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

Messages are AgentMessage objects (see Message Types).

Switch to a specific model.

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

Response contains the full Model object:

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

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

{"type": "cycle_model"}

Response:

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

The model field is a full Model object.

List all configured models.

{"type": "get_available_models"}

Response contains an array of full Model objects:

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

Set the reasoning/thinking level for models that support it.

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

Levels: "off", "minimal", "low", "medium", "high", "xhigh", "max"

"xhigh" and "max" are exposed only when supported by the selected model. Some models, including GPT-5.6, expose both. A level the model does not offer is clamped to the nearest one it does; get_state reports the level that was set. A string that is not a thinking level is an error.

Response:

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

Cycle through available thinking levels. Returns null data if model doesn't support thinking.

{"type": "cycle_thinking_level"}

Response:

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

List the thinking levels supported by the current model. Returns ["off"] for a model without reasoning support.

{"type": "get_available_thinking_levels"}

Response:

{
  "type": "response",
  "command": "get_available_thinking_levels",
  "success": true,
  "data": {
    "levels": ["off", "minimal", "low", "medium", "high"]
  }
}

Control how steering messages (from steer) are delivered.

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

Modes:

• "all": Deliver all steering messages after the current assistant turn finishes executing its tool calls
• "one-at-a-time": Deliver one steering message per completed assistant turn (default)

Response:

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

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 follow-up message per agent completion (default)

Response:

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

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,
    "estimatedTokensAfter": 32000,
    "usage": {
      "input": 32000,
      "output": 1200,
      "cacheRead": 0,
      "cacheWrite": 0,
      "totalTokens": 33200,
      "cost": {"input": 0.01, "output": 0.02, "cacheRead": 0, "cacheWrite": 0, "total": 0.03}
    },
    "details": {}
  }
}

estimatedTokensAfter is a heuristic estimate over the rebuilt message context immediately after compaction, not a provider-exact token count. usage reports the LLM call or calls that generated the summary and may be omitted by custom compaction handlers.

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}

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 an in-progress retry (cancel the delay and stop retrying).

{"type": "abort_retry"}

Response:

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

Execute a shell command and add output to conversation context. Output streams as bash_execution_update events while the command runs; the response contains the final result.

{"id": "req-1", "type": "bash", "command": "ls -la"}

Set excludeFromContext to true when the command output should be stored in the session but omitted from the model context on the next prompt.

Include an id to associate streamed bash_execution_update events with this command.

Response:

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

exitCode is omitted when the command was killed before it exited. If output was truncated, includes fullOutputPath:

{
  "type": "response",
  "command": "bash",
  "success": true,
  "data": {
    "output": "truncated output...",
    "exitCode": 0,
    "cancelled": false,
    "truncated": true,
    "fullOutputPath": "/tmp/pig-bash-abc123.log"
  }
}

How bash results reach the LLM:

The bash command executes immediately and returns a BashResult. Internally, a BashExecutionMessage is created and stored in the agent's message state.

When the next prompt command is sent, pig transforms context messages before sending them to the model. Unless excludeFromContext is true, the BashExecutionMessage becomes a UserMessage with this format:

Ran `ls -la`

total 48

drwxr-xr-x ...

This means:

1. Included bash output reaches the model on the next prompt, not immediately.
2. Multiple bash commands can run before a prompt; pig includes each output that does not set excludeFromContext.

Abort a running bash command.

{"type": "abort_bash"}

Response:

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

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
    }
  }
}

tokens and cost include assistant messages, usage reported by tools, and compaction/branch-summary generation across the full session. contextUsage contains the actual current context-window estimate used for compaction and footer display.

contextUsage is omitted when no model or context window is available. contextUsage.tokens and contextUsage.percent are null immediately after compaction until a fresh post-compaction assistant response provides valid usage data.

Export session to an HTML file.

{"type": "export_html"}

With custom path:

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

Response:

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

Load a different session file. Can be canceled by a session_before_switch extension event handler. A session from another project continues in its own working directory: pig builds a new runtime for that directory (its settings, trust, extensions, and context files) and keeps serving RPC from it. If the session's directory no longer exists, the command fails with an error, since there is nobody to ask whether to continue in the current one.

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

Response:

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

If an extension canceled the switch:

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

Create a new fork from a previous user message on the active branch. Can be canceled by a session_before_fork extension event handler. 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}
}

If an extension canceled the fork:

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

Duplicate the current active branch into a new session at the current position. Can be canceled by a session_before_fork extension event handler.

{"type": "clone"}

Response:

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

If an extension canceled the clone:

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

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 all session entries in append order (excluding the session header). The session is an append-only tree of entries with stable ids, so an entry id works as a durable cursor: pass the last entry id you have seen as since to get only entries strictly after it, even across client restarts. Unlike get_messages, this includes pre-compaction history and abandoned branches.

{"type": "get_entries"}

With a cursor:

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

Response:

{
  "type": "response",
  "command": "get_entries",
  "success": true,
  "data": {
    "entries": [
      {"type": "message", "id": "def456", "parentId": "abc123", "timestamp": "...", "message": {"role": "user", "...": "..."}}
    ],
    "leafId": "def456"
  }
}

leafId is the id of the current leaf entry (null for an empty session), so a client can tell in one round trip whether the active branch moved. If since does not match any entry id, the response is success: false.

Get the session as a tree of entries. Each node is {entry, children, label?, labelTimestamp?}. The result is an array because navigation APIs can create multiple roots; orphaned entries with broken parent chains also appear as roots.

{"type": "get_tree"}

Response:

{
  "type": "response",
  "command": "get_tree",
  "success": true,
  "data": {
    "tree": [
      {
        "entry": {"type": "message", "id": "abc123", "parentId": null, "...": "..."},
        "children": [
          {"entry": {"type": "message", "id": "def456", "parentId": "abc123", "...": "..."}, "children": []}
        ]
      }
    ],
    "leafId": "def456"
  }
}

Get the text content of the last assistant message.

{"type": "get_last_assistant_text"}

Response:

{
  "type": "response",
  "command": "get_last_assistant_text",
  "success": true,
  "data": {"text": "The assistant's response..."}
}

The text value is null if no assistant text exists.

Set a display name for the current session. The name appears in session listings and helps identify sessions.

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

Response:

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

The current session name is available via get_state in the sessionName field. To set the initial name when starting RPC mode, pass --name <name> or -n <name> to the pig --mode rpc process.

Get available commands (extension commands, prompt templates, and skills). Run one through the prompt command by prefixing its name with /.

{"type": "get_commands"}

Response:

{
  "type": "response",
  "command": "get_commands",
  "success": true,
  "data": {
    "commands": [
      {
        "name": "fix-tests",
        "description": "Fix failing tests",
        "source": "prompt",
        "sourceInfo": {
          "path": "/home/user/myproject/.pig/agent/prompts/fix-tests.md",
          "source": "local",
          "scope": "project",
          "origin": "top-level"
        }
      }
    ]
  }
}

Each command has:

• name: Command name (use /name)
• description: Human-readable description (optional for extension commands)
• source: What kind of command:

- "extension": Registered via $pig->registerCommand() in an extension

- "prompt": Loaded from a prompt template .md file

- "skill": Loaded from a skill directory (name is prefixed with skill:)

• sourceInfo: Metadata for the resource that registered the command:

- path: Absolute path to the resource

- source: How pig discovered it, such as "local", "auto", or "cli"

- scope: "user", "project", or "temporary"

- origin: "top-level" for a directly loaded resource or "package" for a package resource

- baseDir: Package base directory, when applicable

Note: Built-in TUI commands (/settings, /hotkeys, etc.) are not included. They are handled only in interactive mode and would not execute if sent via prompt. pig approximates sourceInfo for some resources.

pig-only: upstream pi offers navigateTree() to extensions but not as an RPC command; pig exposes it under upstream's name and result shape. Move the session leaf to another entry, optionally summarizing the branch that is left. Going back to a user message lands before it and returns its text as editorText.

{"type": "navigate_tree", "targetId": "abc123", "summarize": true, "customInstructions": "Focus on the failed approach", "replaceInstructions": false, "label": "before refactor"}

Only targetId is required. Response:

{
  "type": "response",
  "command": "navigate_tree",
  "success": true,
  "data": {
    "cancelled": false,
    "editorText": "The original prompt text...",
    "summaryEntry": {"type": "branch_summary", "id": "def456", "...": "..."}
  }
}

cancelled is true when a session_before_tree handler cancelled the navigation; aborted is present when the summary was aborted. editorText and summaryEntry are omitted when there is none. The session must be saved; with --no-session the command fails.

These commands back the Web UI, which runs each conversation as an RPC child. Upstream pi has no equivalent.

Command	Fields	Response data
doctor	none	{plain, report: {php, binaries, auth, proxy, session}}, the /doctor report as text and as data
diff	args (optional, e.g. "--staged")	{diff}, the output of git diff in the session's directory; fails outside a git repository
bug	hint, includeTranscript (optional)	{path, issueUrl, report}: the report written under ~/.pig/agent/bug-reports/ and a prefilled GitHub issue link. Unlike interactive /bug, nothing is uploaded
export_markdown	format: "md" (default) or "pr"	{format, markdown}: the session as Markdown, or a pull-request description written by the model (pr costs a model call)

Model commands return the complete configured model definition. Costs are in US dollars per million tokens.

{
  "id": "claude-sonnet-4-20250514",
  "name": "Claude Sonnet 4",
  "api": "anthropic-messages",
  "provider": "anthropic",
  "baseUrl": "https://api.anthropic.com",
  "reasoning": true,
  "input": ["text", "image"],
  "contextWindow": 200000,
  "maxTokens": 16384,
  "cost": {
    "input": 3.0,
    "output": 15.0,
    "cacheRead": 0.3,
    "cacheWrite": 3.75
  }
}

For model configuration, see Configure a compatible endpoint. In PHP, use the Pig\Ai\Model class.