Maple Harness home

Maple Harness 2.6.2 released! What's new in 2.6.2

Single userTeams & hubs

One person, one machine: the agent, the proxy and your own usage.

Several people, from one shared proxy up to a hub of hubs.

Drive it from another program #

On this page
  1. In plain words
  2. Start it
  3. Commands
  4. Events
  5. A permission question
  6. What it is not

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 --rpc from 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.

cmdWhat it does
promptStarts a new turn with text. Rejected while one is already running — say steer or follow_up instead, because they mean different things.
steerAdds 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_upQueues text for after the running turn finishes, or starts it at once if nothing is running.
abortCancels the running turn and refuses any permission question it left open. A no-op when nothing is running.
permission_answerAnswers 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:

eventCarries
assistant_delta / assistant_donetext (and thinking, when the model reasoned)
tool_call / tool_resulttool, tool_arg
steeredtext — a steer command landed and is now part of the conversation
noticetext — something worth telling a person, from the harness itself
turn_start / turn_endmsg_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.

Made with ❤️ by Kinn Coelho Juliao in Ottawa, eh — fuelled by double-doubles, bud. 🍁