Saving money#

The cap limits what a task can spend. This page covers the tools that help the same budget go further: finding where spend went, advice on cheaper models, downgrading instead of refusing, the prompt cache options, trimming, and checking prompts before they are sent. It is for developers and team leads who want to lower their bill.

Important

Every option on this page is optional, and most are off by default. Whether one saves money depends on how your agents work, and some can cost more. Measure on your own traffic before you leave one on.

Find where the money goes#

Start with what you already spent. These read local files only, need no Lockpin running, make no network call, and print totals only, never what the logs say.

Command	What it shows
`lockpin waste-scan`	What the calls in this machine’s Claude Code session logs cost at API list prices, and what Lockpin’s cache options would have saved.
`lockpin plan`	Where a Claude Code or Codex subscription’s usage went: calls, tokens, cache share and API-equivalent dollars by window, model and session.
`lockpin import`	What Anthropic, OpenAI and Cursor billed, by key or person and model (Receipts, ledger and reports).

lockpin waste-scan -days 7
lockpin waste-scan -details
lockpin plan

waste-scan -details also shows repeated and very large tool results, per tool. -dir names the transcript folder (default ~/.claude/projects), and -skip skips transcripts whose path contains the given text.

Note

A proxy cannot cap a subscription. lockpin plan shows where its usage went.

Model advice and `lockpin suggest`#

Model advice is always shown. Some of an agent’s calls only read or search files (Read, Grep, Glob, read_file, list_dir and the like, never a shell command). Lockpin prices each of those again, with the same tokens, on the cheaper model the catalog names for its model, and the meter’s Model advice panel and the task’s details in VS Code say what it would have saved.

lockpin suggest goes further: it says when a whole task would have cost less on its model’s cheaper step in the catalog, priced from its own calls with the same tokens, and how sure that is. It is off until you turn it on:

{"flags": {"suggest-cheaper": true}}

Then:

lockpin suggest
lockpin suggest fix-login-bug

With no task, it shows the five tasks that would have saved most. A team admin can also turn it on in the dashboard.

Both are advice only: Lockpin never switches the model a call asks for. The price arithmetic is exact for the tokens used. What it cannot know is whether the cheaper model would have used the same tokens, needed more calls, or managed the task at all.

Downgrade instead of refuse#

When a call’s worst case does not fit the budget left, a downgrade rule can send it to a cheaper model instead, if that model’s worst case fits, so the agent gets a smaller model’s answer instead of a 402. Nothing is downgraded unless you list it.

When to use it: unattended work that should finish rather than stop (overnight runs, CI agents, batch jobs), and steps a smaller model handles (reading files, searching, small edits, summaries).

When not to: work where quality matters more than finishing, such as architecture, security review or a hard bug. A cheaper model can be less accurate or fail at a step the larger model would pass. Lockpin does not check the answer.

Add downgrades to your fallbacks file:

{"fallbacks": {"openai/gpt-6-sol": ["openai/gpt-6-luna"]},
 "downgrades": [
   {"from": "anthropic/claude-opus-*", "to": ["anthropic/claude-sonnet-*", "anthropic/claude-haiku-4-5"],
    "tasks": ["nightly-*"]},
   {"from": "openai/gpt-6-sol", "to": ["openai/gpt-6-luna"], "teams": ["research"], "keys": ["ci-bot"]}
 ]}

Start Lockpin with it, and restart after each change:
```
lockpin -fallbacks fallbacks.json
```

How the rules work:

from is a model as provider/model. One * matches any run of characters, and a * in a target stands for what it matched, so claude-opus-5-5 goes to claude-sonnet-5-5.
to is tried in order: the first target whose worst case fits is used, reserved at its own price.
keys, teams and tasks limit a rule to those calls. The first rule that matches is used.
A call that fits is never touched. A downgrade never raises a budget or a limit.
Downgrades come before asking at the cap: only a call no target can take is held and asked about.

Where you see it: the reply’s X-Lockpin-Downgrade (the model that answered), X-Lockpin-Downgrade-From and X-Lockpin-Downgrade-Skipped; the meter’s Downgraded column; and a downgrade line on the call’s receipt. An agent can refuse a downgrade for one call with X-Lockpin-Downgrade: off. A signed policy with "downgrades": false forbids them on the machine.

Anthropic’s prompt cache#

Anthropic caches nothing unless a call asks. These options apply to Anthropic’s own API only.

Option	Default	What it does
`-auto-cache-marker`	on	When a task’s previous call was less than 5 minutes ago, add the cache marker to calls that have none, so the next call reads its history at a tenth of the price. The reply carries `X-Lockpin-Cache-Marker: added`.
`-anthropic-cache-ttl`	`client`	`auto` moves a task to the 1-hour cache once it has paused past 5 minutes; `1h` does it for every call. The hour’s writes cost 2x instead of 1.25x.
`-cache-keepalive`	off	Keep an idle task’s cache warm for this long (for example `4h`, up to `8h`) by resending its last call every 55 minutes with an output limit of 1. Use with `-anthropic-cache-ttl auto` or `1h`.
`-cache-anchor`	off	Mark the system prompt too, so a trimmed or edited history keeps it cached.
`-cache-economics`	off	Let each task decide from its own pauses whether the 1-hour cache and keep-alive pay. Every reply explains the choice in `X-Lockpin-Cache-Plan`.

Keep-alive pings are priced and charged like a real call of the task. They stop at the cap, while the circuit breaker is open, and when a team key is removed, disabled or loses the model.

lockpin waste-scan shows what these options would have saved on your own logs before you turn one on.

Keep the prompt prefix stable#

Every provider’s cache reuses a request only up to the first byte that differs from the previous call. A tool list in a new order, a stray space, or a date on the first line of the system prompt re-bills the whole history every call.

-stabilize (off by default) fixes those on the wire, on every provider, without changing what the prompt means: tools are sorted by name and written the same way each time, the system prompt’s whitespace is normalised, and its lines that change per call (a date, a time, an id) move to its end. It never touches the conversation or tool results. The reply carries X-Lockpin-Prefix. Per request: X-Lockpin-Stabilize: on|off.

Why a call missed the cache#

After each call Lockpin compares it with the task’s previous call. When the call read less from the cache than it could have, the reply carries X-Lockpin-Cache-Miss with the reason, and the meter’s “Cache misses” column shows the count, what they cost and the latest reason.

Reason	What happened
`model changed`, `tool list changed`, `system prompt changed`	The start of the prompt changed, so nothing after it could be reused.
`history edited at item N`	The agent rewrote an earlier message.
`Lockpin trimmed history`	Trimming cut old tool results on purpose.
`idle 25m, past the 20m cache lifetime`	The task paused longer than the cache lasts.
`no cache marker`	An Anthropic call asked for no caching.
`provider evicted the cache`	Nothing changed; the provider dropped it.

Streams report usage at the end, so for them the reason only reaches the meter and the ledger.

Trimming old tool results#

Agents resend their whole history every call, and old tool output is often most of it. With -compact, Lockpin replaces old tool results with a one-line stub:

[lockpin removed an old tool result of about 2480 tokens to save cost. Call the tool again if you need it.]

Changing old history uncaches everything after the change, so Lockpin only cuts when it pays: at once when the cache is cold, and when the cache is warm only if the savings on later calls repay the cache it breaks, with a 2x margin. It never touches the newest results (-compact-keep, default 3), tools you list in -compact-exclude, or requests that use previous_response_id.

Warning

Trimming is off by default because, measured against an agent that sets its own cache marker, it has not paid: it can cost more, and a task that needs the old output pays twice, for the broken cache and the re-reads. Turn it on for an agent that sets no cache marker and reads large, disposable output, and check compact_saved_usd on the meter after a day.

Each response carries X-Lockpin-Compact (cut, sticky, waiting, none) and X-Lockpin-Compacted-Tokens. A request can opt in or out with X-Lockpin-Compact: on|off.

Two more cuts lose nothing. Both need -compact and are off by default:

-dedup replaces an exact repeat of earlier tool output with a pointer to the copy still in the history.
-stale-reads replaces an old read of a file that a later call edited with a one-line note.

Trimming changes what the model sees.

Carry the thread across /clear#

-handoff (off by default) adds a short note to a conversation that starts over in a task (a /clear, a compaction, a new session): the user’s own words, the plan, the files worked on and the last message, with secrets removed. It is only added to calls that name their task in X-Lockpin-Task. It changes what the model sees. X-Lockpin-Handoff: off skips it for one call.

Check prompts before they are sent#

The costliest part of a call is often what a prompt pastes or attaches, because it stays in every later call of the session. Lockpin’s hooks check before the call.

Preview the hooks for each agent Lockpin finds:
```
lockpin hooks install -dry-run
```

Install them. Each change is shown as a diff and written only after you answer yes:

lockpin hooks install
lockpin hooks install -agent claude-code -guard -lint

Hook	What it does
`review`	Prices a prompt before it is sent and blocks one that holds a secret or whose fixes would save at least $0.10 this turn (`-block-usd`) or 20,000 tokens (`-block-tokens`). Add `lockpin:ok` to a prompt to send it anyway; a secret always blocks.
`guard` (Claude Code)	Refuses a whole read of a file over 8,000 estimated tokens (`-tokens`) before it happens, with a reason the agent sees: read a range, or grep first. `-warn` makes it a note instead.
`lint` (Claude Code)	Warns about repeated and large messages, and when the prompt cache has expired.

Review a prompt file by hand:

lockpin hooks review -model claude-sonnet-5-5 -file prompt.txt

The review lists what to change, each with the tokens it would save: a secret, a long log (keep the first error and the lines around it), a big paste, an @path that attaches a large file whole, sentences already in CLAUDE.md or AGENTS.md, duplicates, and “read the entire codebase”. The rules are fixed, and nothing is sent anywhere. Its token counts are estimates. lockpin hooks uninstall removes the hooks.

Advanced: measuring the savings features#

These commands measure Lockpin’s own savings features on your traffic. Most people do not need them.

Command	What it does
`lockpin ab`	Reads the ledger of a Lockpin started with `-ab` (for example `-ab 'stabilize,compact=50%'`) and compares spend per call between the treatment and control arms, with a 95% interval.
`lockpin replay`	Replays calls recorded with `lockpin -record DIR` against local fakes, with each savings feature on and off. Nothing is sent anywhere.
`lockpin shapes`	Writes one shape file per session of local Claude Code or Codex logs: the sizes and times of each call and nothing more, for `replay`.
`lockpin gaps`	Shows the pause and calls-per-task tables Lockpin keeps from its ledger; `-check` tests them against the older rules.
`lockpin learn`	Trains two small pause models on this machine’s calls and keeps each only if it beats the gap tables. It sends nothing.