# Usage Cap Check: see the month coming before the agent bill does

> A free kit for providers who bill agent or model usage to clients, and for the owners who pay it. Write one plan with a monthly cap, alert points, a rule for going over and every job that spends. Copy usage from the provider's own export into a three-column log. A checker gives spend to date, the last 7 days' pace and where the month lands, flags jobs over budget, unplanned spend and jobs with no off switch, and turns each into one decision sheet the client owner answers in a single reply.

- URL: https://paperchasewebb.ai/bots/marketplace/items/usage-cap-check-see-the-month-coming-before-the-bill/
- Type: Prompt pack
- Category: Solo business
- By: PaperChaseWebb
- Works with: Claude Code, Codex, Grok Bot, Hermes (named in the listing); One Python script, a plan and log template, a fictional plumbing company example, and agent rules for each harness. Tested on Linux
- Price: Free USD
- Difficulty: Beginner
- Setup time: 15 min
- Time to result: First status line in about 15 minutes
- Format: Markdown (.md) file, usage-cap-check-see-the-month-coming-before-the-bill.md
- Version: 1.0, updated 2026-11-03
- License: Personal and commercial use.

## What you end up with

No surprise at month end: the client owner sees the projection early and decides, in one line, what happens near the cap.

## What you get

- The method: one cap and one over-cap rule agreed before the month, a weekly count, a decision before the cap, not after
- usagecap.py: 5 plan checks, 4 findings (heading over the cap, job over its daily budget, unplanned job, no off switch) and 4 reply checks
- A one-page usage sheet with spend, pace, month-end projection, spend by job and a one-line reply
- Owner decisions refused inside an agent session, from anyone but the client owner, or after the plan or the log changes
- AGENTS.md, CLAUDE.md, a Grok Bot standing order and a Hermes skill, a fictional example, and 28 tests

## Who it is for

Providers who bill usage and want no month-end surprises, and owners who want to see the bill coming.

## Tools needed

- Python 3.8 or newer: usagecap.py: plan check, spend and pace, month-end projection, decision sheet, owner reply and action list; standard library only
- Grok Bot, Claude Code, Codex or Hermes (optional): copies usage rows from the provider's export, runs status and sends the sheet under AGENTS.md; never records decisions, pauses a job or touches a bill
- You need: Python 3.8 or newer
- You need: The provider's usage export (any format you can copy date, job and dollars from)

Cost to run: Free. Python is free.

## How it works

1. **Run the example.** Unpack the file and run python3 usagecap.py status example/plan.json --today 2026-11-14. Expected: $171.90 spent of $300, month end near $409, 4 findings.
2. **Write your plan.** Fill in templates/plan.json with the cap, alert points, over-cap rule and every job that spends, then copy rows into the usage log. Expected: usagecap.py check shows plan OK.
3. **Sheet and send.** Run sheet and send usage-sheet.md to the client owner. Expected: usage-sheet.md with one numbered item per finding.
4. **Reply once, then act.** The client owner answers in one line at their own terminal, then run plan and hand usage-actions.md to the provider. Expected: usage-actions.md with only the approved steps, each with a done test.

## Sample prompt: Weekly usage check (Grok Bot, Claude Code, Codex, Hermes)

```
Follow AGENTS.md. Copy last week's rows from the provider's usage export into the log, run usagecap.py status, and if it needs a decision, run sheet and send the client owner usage-sheet.md with the reply line. Do not pause a job, change a limit, raise the cap or edit the plan.
```

One prompt.

## Free preview of usage-cap-check-see-the-month-coming-before-the-bill.md

````markdown
# Usage Cap Check

**Know where the month will land before the bill does. One plan with a cap and a rule for going over, a log copied from the provider's usage export, and a one-page sheet the client owner can read and answer in one line.**

Version 1.0, 2026-11-03. By PaperChaseWebb Inc. Free. Works with Grok Bot, Claude Code, Codex and Hermes, or by hand. Python 3.8 or newer, no installs.

## The problem

Agent work is billed by use, and use drifts. A follow-up job starts running twice a day. Someone adds a research task that was never in the plan. Nobody notices until the invoice, and then the conversation is about blame instead of choices.

The fix is boring and it works: agree a cap and a rule before the month starts, count against it every week, and ask the client owner before the cap, not after.

## What you get out of it

- One plan: the monthly cap, alert points, what happens at the cap, and every job that spends with its priority, daily budget and off switch.
- A status line any time: spent so far, the last 7 days' pace, and where the month ends at that pace.
- A one-page usage sheet in plain words, with a numbered decision per problem and a reply line like `1: pause 2: limit 3: add`.
- An action list of only what the client owner approved, each with a done test.

## Who it is for

Providers and small agencies who bill agent or model usage to clients and want no surprises at month end. Owners who pay for that usage and want to see it coming.

Not a billing system. I
````

## Test record

- Date: Nov 3, 2026
- What was run: tests/test_usagecap.py (28 tests) unpacked from the pack file and run fresh on Linux, Python 3.8, 3.9, 3.11, 3.12 and 3.13; check, status, sheet, reply and plan on the fictional example.
- Result: 28 passed, 0 failed on all five versions; the example gives $171.90 spent of $300, a month-end pace near $409 and 4 findings; decisions refused in agent sessions, without a terminal, for the wrong name and after a plan or log edit; the plan and log are never modified.
- Not run: macOS or Windows. Real provider usage exports. A live Grok Bot, Claude Code, Codex or Hermes session.

Copied from this item's dated test notes. What was not run stays in.

## Worth knowing

- It knows only what the log says. Copy rows from the provider's own export; a missing row is missing spend.
- The month-end figure is the last 7 days' pace carried forward, not a quote.
- On 2026-11-03: 28 tests passed on Python 3.8, 3.9, 3.11, 3.12 and 3.13 on Linux, run from the files unpacked out of the pack. Agent rules guide; they were not loaded inside each harness for this release.
- Not accounting or legal advice, and not a substitute for the usage terms in a contract.

## Questions

**Does it connect to my model provider?** No. It reads a three-column CSV you or your agent copy from the provider's usage export. That keeps it safe to hand to an agent.

**Can my agent pause a job when the cap is close?** No. It drafts the sheet and the action list. Recording decisions is refused inside an agent session, and the tool never pauses a job or changes a limit.

**What if the client never replies?** Every unanswered item holds, and the over-cap rule written in the plan applies when the cap is reached.

**What should I pair it with?** Retainer Scope Sheet ($29) itemizes what the monthly covers, and Agent Cost Levers ($24) cuts cost per solved task on the jobs that run over.

## How to get it

Free sample. Download it directly at https://paperchasewebb.ai/bots/marketplace/items/usage-cap-check-see-the-month-coming-before-the-bill/, no signup.

Seller: PaperChaseWebb Inc., mgmt@paperchasewebb.com