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.

What the proxy adds for other tools #

On this page
  1. In plain words
  2. At a glance
  3. One address for many models
  4. Keeps going when an account runs out
  5. Budgets
  6. See what each tool spends
  7. Prompt cache
  8. Settings you can turn on
  9. Using it from another machine
  10. What stays in Maple Harness
  11. Measure it yourself

Claude Code, OpenCode, pi, GitHub Copilot CLI and Hermes can send their requests through the Maple proxy instead of straight to a provider. Use your models from other tools has a tested setup for each. This page says what they get from it, and what stays in Maple Harness.

Other tools that speak the OpenAI or Anthropic API can use the same addresses. There is no tested setup for them here.

Everything below describes what the proxy does. Nothing here is a promise about your bill.

In plain words #

  • What it is. Claude Code, OpenCode, pi, Copilot CLI and Hermes can send their requests through the Maple proxy instead of straight to a provider.
  • Why you want it. They get every model the proxy serves, its fallbacks when an account runs out, its budgets, and their usage on the same charts as Maple's.
  • What to do. Point the tool at the proxy's address (the setup page's header shows both); the tested lines for each tool are in Use your models from other tools.

At a glance #

What each tool sent was checked with Claude Code 2.1.284, OpenCode 1.18.33, pi 0.87.1, Copilot CLI 1.0.89 and Hermes Agent 0.19.0. Other versions may send different headers or cache marks.

Claude CodeOpenCodepiCopilot CLIHermes
Every model the proxy servesYesYesYesYesYes
Aliases, fallbacks, budgetsOnce you set themOnce you set themOnce you set themOnce you set themOnce you set them
auto, auto-heavy, auto-medium, auto-lightYesYesYesYesYes
Usage log, Cache and Savings cardsYesYesYesYesYes
Its name in the usage log's agent columnclaude-codeopencodeotherotherother
Sessions cardNoNoNoNoNo
Cache marks for Claude modelsIts own, and the proxy'sThe proxy'sThe proxy'sThe proxy'sThe proxy's
Prefix stabiliserLeft aloneOn by defaultOn by defaultOn by defaultOn by default
Image shrinking, snapshot trimmingOnce you turn them onOnce you turn them onOnce you turn them onOnce you turn them onOnce you turn them on
Response cacheNoNoNoNoNo

Each row is explained below.

One address for many models #

The tool asks for a model by name, and the proxy sends the request to whichever provider serves it: your GitHub Copilot account, an Anthropic account, or a model server such as Ollama, LM Studio or oMLX. The proxy translates between the two APIs in both directions. Claude Code, which speaks the Anthropic API, can use a Copilot model or a local one. OpenCode, pi, Copilot CLI and Hermes, which speak the OpenAI API, can use a Claude model from an Anthropic account.

Give the tool a name the proxy lists (curl http://127.0.0.1:11535/v1/models), or an alias from model_aliases. You can then change which model an alias means without touching the tool. See Model aliases.

A tool can also ask for the proxy's auto mode: with the model auto, the proxy looks at each request and sends it to a heavy, medium or light model; auto-heavy, auto-medium and auto-light fix the weight. Each means a model and its fallbacks, from your provider's own ranking unless you choose them on the setup page's Auto mode card. The proxy judges from the request alone, so it does not know what the tool meant; X-Maple-Router says how it weighed a request and X-Maple-Served-By which model answered. The proxy's log, the usage log and both headers are described in See what auto chose.

A tool can also ask for github-copilot/auto, where GitHub Copilot itself picks the model for each request, when your Copilot account offers it. The X-Maple-Served-By header says which model Copilot picked. It can also be the model for a weight of auto mode, chosen on the setup page's Auto mode card. See Copilot Auto.

Keeps going when an account runs out #

Fallbacks apply to every request through the proxy, whatever tool sent it. With model_fallbacks, a model that cannot answer (out of chats or credit, overloaded, unreachable) hands the request to the next name on its list. provider_fallbacks moves one account's requests to another account. A model that has just said it is out of quota is tried last for the next hour, so the tool does not wait for the same refusal on every request.

A fallback happens only before any output reaches the tool, and never for bad credentials or malformed requests. The usage log's fallback column and the X-Maple-Served-By response header say which model answered. See Fallbacks.

Budgets #

A daily limit on a provider (requests, AI units, or both) counts every request to that provider through the proxy, whichever tool sent it. At the limit, requests are refused or handed to a fallback. See Daily budgets.

See what each tool spends #

Every request through the proxy gets one line in the usage log: the model asked for and the model that answered, tokens in and out, tokens read from and written to the cache, AI units when the provider reports them, and estimated cost and savings columns. The log keeps counts and labels, never prompts or answers. You can query it with DuckDB, or export it to CSV or Parquet (Your usage data).

To tell tools apart:

  • agent is taken from the tool's User-Agent. Claude Code shows as claude-code and OpenCode as opencode. pi, Copilot CLI and Hermes show as other.
  • client is the label of the access token a tool used. That is the reliable way to separate tools on other machines, or two tools that both show as other: give each one its own token.

The Cache card (hit rate and cache tokens, per model and per client) and the Savings card (what the proxy's own settings saved and cost, each figure marked measured or estimated) include these tools' requests. The Sessions card does not. It groups requests by a session id that Maple Harness sends and these tools do not.

Prompt cache #

Providers charge less for the start of a request they have already seen. For Claude models, reached through an Anthropic account or through Copilot, the provider caches only the parts of a request that are marked for caching. The proxy marks them (prompt_cache, on by default):

  • Claude Code marks its own system prompt. The proxy keeps those marks and marks the conversation too.
  • OpenCode, pi, Copilot CLI and Hermes, on the OpenAI-compatible address, get the proxy's marks.

The prefix stabiliser (prefix_stabilizer, on by default) keeps the start of each request the same from turn to turn, so a provider's cache can keep matching it. It works with any provider, and each response that it changed carries X-Maple-Prefix-Stabilized. It leaves a request alone when the tool marks its own cache points, so it does not touch Claude Code's requests.

Whether a request hit the cache is in the usage log and on the Cache card. See Caching.

Settings you can turn on #

These are off by default. When on, they apply to every tool.

  • Image shrinking (image_resize_tool, image_resize_user, image_superseded) sends smaller images. Small text in a screenshot may become harder to read.
  • Snapshot trimming (snapshot_trim) shortens browser page snapshots from Playwright MCP. It only acts on results it recognises as snapshots.
  • Trim old tool results (context_trim) replaces old, large tool results in long conversations with a short note. The model can no longer see what was trimmed.
  • Context guard (context_guard) drops the oldest turns, or refuses the request, when a request is too big for the model's window.

See Images and browser snapshots and Guards.

The response cache (response_cache) is different. It answers only requests that carry the header X-Maple-Cache: allow, and none of these tools send it. It also never answers a request whose last message is a tool call or a tool result, and in an agent's loop most requests end with one.

Embeddings are served at http://127.0.0.1:11535/v1/embeddings, for any tool or script that asks for them. See The proxy's cache.

Using it from another machine #

To reach the proxy from another machine, give the tool an access token as its API key, in place of the placeholder. The token's label then names the tool in the usage log's client column. The setup page itself is reachable only from the proxy's own machine, and you can protect it with a password. See Using it from another machine.

What stays in Maple Harness #

These belong to the agent, not the proxy. Pointing another tool at the proxy does not give it any of them:

  • history_search over earlier conversations, and the session journal of what each turn read, changed and ran.
  • Memory notes and the project index as the agent uses them: recalled during a turn, and kept current after each edit. Other tools can reach the notes and the index through a separate server: Give other tools this project's knowledge.
  • The shell sandbox, permission modes and file-access rules.
  • /model auto, which picks a model for each message.
  • /cost and /savings for one session, and the Sessions card, which needs the session id the agent sends.
  • Remote control from your phone.
  • Subagents.

Measure it yourself #

The measured comparison on this website is between Maple Harness and Copilot CLI. What the proxy changes for these tools on their own has not been measured, so this page gives no figure.

To measure it on your own work, use 0. It can run another tool as one arm, with the same tasks and the same check, several times each: for example, the same tool once pointed at your model server directly and once at the proxy. The usage log shows what each request through the proxy cost.

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