The meter and the desktop overlay#

The meter is a local web page that shows every task’s spend as it happens. The overlay is a small island at the top of a Windows screen that shows the running task and asks Lockpin’s questions. This page describes both, for anyone who watches agents spend.

Open the meter#

The meter is served by Lockpin itself while it runs:

http://127.0.0.1:8787/lockpin/

Or let Lockpin open it in your browser:

lockpin -open

The page refreshes every second and pauses while its tab is hidden. The top right says when its numbers are from, on a 24-hour clock with the zone (“As of 21:57:32 EST”).

Important

The meter has no login. Keep -listen on localhost unless team mode (-keys) is on.

Simple and Detailed views#

Simple fits on one screen and shows:

The summary cards: Total spend · all time on this machine and, only when they apply, the on-goal share, Lockpin saved (what Lockpin’s own features saved, each net of what it cost), Refused (calls refused at the budgets you set, and the most they could have cost), cache writes, and the cost of rebuilds after an expired cache.
The task that spent most, with chips for the breaker and recent alerts.
Spend over time: what every task spent per minute (last hour), per 15 minutes (24 hours), per hour (7 days) or per 6 hours (30 days). It is read from the ledger, so it survives a restart.
A one-line goal summary and Top tasks by spend, each as spent of budget (“$0.78 of $1.00”).

Detailed adds every table: tasks, goal steps, drift findings, keys, breaker, tags, alerts.

To	Do
Switch views	Press `d`, or open `?view=simple` or `?view=detailed`. Settings (the gear) can turn the shortcut off.
Change the theme	Settings → Theme: System, Light or Dark.
Open one task	`/lockpin/#task=<id>`, with the id encoded (`#task=alice%2Ffix`).

Your choice of view is remembered in this browser.

The Tasks table#

The Tasks table (Detailed) lists 50 tasks at a time.

Find filters by name. Sort orders by most recent, most spent or name. Show all lifts the 50.
Edit next to a budget sets that task’s budget. 0 leaves the task with no task budget.
The Left column shows the dollars left and, under them, about how many more calls the budget pays for at the task’s recent rate.
The Downgraded column counts calls served by a cheaper model, and Cache misses counts calls that read less from the cache than they could have, with the latest reason.

A link to #task=<id> switches to Detailed, marks the task’s row, scrolls to it, and puts the task’s spend, budget and calls above the table, as of when they were read. An unknown id gets “No such task”.

Other panels#

Panel	What it shows
Approvals banner	Calls held at the cap (Call needs approval) or in a loop, with their buttons (Approvals at the cap).
Alerts	The latest 20 alerts, even with no Slack or webhook set. Loosenings are marked loosened.
Spend-rate breaker	The circuit breaker’s switch, settings, and what is tripped, with a reset button.
Spend by tag	Each tag value’s spend today, this week, this month and in total.
Model advice	What routine read-and-search calls would have cost on a cheaper model (Saving money).
Drift and Against the goal	Drift tracking’s sessions, findings and goal view (Loop checks and drift).

Pause from the meter#

Detailed offers 15 min and 1 hour at the top. Calls then pass through without a cap and still count, up to 8 hours a day. The × hides the offer for that tab. Settings (the gear) keeps the same buttons, and Resume now while a pause is on.

When something fails#

A panel that cannot update says so, with the time of the numbers it still shows and a Retry button.
If Lockpin stops answering, a notice at the top says Can’t reach Lockpin, the time of the numbers shown, and that the page retries every second.

Team mode#

Admin key. Changing keys, teams or invites asks once for an owner or admin key, which stays in that tab until it closes.
Members’ view. Each developer can open /lockpin/me on the address their agents use and enter their own Lockpin key. They see only that key: spend against its limits, its tasks (top 50 by spend), its users, whether the breaker has paused it, and its alerts. It is read-only.

The meter’s API#

The page reads a small JSON API under /lockpin/api/. Tools on this machine can read it too:

Route	Gives
`GET /lockpin/api/summary`	Totals across every task.
`GET /lockpin/api/spend?range=1h\|24h\|7d\|30d`	The chart’s spend per step, oldest first.
`GET /lockpin/api/tasks`	Tasks; takes `sort=recent\|spent\|name`, `q=` and `limit=`.
`GET /lockpin/api/tasks/<task>/receipts`	A task’s recent receipts.
`GET /lockpin/api/projects`	Each project’s spend and limits.
`GET /lockpin/api/tags?name=env`	Spend by one tag.
`GET /lockpin/healthz`	Health, for a supervisor. Needs no key.

The desktop overlay#

The overlay is a small island at the top of the screen on Windows. It shows the running task’s spend against its budget and answers Lockpin’s questions there: allow this call, raise the budget, stop, or let a loop run. It reads only the meter on 127.0.0.1 and never calls a model provider.

Install the overlay#

The Windows installer, Lockpin_<version>_x64-setup.exe, installs Lockpin and the overlay together.

Download the installer and the .sha256 file next to it.

Compare the hash before you run it:

Get-FileHash .\Lockpin_<version>_x64-setup.exe

Double-click the installer. It installs for your user only and asks for no admin rights. Until releases are code-signed, SmartScreen warns about it: choose More info, then Run anyway, only for a file whose hash you checked.

The overlay starts at once and at every sign-in. The Start menu entry Lockpin opens it; open the meter with lockpin -open.

What it shows#

State	What you see
Calm	A pill with the task and what is left of its budget. Hover it for the detail card.
Asking	A call is held at its budget: Call needs approval (Near cap: call needs approval from 75% used), with Allow this call, Raise budget and Stop, the amount under each and when the hold ends. Once the hold ends, the card says Call refused and offers Allow next call.
At cap	With nobody watching, a refused call turns the pill amber (“at cap · $0.50 budget” or “2 refused”).
Pace	The meter’s forecast says a task reaches its budget within about 5 minutes (medium or high confidence only): the island opens for 6 seconds.
Unusual spend	Lockpin raised an unusual-spend alert for a task: the island opens the same way.
Catch	A loop is held (Stop and Let it run), or the breaker or drift tracking raised an alert.
Recap	A task the overlay saw running has had no call for 5 minutes: a card sums up its spend, savings and events.
Off	`Can't reach Lockpin · start it with lockpin service start`. The overlay never starts anything itself.

Pace and unusual-spend cards show at most once per task per kind an hour.

Keyboard and mouse#

Win+Shift+L gives the card the keyboard. With no card waiting, it opens the Ask about spend box.
Arrows or Tab move along the buttons; Enter or Space answers.
Allow… and Raise budget need two presses: the first turns the button into Confirm +$X, a second press within 5 seconds sends it.
A card ignores clicks and keys for its first 400 ms.
Drag the island to move it; it snaps to a grid of spots on each monitor.

Ask a question about spend#

Win+Shift+L (with no card waiting), or Ask about spend on the detail card, opens a text field. Type a question such as “most expensive agent today?” and press Enter. The words are matched to a fixed set of questions and answered from this machine’s meter only. No model is called, and every answer ends with “as of” and the time it was read.

Presenting#

Presenting in the tray menu, or Win+Alt+P, hides the island from screen sharing and recordings at once. You still see it. Keep presenting on at start keeps it on at every start. This needs Windows 10 version 2004 or later. A camera pointed at the screen still sees it.

It counts as watching#

While the overlay runs, a call at its task’s budget is held and asked about for up to -ask-at-cap, even if nobody is at the screen. Unanswered, a held budget call is refused (402), so the cap still holds; an unattended agent just waits longer for it. A held loop call goes on.

Settings#

The file is %APPDATA%\dev.lockpin.overlay\overlay.json. Every field is optional. Quit the overlay, edit the file, then start it again.

{"hide_from_capture": false, "watch": true, "shortcut": "super+shift+L",
 "nudges": true, "nudge_cooldown_minutes": 60, "presenting_shortcut": "super+alt+P"}

Field	Default	What it does
`watch`	`true`	`false`: the overlay never reads the questions, and Lockpin no longer holds calls on its account.
`nudges`	`true`	`false`: no pace or unusual-spend card pops up.
`nudge_cooldown_minutes`	`60`	How long before the same task’s card of the same kind can show again, 1 to 1440.
`recap`	`true`	`false`: no recap card pops up when a task goes idle.
`hide_from_capture`	`false`	`true`: presenting is on at every start.
`shortcut`	`"super+shift+L"`	The shortcut that gives the card the keyboard. It must include Win.
`presenting_shortcut`	`"super+alt+P"`	The shortcut that turns presenting on and off.

Uninstall the overlay#

Uninstall from Settings > Apps > Installed apps > Lockpin. It removes both programs, both sign-in tasks, the PATH entry and the shortcuts, and keeps %LOCALAPPDATA%\Lockpin (your spend history and the log).