Drive it from another program #
maple-harness --rpc reads commands from another process instead of a person, and writes back everything that
process needs to follow along: the model's own output, tool calls and results, questions that need an answer, and
the running cost — as it happens, not only once the whole session ends. It is how a CI step, an editor plugin, or a
script of your own drives a session the same way the terminal interface does.
In plain words #
- What it is. A way for another program (a CI job, an editor plugin, your own script) to drive a Maple session, line by line, as the terminal does.
- Why you want it. Automate the agent and still see every tool call, question and cost as it happens.
- What to do. Start
maple-harness --rpcfrom your program and exchange one JSON object per line. The commands and events follow.
Start it #
maple-harness --rpc
It never starts on its own; it is meant to be the child of whatever is driving it. One JSON object per line comes in
on stdin, one JSON object per line goes out on stdout. Nothing else is written to stdout — diagnostics and notes go
to stderr, the same convention --prompt uses, so a plain harness --rpc < commands.jsonl > events.jsonl captures
exactly the protocol.
It cannot be combined with --prompt, --repl or --remote: each is its own way of driving the session, and
--rpc is this one.
Nobody can answer a question here, so when the proxy on this machine cannot be verified as yours, --rpc does not
start: it writes nothing on stdout, prints the reason and the fixes on stderr, and exits with status 1. Start the proxy
as the same user with the same settings folder (or let the harness start it), or see
CI jobs and containers for a proxy you do not start.
Commands #
Every line you send is one JSON object with a cmd field, and an optional id you choose — it comes back on the
response so you can match one to the other.
cmd | What it does |
|---|---|
prompt | Starts a new turn with text. Rejected while one is already running — say steer or follow_up instead, because they mean different things. |
steer | Adds text to the turn that is running right now, delivered after its current tool calls finish and before the model is asked again. Rejected when nothing is running. |
follow_up | Queues text for after the running turn finishes, or starts it at once if nothing is running. |
abort | Cancels the running turn and refuses any permission question it left open. A no-op when nothing is running. |
permission_answer | Answers a permission_request event by its request_id, with allow (and optionally always, for the rest of the session). |
{"id": "1", "cmd": "prompt", "text": "add a test for the empty-cart case"}
The response says what happened to the command itself, not how the turn it may have started turns out:
{"type": "response", "id": "1", "cmd": "prompt", "ok": true, "disposition": "started"}
disposition is started (a new turn began), queued (waiting for the current one), aborted, noop, or
handled (a permission answer). ok: false carries an error saying why — malformed JSON, a missing field, an
unknown command, or a command that does not apply right now (a prompt while one is already running, a steer
with nothing to steer). None of these stop the session; the next line is read as normal.
Events #
What the turn itself does streams as further lines, "type": "event", tagged by event:
event | Carries |
|---|---|
assistant_delta / assistant_done | text (and thinking, when the model reasoned) |
tool_call / tool_result | tool, tool_arg |
steered | text — a steer command landed and is now part of the conversation |
notice | text — something worth telling a person, from the harness itself |
turn_start / turn_end | msg_id; turn_end also carries stop_reason, error if any, and usage |
usage is the session's running total — tokens, cache reads and writes, AI units — the figures --prompt
--json-summary writes as its session_* fields, sent after every turn rather than only once at exit. It is the true total: if this turn delegated
work to a subagent (see subagents), that subagent's own tokens and AI units are folded in here too,
the same as they are in /cost and the status bar — not just the driving turn's own requests.
{"type": "event", "event": "turn_end", "msg_id": "m1", "stop_reason": "end_turn",
"usage": {"turns": 3, "input_tokens": 8120, "cached_tokens": 7200, "cache_write_tokens": 400, "output_tokens": 540, "ai_units": 4.1}}
A permission question #
A tool call that needs approval under your permission settings — the same settings --yolo and the interface's own
mode control (ask/auto/yolo) govern — is not decided for you. It arrives as an event:
{"type": "event", "event": "permission_request", "request_id": "a1b2c3", "tool": "bash", "tool_arg": "rm -rf build/"}
Answer it the same way a person would:
{"cmd": "permission_answer", "request_id": "a1b2c3", "allow": true}
and a permission_resolved event confirms it, with allow and always. There is no timeout on a question left
unanswered — the tool call waits, exactly as it would for a person at a terminal.
What it is not #
This is a local pipe between a parent process and the child it started — there is no listening address and no token, because whoever can write to this process's stdin already has everything a shell here would give them. If you want a session another device can join over the network instead, see Control it from your phone, which is a different feature with its own, separate authentication.