Use it with herdr #
On this page
herdr hosts terminal sessions for coding agents and shows, for each pane, whether the agent in it is working, waiting for you, or idle. Maple Harness works with it without any setup.
In plain words #
- What it is. herdr shows, for each terminal pane, whether the agent in it is working, waiting for you, or idle.
- What to do. Nothing: start Maple inside a herdr pane and the pane shows its state.
What you need to do #
Nothing. Start maple-harness (or mpl) inside a herdr pane and the pane labels itself maple-harness and shows
its state as it changes:
| State | What it means |
|---|---|
| working | a turn is running |
| blocked | it is waiting for you to approve a tool call |
| idle | it is waiting for your next message |
The harness tells herdr itself, over herdr's local socket, and clears the label when it exits, so a pane is never left labelled by an agent that has gone. On a machine without herdr nothing happens and nothing is printed.
Tested with herdr 0.9.0. Other versions should work, because it only uses herdr's public socket, but they haven't been tried.
If the pane does not pick it up #
- Check that you started the harness from a shell inside the herdr pane (not a separate terminal window).
- If herdr uses a non-default socket, make sure
HERDR_SOCKET_PATHpoints at it in the environment the harness inherits. By default it looks in~/.config/herdr/herdr.sock. - Run
maple-harness versionto confirm you are on a current build, then start a new session.
The terminal signals, with or without herdr #
Independently of herdr, the harness sets the window title and the terminal's progress indicator on every change of state, and sends a notification when a turn finishes or needs a decision. Terminals that do not support one of these ignore it.
| State | Window title | Progress indicator |
|---|---|---|
| idle | ● MapleHarness | cleared |
| working | ✳ MapleHarness — working | busy |
| needs approval | ⏸ MapleHarness — needs approval | warning |
| done | ✓ MapleHarness — done | cleared |
| failed | ✗ MapleHarness — failed | error |
WezTerm, Ghostty and Windows Terminal show the progress indicator on the tab. Any terminal shows the title.
The detection manifest (advanced) #
herdr can also classify a pane from a detection manifest. Most people do not need this, because the harness reports
its own state. If you want the manifest anyway, maple-harness herdr-manifest prints it, and
maple-harness herdr-manifest --id <name> writes a different agent id into it. Whether your herdr version loads
manifests for agents it does not ship with depends on the version, and this path has not been tested beyond herdr
0.7 and 0.9.
Turning the installer's herdr step off #
The installer needs to install nothing for herdr. --no-herdr is accepted and ignored, so older install commands
keep working.
Related: terminal notifications and their settings are in Harness settings, and
the herdr-manifest command is in Commands and keys.