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.

Commands and keys #

On this page
  1. In plain words
  2. Modes and keys
  3. Slash commands
  4. Agents and the agents tray
  5. Your own commands and skills
  6. Commands you run from a shell
  7. Command-line flags

Everything you can type in a session, the keys, the modes, and the commands you run from a shell. For the settings in config.yaml, see Harness settings; for the proxy, see Proxy settings.

Each item has a Helps tag, because each exists to serve one or more of three goals:

  • Efficient: fewer tokens or AI units for the same work.
  • Efficacious: the work stays as good, and the safe choice is the default.
  • Effective: whole tasks succeed: the right model, and waste stopped before it grows.

A tag appears only where it is true. Nothing here is a promise about your bill: measure your own tasks.

In plain words #

  • What it is. The list of everything you can type: slash commands in a session (/model, /cost, /remote), the keys, the modes, and the shell commands of both programs.
  • What to do. /help in a session lists the commands; this page says what each does and its trade-off. For the setup page instead, see The proxy and its setup page.

Modes and keys #

Permission modes decide what happens when the model wants to write a file or run a command.

ModeWhat happensHelps
ask (default)You are asked before each write or command. deny rules are absoluteEfficacious
autoWrites and commands run without asking; deny rules still apply. Unlike yolo, it can be chosen with Shift+Tab or set in config.yamlEffective
yoloEvery question is answered yes. deny rules and the sandbox still apply. It exists only when you start with --yolo; a config file can never turn it onEffective (in a disposable place only)
plan (/plan)Read-only: the model can look but not change, and its answer is a planEfficacious
KeyWhat it does
/ then typeOpens completion over built-in commands, your commands and your skills. Tab fills, ↑/↓ move, Enter runs
EnterSends the message; while the model is busy, queues it
Shift+EnterA new line in the message box (Alt+Enter and Ctrl+J also work)
Shift+TabCycles mode: ask then auto (and yolo only when launched with --yolo)
EscInterrupts the running turn, or clears the input when idle
Ctrl-CClears the input; interrupts a turn; quits on a second press. With text selected and nothing running, it copies the selection instead of offering to quit
y n aAnswers a tool approval (a = always, for this session)
Mouse wheelScrolls the transcript at any time: while the model works, while an approval or a list is open, and inside a subagent's transcript
↑ ↓Scroll the transcript while the message box is empty or an approval is waiting
PgUp PgDnScroll a page, at any time. Ctrl+End jumps back to the bottom
Ctrl+OExpand or fold every long tool output
ClickOn a folded tool result, or on the tool call above it, opens just that one; click it again (or its "click to fold" line) to fold it. On a row of the agents tray, opens that subagent
DragSelects text in the transcript, and letting go copies it. Dragging past the top or bottom scrolls. A double click selects a word, a triple click a line. The highlight stays until the next click or key
Ctrl+YCopies the selected text; with nothing selected, the entry you last clicked; otherwise the last answer, as the Markdown the model wrote
Shift+dragYour terminal's own selection, even while the mouse is captured (Option+drag in iTerm2). Copy it with your terminal's key, such as Ctrl+Shift+C or Cmd+C
Ctrl+VPastes text, or a picture on the clipboard (macOS; Linux with wl-clipboard or xclip installed), which is saved under .mapleharness/pasted/ and its path put in your message
Drop a fileDropping files on the terminal window puts their paths in your message; pictures (png, jpeg, gif, webp) are also attached, so the model sees them with your next message
Ctrl+TMove into the agents tray (below)

The message box and the status bar stay on the same rows whatever appears above them (an approval question, the agents tray, a list to choose from).

Copying. Drag to select and it's copied; Ctrl+Y or /copy copies the last answer. Nothing else needs learning. A copy goes to the clipboard two ways at once: through your terminal, which also works over SSH, and through wl-copy, xclip, xsel or pbcopy when one is installed. A terminal only takes the first if it lets programs set the clipboard; some ask you to turn that on. Inside tmux, add set -g set-clipboard on to your tmux configuration (or set -g allow-passthrough on). Through the terminal, a copy is cut at about 74 kB; the line under the status bar and the transcript say when that happens, and an installed clipboard program still gets all of it. A selection is copied as the transcript shows it, without the transcript's left margin: a long line the window wrapped is copied as separate lines, so use Ctrl+Y or /copy for an answer's exact text. To start with the mouse off, set mouse: false (configuration); /mouse on turns it on.

The transcript with two lines of an answer highlighted, and the line under the status bar saying copied 159 characters (selection)The transcript with two lines of an answer highlighted, and the line under the status bar saying copied 159 characters (selection)
Drag over the transcript to select; letting go copies it, and the line under the status bar says how much.

The message box is never disabled: type while the model works and your messages queue and run in order. Built-in commands still run immediately. Efficient: you can correct course early without waiting for a turn to finish.

Slash commands #

A slash command that this session does not have (not built in, and not one of your own commands or skills) is never sent to the model: Maple Harness says so and sends nothing. To send a message that starts with /, begin it with //; a path such as /etc/hosts at the start of a message is sent as it is.

Session #

CommandWhat it doesHelps
/helpShows the commands and keys
/clearStarts over: clears the screen and the conversation. Memory notes are keptEfficient
/quit, /exitExit
/sessionsLists saved sessions. Resume one with --session <name>Effective
/fork [n]Copies the first n messages of this conversation, and only the stored history that belongs to them, into a new session, leaving this one untouched — bare /fork copies up to and including your last message, so "try that again, differently" needs no argument. It does not switch this view to the fork; resume it with --session <name>Effective
/export [html|jsonl]Writes this conversation to a file (default jsonl) named after the session, in the working directory. Obvious secrets are redacted, but review it before sharingEffective
/tree [list|save [name]|fork <n or name> [new-name]]Saved points inside this conversation. Bare /tree or /tree list shows them; save marks the current point (with a model's one-line summary only when compress_with_model allows one); fork starts a new session from a saved point, never the running one — the same safe mechanism /fork usesEffective
/clone [name]Copies this conversation and its saved branches into a new session, leaving this one untouched. Unlike /fork, nothing is truncated: it is "keep going from here, in parallel," not "go back and retry"Effective
/share [confirm]Uploads this conversation as a private GitHub gist, via the gh CLI (needs gh auth login once). Nothing is uploaded until you type /share confirm — a private gist is still visible to anyone with its link, so review it first, the same as /export
/btw <question>Asks a side question without interrupting the running turn: no tools, and no shared historyEfficient
/copy [code [n]]Copies the last answer to the clipboard, as the Markdown the model wrote. /copy code copies the last code block of the newest answer that has one, and /copy code 2 its second (counting from the top)Efficient
/mouse [on|off]Without an argument, says whether the mouse is captured. /mouse off hands the mouse to your terminal, so it selects and copies text itself; /mouse on takes it back for scrolling, clicks and drag-to-copy. The line under the status bar says when it is off
/theme [name]Lists or switches colour themes, grouped dark / light / colour-vision-deficiency-friendly (full list: configuration). /theme auto follows your Omarchy desktop theme and keeps following it live; any other name stops following. The choice is saved as theme in your config.yaml, so the next session opens with it; only that line changes, and your comments and other settings stay as they are

Models and effort #

CommandWhat it doesHelps
/modelOpens a list of the models the proxy serves. Bare /model also shows what automatic choice would use for each kind of workEffective
/model <name>Switches straight to that model or alias. In the plain line mode (--repl), bare /model prints the listEffective
/model autoChooses a model per message from what your provider serves, within your current provider, keeping your model when it fits. It says what it chose and why; /model fixed takes the choice backEfficient, Effective
/effort [level]How hard the model thinks. Bare /effort lists the levels this model accepts; default returns to the model's ownEfficient, Effective
/thinking <off|on|tokens>Turns thinking off or on, or sets a token budget for models that take oneEfficient
/disable-thinking, /enable-thinkingShorthands for thinking off and onEfficient
/plan [on|off], /plan-modePlan mode: read-only, and the answer is a plan. Pairs well with /model autoEfficacious
/mode [name], /yolo on|offCycles the permission mode, or switches to ask, auto or yolo (yolo needs --yolo at start-up)Efficacious

Context and cost #

CommandWhat it doesHelps
/contextWhat the model can see: memory notes, the project index, the tools it is offered, the window used, and what the session has spentEfficient
/costWhat the session has spent: totals, the last requests with their cache hit rate (and where a model change or a low hit rate lost the cache), retries, where the input goes, and which of the tool results still in the conversation have cost the most by being sent again and again. See What /cost tells youEfficient
/savingsWhat the harness's own techniques saved and cost this session. Every figure is marked measured or estimated, costs are counted, and the net can be negativeEfficient
/settings, /configuration, /configEvery harness.* setting in a table grouped by area (Sandbox, Permissions, Theme & display, and so on): its effective value, where it comes from (default, user config or project config) and what it does. A value you changed is highlighted and marked •; a list shows how many entries it has. /settings changed shows only what differs from the default; /settings <word> shows one group, or the settings whose name contains the word (/settings sandbox). /settings get <key> shows one setting in full; /settings set <key> <value> changes one and saves it to your global config.yaml. The three names are the same command. See Per-project overrides
/compressMakes room now: older messages are stored and stay searchable, and a record of the work takes their place. By default no model is asked, so it costs nothing; a model's summary is added only when compress_with_model allows one. Esc stops it. See Long conversationsEfficient, Effective
/look <path>, /image <path>Attaches a png, jpeg, webp, gif or pdf so the model can see it, not just its path. It rides with your next messageEffective
The /settings mode command showing a table of settings grouped under Model, Permissions, Sandbox, File access, Guards, Conversation and Prompts, with columns for the value, where it comes from and what it doesThe /settings mode command showing a table of settings grouped under Model, Permissions, Sandbox, File access, Guards, Conversation and Prompts, with columns for the value, where it comes from and what it does
/settings mode: the settings whose name contains "mode", grouped by area; changed values are marked with a dot.

Memory, project and tools #

CommandWhat it doesHelps
/memory [list|show <name>|rm <name>|path]The agent's notes about the project and youEffective
/graph [stats|reindex|connections <id>|path]Queries and rebuilds the project index of notes and code symbols the harness looks things up inEfficient
/jobsLists background commands started with run_in_backgroundEffective
/mcpThe connected MCP servers and the tools each providesEffective
/lspLanguage servers: detected, running, or missing, with the install command for each missing oneEffective, Efficacious
/ledger [show|add|done|block|drop|rebuild|clear]The checklist kept for a large request: items are checked before they are called done. Needs ledger: autoEffective
/proxyWhere the proxy is, whether it answers, and where its log is. /proxy start, /proxy stop and /proxy restart control it (other harnesses share it); /proxy logs [lines] shows the end of the log of a proxy the harness started, when proxy_logs is onEffective

Memory notes. The model saves a note with the remember tool by giving a kind (project, user, feedback or reference), a one-line title and the fact, and optionally why it matters, how to apply it, and a few tags. The harness writes every note in the same shape, so notes read the same whichever model wrote them, and they stay plain Markdown you can open and edit. Saying the same thing again updates the existing note instead of adding a copy, and an empty or oversized note is refused with the reason. Notes written by earlier versions still load. Project notes the model writes live in the project's .mapleharness/memory folder, which is not committed. The notes the harness writes on its own (the session-progress note at the end of a session, and the test and build commands it saves) live in your Maple Harness config folder under notes/<project>/, never inside the project; notes it wrote in the project folder before are moved there the next time a session starts. recall shows both kinds. The harness does not read or write project notes through a symbolic link: if .mapleharness or .mapleharness/memory is a link, the model's project notes are not used, and a note file that is a link is replaced when written, never written through.

Session journal. After every turn the harness itself, not the model, records what the turn did: the files read and changed, the commands run and whether they passed, failed tool calls, and the model used. It is kept per session in your Maple Harness config folder, in a folder for each project (never inside the project itself), stays small (older sessions are removed), and passes through the same redaction as the rest of the harness. sessions rm removes a session's journal with it, and cleanup removes journals whose session is gone. The model can read this session's journal with recall and journal: true. When a test or build command has passed several times across different turns of this session, the harness saves it as a project memory note so the next session knows how to check its work. Only the plain command is saved: no environment variables in front of it, nothing chained after it, no redirections, and nothing at all if it carries something that looks like a credential. It never overwrites a note the model or you wrote, and it saves nothing that needs judgement. What a subagent reads, changes and runs goes in the same journal, marked with the subagent's name; memory notes are saved from your own session's commands only.

Project index. Files the model writes or edits are re-indexed in the background shortly after each turn, only those files, so the index stays current during a session without slowing it down. Files changed some other way — a command, a subagent, your editor — are found after each turn too, recorded in the journal as changed from outside, and re-indexed the same way. Test files (_test.go) and build files such as go.mod and Makefile are recorded in the journal too, though the index leaves them out.

Search by meaning. With a model for it set up in the proxy, history_search, recall and graph_search also rank results by what they mean, combined with the words they share, and recall gains a query argument. Without one they work exactly as before. See Search by meaning.

Switching model mid-conversation. The first message on the new model carries one short note saying which model held the conversation, and that memory, the journal, history_search and the code index already hold what it would otherwise re-read. A switch back to a model that has already had the note gets a single line.

Safety #

CommandWhat it doesHelps
/sandboxHow the bash tool is contained: the mode, the backend, what is writable and hidden. See The shell sandboxEfficacious
/sandbox auto, /sandbox strict, /sandbox offContains commands when a backend is available; refuses to run them without one; or no containment for this sessionEfficacious
/sandbox network allow, /sandbox network denyLets contained commands reach the network, or cuts itEfficacious
/sandbox allow <path>Lets contained commands read a hidden path for this session; --write makes it writable; --save keeps it in config.yaml. See The shell sandboxEfficacious

Agents #

CommandWhat it doesHelps
/agentsManage subagents: list, view, create, edit, deleteEffective
/agent <name> <task>, @name <task>Runs a subagent on a taskEfficient, Effective

Remote and notifications #

CommandWhat it doesHelps
/remoteShares this session with a phone or another Maple Harness. See Control it from your phoneEffective
/remote pairOpens a list of addresses, then makes a short pairing code and one QR for the address you pick. --via, --token and --fixed change what it makes; --watch-only makes a device that can watch but not drive; --no-start refuses to start the gateway if none is runningEffective
/remote status, /remote devicesWhere remote control is listening, and the devices that have a tokenEfficacious
/remote share [label] [--for 1h|8h|24h|7d] [--drive|--device], /remote shares, /remote unshare <id>Makes a link that lets one person watch this session live, read-only, until it ends (24 hours unless you choose); with --drive, a link that can also send messages and answer approvals in this session (8 hours unless you choose; it explains what that allows and asks you to repeat it with --confirm); with --device, a pairing link for one of your own devices that may use this session only (7 days unless you choose, up to --for 30d; it also asks for --confirm); lists this session's shares and devices; stops one. See Sharing one sessionEfficacious
/remote revoke <id>, /remote offRemoves one device's token (it stops at once), or stops sharingEfficacious
/remote local, /remote tailscaleShares on this machine only (through an SSH tunnel), or serves a real certificate for your tailnet nameEfficacious

See Control it from your phone for the whole flow.

Agents and the agents tray #

Subagents are helper agents you define in .claude/agents/<name>.md (or ~/.claude/agents), or use from the built-in set. The model can hand them jobs, and you can run one yourself with @name <task> (Tab completes the name). While any run, a tray sits just above the message box:

  • a main row and one row per subagent, with a status mark, its name, what it is doing, elapsed time and tokens;
  • ↓ from an empty message box, or Ctrl+T, moves into it; ↑/↓ move between rows;
  • Enter, or a click on its row, opens that subagent's live transcript (read-only); the wheel and PgUp/PgDn scroll it; Esc, Enter, q, b, ←, Backspace or a click leaves it;
  • x then y stops the selected subagent; c collapses the tray to "N agents" on the status line.

Efficient: a subagent's long searches and tool output stay out of the main conversation, so the main conversation stays short. See Subagents.

Your own commands and skills #

  • .claude/commands/<name>.md becomes /name (with $ARGUMENTS, or $1 to $9, substituted).
  • .claude/skills/<name>/SKILL.md becomes a skill, callable with /name or chosen by the model.

Built-in commands always win over a command or skill with the same name. Effective: your team's routines are one keystroke away.

Commands you run from a shell #

maple-harness with no command starts the full-screen interface. The short name is mpl.

On a terminal, commands that print lists or status use tables and your theme's colours, fitted to the window. Piped into another program or a file, the output is plain text with no colour codes and no cut-off cells. --no-color or the NO_COLOR environment variable turns colour off, and --json output never has colour.

CommandWhat it doesHelps
maple-harness auth login|status|logout <provider>Sign in to github-copilot or anthropic through the proxyEffective
maple-harness sessions list|show|rm|path <name>Work with saved sessions. rm also removes the session's stored history and journal, and a stored history left without its session. sessions prune is the same as cleanupEffective
maple-harness sessions fork <new-name> [n]Forks the latest session in this directory into a new one, up to and including its last user message (or the first n messages, given), with only the stored history that belongs to those messagesEffective
maple-harness sessions export <name> [--format html|jsonl] [--out FILE]Writes a saved session's transcript to a file (default: <name>.jsonl in the working directory). Obvious secrets are redacted, but review it before sharingEffective
maple-harness sessions tree <name> list|fork <ref> <new-name>Lists a saved session's branches, or forks one into a new session. save is TUI-only — it needs a live conversation to summariseEffective
maple-harness sessions clone <name> <new-name>Copies a saved session's messages and branches into a new one, leaving the original untouchedEffective
maple-harness sessions share <name>Uploads a saved session's transcript as a private GitHub gist, after asking yes/no on the terminal
maple-harness cleanupShows saved sessions and project indexes that can go, stored histories and journals whose session is gone, and temporary files an interrupted save left behind (older than an hour); removes them only with --yes. --older-than, --keep, --sessions, --graphs, --declines (forget which models declined tasks), --jsonEfficient
maple-harness doctorChecks the setup and says what is wrong and what to do. --fix repairs what is safe, --json prints the report, --report FILE writes a redacted bundle to attach to a bug report, --online also checks the update feedEfficacious
maple-harness trust list|approve|forget [path]A project's own hooks and MCP-server files ask before running the first time; manage that decision directly instead of waiting to be asked. list --json for a machine-readable formEffective
maple-harness bench run|report|arms|init-demoReplays the same tasks under different settings, several times each, and compares them task by task with the uncertainty shown. Nothing is spent without --yes and a budget. See Measure with benchEfficient, Effective
maple-harness proxy connect --sso <url>A shortcut (--name, --models-url) that has your local proxy sign in to a team hub with your company account, the same as maple-proxy chain connect --sso. It starts the proxy if it is not running, prints a link and a code to enter on the hub's My access page, and finishes when you confirm there. The harness itself is not signed in and gets no token: it keeps using your local proxy, which reaches the hub's models as hub/<model>. --name NAME names the hub on your proxy (default hub). See Join your laptop to a team hubEffective
maple-harness proxy connect <url>|disconnect|statusAdvanced, for CI jobs and containers where no proxy of your own can run: uses a proxy on another machine with an access token. connect asks for the token (or reads it from standard input), keeps it in the secret store and sets proxy.url and proxy.token; --token-env NAME uses an environment variable instead, --allow-insecure accepts plain http on a private network. disconnect goes back to the proxy on this machine; status says where the proxy is and whether it answers. See Connect the harness to a proxyEffective
maple-harness proxy restartRestarts the proxy on this machine on this release (the same as /proxy restart in a session). A proxy on another machine is never restarted from here. See Verified and unverified proxiesEffective
maple-harness savingsThe proxy's savings account in a terminal (--json, --addr); the same as the setup page's Savings cardEfficient
maple-harness graph stats|nodes|connections|reindex|wipe|pathInspect and rebuild this project's indexEfficient
maple-harness mcp serveServes this project's notes and index to any tool that speaks MCP. Off this machine it needs an access token and TLS. See Give other tools this project's knowledgeEffective
maple-harness serveRuns a session with no terminal and lets another device drive it. See Control it from your phoneEffective
maple-harness attach <address>Opens your usual interface on a session running somewhere else. --token-file, --fingerprint and --sessionEffective
maple-harness gateway start|pair|address|status|stopThe one remote-control address on this machine. workspaces add|rm|list chooses the folders a phone may start sessions inEffective
maple-harness notify test|statusSends a test message to your notification destinations, or shows what is configuredEffective
maple-harness service install|uninstall|status|printKeeps the proxy and the gateway running in the background. See Keep it running in the backgroundEffective
maple-harness updateInstalls a newer release. --check reports only
maple-harness version, maple-harness licensesThe version, and the licences of the software inside the program
maple-harness herdr-manifestPrints a detection manifest for Use it with herdr (advanced)

The proxy has its own commands (maple-proxy, short name mplp), listed in The proxy and its setup page. Among them, maple-proxy token add <label> [--person <id>] makes a person's proxy token in a terminal (shown once), maple-proxy token list shows every token's id, label and person, and maple-proxy token revoke <id> revokes one. See Teams.

Signing your proxy in to a team hub happens at the proxy:

Proxy commandWhat it does
maple-proxy chain connect --sso <url>Signs this proxy in to a team hub with your company account (--name, --models, --wait, and --models-url for a models address off the hub's sign-in domain that you trust; see Where your requests go): it prints a link and a code, you sign in on the hub's My access page (on any device) and confirm the proxy's name. The proxy then holds a token for you, renewed quietly for up to 7 days, and the hub becomes a provider (hub/<model>). --name NAME (default hub), --models a,b to list hub models, --wait 10m to stop waiting sooner. See Join your laptop to a team hub
maple-proxy chain statusThe hubs this proxy uses and whether they answer, and, under Sign-ins with a company account:, each sign-in with who it is and until when it renews, or what needs attention (REVOKED: sign in again when the hub ended it)
maple-proxy chain disconnectEnds a sign-in: the token is revoked at the hub, forgotten here, and the hub's provider removed. --name NAME (default hub), --keep-provider to keep the provider entry

Command-line flags #

FlagWhat it does
--prompt "text"Runs one turn and exits, printing the answer. Everything else goes to the error stream, so > out.txt captures just the answer. Answers print as they arrive; when a check sends one back and the answer that stands is not the last one printed, it is printed again at the end (the error stream says » final answer:), so the output always ends on it
--json-summary FILEWith --prompt: writes a machine-readable summary of the run (tokens, cache figures, AI units, tool calls, why it stopped): this run's own figures, with the session's totals in session_* fields when it continues a session. A run stopped by a signal (a timeout, Ctrl-C) still writes it, with "interrupted": "terminated" or "interrupt" and what it had spent until then
--continue, --resume, --session NAMEResume the most recent session here, pick one to resume, or use a named session
--config PATHUse a specific config.yaml
--yoloAllow yolo mode (see above)
--replUse the plain line-based interface instead of the full-screen one
--rpcRead newline-delimited JSON commands from stdin and write newline-delimited JSON events to stdout, for scripting and IDE integration. See Drive it from another program
--remoteAlso let another device drive this session. --remote-listen, --remote-tls, --remote-allow-host and --remote-insecure-http set how

A run started with --prompt that is stopped because the same problem kept failing exits with status 3, and says what it tried.

A run that nobody can answer (--prompt, --rpc, serve, or no terminal) does not start when the proxy on this machine cannot be verified as yours: it exits with status 1 at once and prints This session cannot ask you, so it did not start. with the fixes. For CI jobs, see CI jobs and containers.

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