CClawMetryDocs

Cost & usage

Reducing spend#

Four levers, in the order of how much they usually return.

1. Cache hit rate#

The largest lever, and nearly invisible without instrumentation. A cached prompt read costs a fraction of a fresh input token, and agent workloads are almost entirely re-read context.

bash
curl -s localhost:8900/api/efficiency/cache-hit-rate | jq
curl -s localhost:8900/api/usage/cache-trends | jq
curl -s localhost:8900/api/usage/cache-risk | jq

What breaks a cache: anything that changes the prefix. A timestamp in a system prompt, a file list that reorders, a memory document that is rewritten every session, a tool definition that varies. Each of those invalidates everything after it.

What to do: put the stable material first and the volatile material last. The cache-risk view shows sessions where a small change is invalidating a large prefix, which is exactly the list of things worth reordering.

A cache trend that is quietly degrading over weeks usually means a prompt is accumulating volatile content. That is the most common silent cost increase there is.

2. Model routing#

Not every task needs the largest model. The routing advisor looks at what your sessions actually did and identifies where a cheaper model would have produced the same result.

bash
curl -s localhost:8900/api/efficiency/routing-advisor | jq
curl -s localhost:8900/api/usage/optimization-recommendations | jq
curl -s localhost:8900/api/cost-optimizer | jq

The proxy can act on this automatically:

bash
clawmetry proxy config --action downgrade

Look at the Models tab before changing anything: latency and error rate matter as much as price. A cheaper model that fails and gets retried twice is not cheaper.

3. Context discipline#

Every token in context is paid for on every turn.

bash
curl -s localhost:8900/api/context-economics | jq
curl -s localhost:8900/api/usage/compression | jq
curl -s localhost:8900/api/context-anatomy | jq

Things that show up here repeatedly:

  • Whole files read when a grep would do. The Tools tab shows call counts;

a file-read tool with a very high count is usually this.

  • Memory documents that grew. They load on every session. An instruction

file that doubled in size doubled the floor cost of every run.

  • Repeated compaction. A session that compacts several times is paying for

the compaction and losing information. Usually solvable by loading less rather than by upgrading the model.

A cumulative token count is not your context size

Some runtimes report prompt_tokens as a sum across calls, which counts the re-read of context on every turn. That is billing-shaped, not context-shaped. ClawMetry keeps them distinct.

4. Eliminating work that produces nothing#

The lever nobody measures, and often the largest single number.

bash
curl -s localhost:8900/api/forward-progress | jq
curl -s localhost:8900/api/guard/actions | jq

Look for:

  • Sessions flagged no_progress — busy, no file changes
  • Sessions flagged stuck_loop — the same call repeatedly
  • Sessions with repeated_tool_failure — almost always a configuration problem

producing repeated paid retries

  • Scheduled jobs that have been failing quietly

A repeated_tool_failure is worth chasing first: it is cheap to fix, it is usually a wrong path or a missing credential, and it costs on every single run until someone notices.

Guard is the enforcement side of the same lever — a policy that pauses a looping session stops the spend at the point it becomes waste. → Policies and escalation

Measuring whether it worked#

Compare equal windows either side of the change:

bash
curl -s localhost:8900/api/local/aggregates | jq '.rows[-28:]'

Or ask the agent, which will do the comparison and read the sessions:

Using clawmetry, compare cost per session for the two weeks before and after the 1st. Tell me whether the change came from fewer sessions, cheaper sessions, or a better cache hit rate.

→ Self-diagnosis recipes

What not to bother with#

  • Micro-optimising prompt wording. Cache behaviour dominates it.
  • Chasing the cheapest provider. Retries and failures cost more than the

rate difference.

  • Turning off reasoning globally. It is expensive and it is often what makes

the difference between one attempt and four.

Tier#

cost_optimizer, per_run_waste_flags and per_run_compare are Pro features. The underlying cost and cache data is free.

Edit this page View as Markdown Report an issue
Cookie preferences