RPC protocol
Control Tau as a subprocess with Pi-compatible JSONL commands and events.
Run Tau as a headless subprocess:
tau --mode rpc [--provider NAME] [--model MODEL] [--cwd PATH] [--session ID]
RPC mode reads one JSON object per LF-terminated line from stdin and writes responses and
session events as compact JSON lines to stdout. Diagnostics use stderr. Clients may include an
id; the corresponding response echoes it. Event records are asynchronous and do not normally
carry request IDs.
{"id":"1","type":"prompt","message":"Inspect this project"}
{"id":"1","type":"response","command":"prompt","success":true}
{"type":"agent_start"}
The protocol supports Pi-compatible prompting (prompt, steer, follow_up, abort), state
and message inspection, complete Pi-shaped model references, model and thinking cycling,
auto-compaction control, direct shell commands, HTML export, new/resumed sessions, entry cursors,
session statistics and trees, forking, last-assistant lookup, session naming, and command
discovery. Unknown commands and invalid arguments return success: false without stopping the
process.
Use agent_settled, not agent_end, to decide that a run is fully idle: retries, overflow
compaction, or queued continuations can follow agent_end.
Framing
Split records only on LF (\n). A trailing CR is accepted for CRLF input. Unicode line
separators such as U+2028 and U+2029 are ordinary characters inside JSON strings. Records are
limited to 16 MiB.
Minimal Node/Electron client
import { spawn } from "node:child_process";
const tau = spawn("tau", ["--mode", "rpc"], { stdio: ["pipe", "pipe", "inherit"] });
tau.stdout.setEncoding("utf8");
let buffer = "";
tau.stdout.on("data", chunk => {
buffer += chunk;
for (;;) {
const index = buffer.indexOf("\n");
if (index < 0) break;
const line = buffer.slice(0, index);
buffer = buffer.slice(index + 1);
console.log(JSON.parse(line));
}
});
tau.stdin.write(JSON.stringify({ id: "1", type: "prompt", message: "Hello" }) + "\n");
RPC and TUI compaction preserve recent entries and return or persist the first pre-existing
retained entry as firstKeptEntryId, matching Pi. Session inspection emits modern compactions
in Pi’s native shape without Tau’s former replacement-id bridge. Older Tau records can lack a
boundary; inspection exposes those honestly as customType: "tau.compaction" entries instead
of fabricating Pi compaction metadata. Their legacy id lists remain usable for local replay but
are not added to the RPC wire format. When available, projected compaction and branch-summary
entries include Pi-compatible usage data from the request that generated the summary. Legacy
entries and heuristic fallback summaries omit the field.
Session inspection projects persisted custom_message entries in Pi wire
shape: parentId, customType, content, details, and display. Tau’s local
session JSONL uses snake_case wrapper fields such as parent_id and
custom_type; clients should rely on the RPC shape rather than the storage
spelling.
Tau mirrors Pi where its public CodingSession has equivalent behavior. Direct bash is
supported, but abort_bash requires a future cancellable session API. Queue delivery modes,
retry controls, cloning, image prompts, and the extension UI request/response subprotocol remain
staged compatibility work. See dev-notes/design/rpc-runtime-interchangeability-plan.md for the
contract, completed frontend-critical phase, and remaining production phases.