@blocksifr/modelmeter

The AI Compute Savings Layer foundation for ModelMeter: the pre-execution cost gate + waste engine (waste.ts), a hash-chained session ledger, the anti-fake-savings engine, AI Workflow Receipts, and the modelmeter CLI. Shared by every capture surface (browser extension, CLI, MCP proxy, GitHub App).

Stop wasting tokens — cut AI compute cost before the model runs. Token trackers measure the bill; ModelMeter lowers it.

See docs/modelmeter/README.md for the product category, the anti-fake-savings acceptance criteria, and the roadmap.

CLI quick start

npm install -g @blocksifr/modelmeter
modelmeter scan                       # instant local waste report, no setup
modelmeter scan --badge               # README badge Markdown
modelmeter init                       # create .modelmeter/ (metadata-only)
modelmeter trace --test -- npm test   # record a hash-chained receipt + tests_passed
modelmeter report --out report.md     # savings totals + shareable Markdown
modelmeter mcp --server-id fs -- npx -y @modelcontextprotocol/server-filesystem .
modelmeter connect github             # link the repo + wire the PR waste report

Metadata only: model names, endpoints, token counts, and non-reversible hashes — never prompts, responses, code, or files. See how we calculate for the exact formulas.

API

import {
  Ledger,
  buildReceipt,
  verifyReceipt,
  summarizeSavings,
  assertSavingsClaim,
  classifySavings,
} from "@blocksifr/modelmeter";

const ledger = new Ledger();
ledger.append({ type: "model_call", sessionId: "s1", payload: { model: "claude-opus-4-8", estimatedUsd: 0.42 } });
ledger.append({ type: "verification", sessionId: "s1", payload: { signal: "tests_passed" } });
ledger.append({
  type: "savings",
  sessionId: "s1",
  payload: { label: "verified", amountUsd: 1.5, basis: "reuse avoided re-run", verification: ["tests_passed"] },
});

const receipt = buildReceipt(ledger, { workflowType: "coding", title: "Checkout fix" });
// receipt.savings.verifiedUsd === 1.5, kept separate from estimated/actual/opportunity.
// A `verified` claim with an empty `verification` array throws FakeSavingsError.

Pre-execution cost gate + shareable waste report:

import { CostGate, contextHash, buildWasteReport, renderWasteReportMarkdown } from "@blocksifr/modelmeter";

const gate = new CostGate();
gate.inspectPrompt({ model: "claude-opus", tokens: 300 });            // → expensive_model_choice
const h = contextHash(systemPrompt);
gate.inspectPrompt({ model: "claude-sonnet", tokens: 4000, contextHashes: [h] });
gate.inspectPrompt({ model: "claude-sonnet", tokens: 4000, contextHashes: [h] }); // → repeated_context

const report = buildWasteReport({ aiSpendUsd: 41.2, signals: gate.signals(), savings });
// report.avoidableWasteUsd is the primary metric; labels stay separate.
const markdown = renderWasteReportMarkdown(report);

Viral scan + README badge

modelmeter scan is the no-setup wedge: it scans repo metadata, estimates oversized/repeated context risk, flags premium-model overuse references, and prints a shareable Markdown report. It stores no prompts, responses, code, or files.

npx -y @blocksifr/modelmeter scan
npx -y @blocksifr/modelmeter scan --out modelmeter-report.md
npx -y @blocksifr/modelmeter scan --badge

The badge is designed for README virality:

![ModelMeter AI waste](https://img.shields.io/badge/AI%20waste%20avoided-$4.00-006E7F?labelColor=14202B)

The headline is always avoidable waste. Verified savings only appear when backed by evidence.

GitHub PR reports

Aggregate a PR's captured receipts into one waste report and upsert it as a PR comment, tying AI cost and savings to the real merge/CI outcome. Estimated, opportunity, actual, and verified savings stay separate — nothing is labelled verified without evidence. Metadata only.

# print the Markdown report (and write it to a file)
modelmeter github report --dir .modelmeter --out report.md

# create/update the ModelMeter PR comment in place (idempotent via a hidden marker)
modelmeter github report --post --repo owner/name --pr 42 --token "$GITHUB_TOKEN"

In GitHub Actions, --repo, --pr, and --token fall back to GITHUB_REPOSITORY, GITHUB_REF, and GITHUB_TOKEN.

modelmeter connect github links the repo (resolved from your git origin), verifies token access (flag / GITHUB_TOKEN / gh CLI), writes .modelmeter/github.json, and prints the CI step. Pass --pr N with a token to post a test comment immediately.

Scripts

npm run build      # tsc -> dist (also builds the `modelmeter` bin)
npm run typecheck  # tsc --noEmit
npm test           # vitest (ledger, savings, receipt acceptance tests)
npm run dev -- init          # run the CLI from source via tsx