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.

Subagents #

On this page
  1. In plain words
  2. The ones you already have
  3. Watching them work
  4. Make your own
  5. Settings
  6. Delegate to your local Claude
    1. Turn it on
    2. Choose which claude runs
    3. Extra options for Claude Code
    4. Checks before it runs
    5. How it is kept safe

A subagent is a second session that the main one hands a small, self-contained job to: "find where the retry logic lives", "review this diff", "plan the change". It has its own instructions, its own list of tools and optionally its own model. It does not see your conversation, and only its final report comes back, so a long search stays out of the main conversation.

In plain words #

  • What it is. A helper the agent hands a small job to ("find where retries happen", "review this diff"). It works on its own and only its report comes back.
  • Why you want it. A long search stays out of your conversation, so the main session stays short and cheap.
  • What to do. Nothing: the agent uses them when a job fits. To ask yourself, type @explore and the job. To make your own, write a short file, as below. There is no setup page step.

The ones you already have #

NameWhat it does
general-purposeTakes any self-contained task. Has the same tools as the main session
exploreReads and searches the project and answers questions about it. Cannot change anything
planStudies the code and returns a step-by-step plan. Cannot change anything

The model uses them by itself when a job fits. To run one yourself, type @ and the name, then the job:

@explore where is the retry logic, and what limits it?

Press Tab after the @ to complete a name. /agent explore where is the retry logic? does the same.

Watching them work #

While a subagent runs, a small list appears just above the input box (which does not move):

  ● main
  ◯ explore  reading the retry code                    31s · ↓ 339.6k tokens
  ! plan     waiting for your approval                 12s · ↓ 1.2k tokens

◯ is running, ! is waiting for you, ✓ finished, ✗ failed or stopped. Press the down arrow from an empty input box (or ctrl+t from anywhere) to move into the list, then:

  • the arrow keys choose between main and a subagent;
  • Enter on a subagent, or a click on its row, shows what it is doing, live and read-only (Esc goes back);
  • x, then y, stops the chosen subagent;
  • c folds the list into a count on the status line ("2 agents").

When a subagent needs your approval to write a file or run a command, the question comes to you like any other, with the subagent's name in it. Nothing is approved for you. A subagent can never do more than the main session is allowed to do.

On the phone page, an agents button in the status row opens the same list.

Make your own #

Type /agents. You see every agent with where it lives, and can view, create, edit or delete them. Creating one asks where it should live (this project, or all your projects), a name, a description (this is what tells the model when to use it), which tools it may use (all, read-only, or a list you tick), which model, a turn limit, and its instructions. It writes an ordinary file, and the new agent works straight away.

The file is the same format Claude Code uses, so you can also write it by hand in .claude/agents/ in a project or ~/.claude/agents/ for yourself:

---
name: reviewer
description: Reviews a diff for bugs. Use after a change is made.
tools: read_file, grep
model: gpt-4.1
maxTurns: 12
---
You review code. Report real bugs first, with the file and line, and nothing else.

If a project agent and one of yours share a name, the project's is used. Either one replaces a built-in of the same name.

Settings #

SettingDefaultMeaning
harness.subagents.max_parallel3How many run at the same time when the model hands out several jobs at once
harness.subagents.max_turns50The most turns any one subagent may take

When the model gives out several jobs in one message they run together, and their reports come back in the order they were asked. Each subagent's tokens count in your session's total.

Delegate to your local Claude #

If you have Claude Code installed and signed in on your machine, the harness can hand it a whole task: "ask my local Claude to review the error handling in this package". The harness runs your own claude program in this project folder (claude -p, its non-interactive mode), shows its progress in the agents list, and gives its final answer back to the model you are talking to. It sees none of your conversation, only the task.

What this is, in plain words:

  • It is your own Claude Code, on your machine. The harness runs the claude you installed, unchanged, as you. It never reads, stores or passes your Claude sign-in, and it never signs in for you.
  • It uses your Claude plan. What it does counts against your plan's limits, like running claude yourself. It does not go through Maple's proxy, so the proxy records no usage for it; each run ends with a line saying when it ran, for how long, how it ended, and that it used your Claude plan.
  • Only for you, only here. It is not offered when the harness uses a proxy on another machine (a team's proxy or a hub), it is not offered in a session that serves other devices, and it refuses to run while remote control is on. It runs one task at a time.
  • Through your own proxy only. It runs only while every connection the session opened to the proxy proved it reaches your own proxy on this machine, and only in a conversation whose every reply came that way (see Connect the harness to a proxy). A proxy you connected to with harness.proxy.url never offers it, even at a local address. A proxy not checked as yours (older than the harness, or run as another user, settings folder or container) keeps it off and says why.
  • A conversation from before, or from elsewhere, does not get it. A conversation saved by an earlier release, in remote mode, or through a proxy not checked as yours carries no mark that its replies came from your own proxy, so the delegate stays off in it. Start a new conversation to use it.

Turn it on #

It is off until you turn it on in your own config.yaml (a project's .mapleharness/config.yaml cannot):

harness:
  delegates:
    claude_code: on

The first time it runs in a project, and again whenever that project's Claude settings files change, the harness shows you what it is about to run and asks. The question lists what the project's .claude/settings.json, .claude/settings.local.json and .mcp.json would run: hooks, helper commands, the environment variables they set (flagging ones that could send your requests elsewhere or run code), and MCP servers. If they change while you are being asked, nothing runs.

The harness asking before your local Claude runs for the first time in a project: what runs, whose plan it uses, and what the project's .claude/settings.json namesThe harness asking before your local Claude runs for the first time in a project: what runs, whose plan it uses, and what the project's .claude/settings.json names
The question before the first run in a project, in a demo setup. A stand-in program sits where Claude Code would be; the harness has not run it yet.

Choose which claude runs #

By default the harness runs the claude it finds on your PATH. To run a particular one, name it in your own config.yaml:

harness:
  delegates:
    claude_code: on
    claude_code_path: ~/.local/bin/claude

The path must be absolute (~/ for your home folder is fine). Before it runs, the harness checks that it exists, is a regular executable file and is not inside the project, and that nobody else can change it: it belongs to you (or to the system), and neither it nor any folder above it (or above a link to it) can be written by other people; a folder writable by a group of yours is fine. Otherwise it refuses and says which of these failed. If the path is a link, the file it points to is what runs. A claude found on PATH inside the project is refused too.

Extra options for Claude Code #

claude_code_options adds options to the claude -p command, one per entry, written as --flag value (or --flag=value):

harness:
  delegates:
    claude_code: on
    claude_code_options:
      - --model sonnet
      - --effort high
      - --append-system-prompt Cite the file and line for every finding.

Only these are allowed, each with a check on its value:

OptionWhat it doesAccepted values
--modelThe model it usesAn alias such as sonnet or opus, or a full model name (letters, digits and . _ : @ / -)
--fallback-modelModels to try when the first is overloadedUp to 4 model names, comma-separated
--effortThe effort levellow, medium, high, xhigh or max
--max-turnsA lower turn limit for each run1 up to claude_code_max_turns (20 by default), never above it
--max-budget-usdStops a run at this estimated spendMore than 0, at most 1000
--append-system-promptText added to the end of its instructionsAt most 2000 bytes of plain text (line breaks and tabs allowed, no control characters)
--add-dirOne more folder it may readAn absolute path (~/ allowed) to an existing folder, at most 4; never /, a system folder (/proc, /sys, /dev, /run), your home folder (or a folder holding it), Claude Code's own folder, Maple's settings folder, or a place the sandbox hides (your keys and logins, the session's runtime folder, and your own sandbox.hide). When the run is contained by the sandbox, the folder must also be one the sandbox gives back (sandbox.extra_readonly, or /sandbox allow). With claude_code_project_settings: on, a folder holding a .claude folder is refused. A link is followed once, and the folder it points to is what is passed and shown. It is for reading: edits stay inside the project

Everything else is refused, with the reason. Some of the refused ones, and why:

  • --dangerously-skip-permissions, --permission-mode, --allowedTools, --disallowedTools, --tools: the harness sets what it may do from claude_code_access and your permission rules; these would replace that.
  • --mcp-config, --strict-mcp-config, --setting-sources, --settings, --plugin-dir, --agents: they would load servers, hooks, plugins or helpers you have not been shown.
  • --bare: it would stop using your Claude plan's sign-in.
  • --output-format, --input-format, --verbose, -p/--print: the harness sets how it talks to Claude Code.
  • --resume, --continue, --session-id: each run is a fresh session.
  • --system-prompt: it replaces Claude Code's own instructions, safety ones included; use --append-system-prompt.
  • Any option not in the table above.

The options go to Claude Code as separate arguments, never through a shell. --append-system-prompt text appears in the list of running programs on this machine while a run is going, like any command-line argument. Changing the options asks again before the next run in each project.

Neither claude_code_path nor claude_code_options can be set from a project's .mapleharness/config.yaml. Both are listed in /settings, and /settings set checks them the same way (it splits a list on commas, so text with a comma goes in config.yaml).

Checks before it runs #

Before its first run in a session, and again when the program or the options change, the harness checks that the program answers claude --version within a few seconds (asked in an empty folder of its own, or inside the sandbox when the sandbox applies), that the options pass the checks above, and that the sandbox would run it. The project must be one the harness trusts (below). If anything fails it stops with the reason, before asking you anything or starting a run. The question before the first run in a project shows what was checked: the program and its version, the options, and the access level.

Your Claude sign-in is not checked in advance: Maple never reads it. A run that is not signed in stops at once and says so.

maple-harness doctor has a "Delegate to your local Claude" line when it is turned on: the program it found, its version, and whether the options are valid. Doctor asks claude --version outside the sandbox, and checks the options against the folder you run it in.

How it is kept safe #

  • Only in a project the harness trusts. If the project has files the harness itself would run and you have not trusted them (maple-harness trust approve), it refuses. It also refuses in your home folder itself, and refuses a claude inside the project, whether found on PATH or named in claude_code_path.
  • The project's own Claude settings do not run. Claude Code in this mode runs a project's hooks and connects its .mcp.json servers without asking. So by default the harness starts it with only your own user settings (--setting-sources user), no MCP servers (--strict-mcp-config), and no skills or commands. To let a project's settings load, set claude_code_project_settings: on, after you have read what they run; a project whose files hold something that cannot be shown to you in full (plugins, for example) is then refused.
  • Read-only unless you widen it. By default it may only read and search files inside the project; it is told never to read the places the sandbox hides (your keys and logins) or Maple's own settings folder. claude_code_access: edit also lets it edit and write files inside the project, never its .git/hooks, .git/config, .claude folder, .mcp.json or .mapleharness folder. full also lets it fetch from the web, and run commands, but only when the run is inside the sandbox: a command is not held to those file rules. Your permission rules can only narrow all this: a tool your rules deny, or restrict for some arguments, is held back. In ask mode, anything beyond reading that your rules do not allow outright is put to you once for that run, because it cannot ask you for each change. Anything not granted is refused inside Claude Code rather than left waiting for an answer. Widening the access asks again before the next run.
  • In the sandbox when the sandbox applies. With the shell sandbox on (including sandbox.when_unattended in auto or yolo mode), it runs contained and needs the network (with sandbox.network: deny it refuses to start). Claude Code's own folder, ~/.claude, is given back to it, because its sign-in and session state are there, so the commands it runs can read that folder too; the parts of it that hold code (settings, CLAUDE.md, commands, agents, skills, hooks, plugins) stay read-only. If any of those change during a run, contained or not, the harness tells you, so you can check them before you next run claude yourself.
  • Bounded. It stops after claude_code_timeout_minutes (15) or claude_code_max_turns (20), and when its output grows past a cap. Esc, or stopping it from the agents list, stops it and everything it started. One run at a time, across all your sessions. Its output is cleaned of terminal control characters before you see it.

If it says Claude Code is not installed or not signed in, install it from Anthropic and run claude yourself to sign in, then try again.

Related: Commands and keys for the agents tray, and See and reduce what a task costs for why a subagent keeps your main conversation small.

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