Overview #
Maple Harness is a coding agent for GitHub Copilot's models, Claude and models on your own machine. It comes in three parts:
- The agent,
maple-harness: the program you work with in a terminal. It reads your project, edits files and runs commands, and asks before it changes anything. - The proxy,
maple-proxy: holds your sign-ins and talks to the models, for the agent and for any other tool that speaks the OpenAI or Anthropic API. Its setup page is where you sign in and change settings. - The phone page: share a session and drive it from your phone's browser, or from another computer.
On a Mac with Apple silicon there is also a small helper for Apple's on-device model, which the proxy starts when it is needed.
In plain words #
- The agent is where you work: type what you want done in a terminal, and it reads, edits and runs, asking first.
- The proxy holds your accounts and models. Its setup page, at
http://127.0.0.1:11539, is where you sign in and change settings, with nothing to edit by hand. - Your phone can follow a session and approve what the agent asks.
- Curious what makes it different? What's inside Maple describes the capabilities in plain words.
Start here #
- Install the programs.
- Run Your first session.
- Sign in to GitHub Copilot or Claude, or Connect a model server such as Ollama or LM Studio.
- Choose a model, or let the agent choose for each message.
Get started #
Installing, signing in and connecting models.
- What's inside Maple: what it does for you behind the scenes, and why it helps.
- Install: the one-line installer, platforms, updating and removing it.
- Upgrading to 2.0: what keeps working, what is new, and how to go back to 1.x.
- Which setup do I need?: one laptop, a laptop joined to a team hub, a team hub, chained hubs, several replicas, or CI: what each gives you and where its steps are.
- Your first session: start the proxy and the agent, and the first commands to know.
- Sign in: GitHub Copilot, an Anthropic API key, and more than one account.
- Azure and Google Cloud: Azure OpenAI, Microsoft Foundry and Vertex AI with your cloud sign-in.
- Amazon Bedrock: Claude, Nova, Llama and more in your AWS account, with your AWS credentials.
- Connect a model server: Ollama, LM Studio, oMLX, Lemonade, Unsloth or any OpenAI-compatible server.
- Choose a model: switch models, let the agent choose, and set a default.
Guides #
How each part works, and how to use it with other tools.
The agent
- Subagents: hand small jobs to helper agents, or make your own.
- Language servers: compile errors right after every edit.
- Search by meaning: let the agent find things by what they mean, not only the words.
- The shell sandbox: contain the commands the model runs, and what that breaks.
The proxy
- The proxy and its setup page: what it listens on, the setup page and the settings you may want.
- Keep it running in the background: run the proxy and the phone gateway as a service.
Your phone
- Control it from your phone: pair a phone, approve tool calls, start sessions and share one read-only.
Other tools
- Use your models from other tools: point Claude Code, OpenCode or another tool at the proxy.
- What the proxy adds for other tools: what those tools gain from it, and what stays in the agent.
- Give other tools this project's knowledge: the MCP server.
- Drive it from another program: a script, an editor plugin or CI.
- Use it with herdr: see the agent's state in a herdr pane.
Cost and usage #
Where the spend goes, how to keep it down, and how to check any claim on your own tasks.
- See and reduce what a task costs: start here.
- What /cost tells you: each part of
/cost, and what to do about it. - Settings by goal: the setting for spending less, keeping quality or stopping runaways.
- See and filter your usage: ask the usage log questions, filter exports, ready-made DuckDB views and the events log.
- Provider health: how each provider and model is answering on your traffic, and optional failover.
- Metrics and telemetry export: Prometheus
/metrics, OpenTelemetry and audit lines for your monitoring and security tools; off until you turn it on. - Your usage data: query and export the usage log, or wire it into Grafana.
- Check it yourself: how to test a setting on your own work.
- Measure with bench: repeated, paired runs of your own tasks with a spending cap.
Your data
- Your data: where it lives and how to query it: the daily files, PostgreSQL and the lake, and which to use when.
- Query your usage: tested recipes for
usage query, DuckDB and spreadsheets. - The Maple data lake: keep your whole usage history in a DuckLake, on one machine or for a team.
Reference #
Every command, key and setting, with what it does, its default and its trade-off.
- Commands and keys: slash commands, keys, modes and shell commands.
- Harness settings: every
harness:setting inconfig.yaml. - Proxy settings: every proxy setting, setup-page card, command and response header.
Help #
When something does not work, and the rest.
- Troubleshooting: common problems and their fixes.
- Security: what it can touch and how to keep it safe.
- Glossary: the words these pages use.
- Licence.
- Release notes, with the downloads.