How to Control AI Code Review Costs: Spend Limits and Run Limits

Controlling AI code review costs is the objection that usually arrives second, right after "does it actually catch bugs?" It is a fair objection. Usage-based pricing means a runaway configuration costs money rather than just wasting time, and "an AI agent that can push commits" is a sentence that should make anyone ask about ceilings.

The honest answer is that cost control in AI code review is a configuration problem with a small number of specific knobs. This guide covers each one, what it defaults to, and which failure it exists to prevent.

TL;DR — Controlling AI Code Review Costs

• A monthly spend limit is a hard ceiling on total usage per billing period, and it cannot be overridden.
• Per-user and workspace CLI limits best-effort cap local review spend separately from CI; concurrent or already-running reviews may exceed them, and there is no limit by default.
• maxBudgetPerRun caps what a single agent run may spend in US dollars; the agent checks accumulated cost after each turn and stops.
• maxRuns caps how many times an agent runs on one pull request.
• The loop to actually worry about: an agent that writes code creates a new push, which can re-trigger the same agent. maxRuns is the fix.
• Cheaper models are a real lever — model choice is per-agent, so expensive reasoning can be reserved for the checks that need it.

Why Usage-Based Pricing Changes the Cost Question

Under per-seat pricing, cost is a function of headcount and cost control is a procurement conversation. Under usage-based pricing, cost is a function of activity, which means it moves with your merge rate, your CI configuration, and how many custom agents you have enabled.

That is better in the common case — you pay for review that happens, not for licenses that idle — and it means the ceilings matter. The rest of this post is those ceilings.

Layer 1: Monthly Spend Limits

The outermost control is a monthly spend limit: an intended ceiling on total usage per billing period. It is deliberately not overridable, but the pre-flight spend check does not atomically reserve budget, so concurrent reviews that pass the check while below the limit can still bill past it. In practice the overshoot is bounded by how many reviews run simultaneously, not unbounded.

Two consequences worth planning for:

• Commits pushed while the spend limit is hit are skipped, not queued and billed later. Reviews resume when the limit is raised or the billing period rolls over. Commits blocked by an exhausted credit balance are skipped until credits are added — auto-refill or a manual top-up — since rollover does not replenish persistent credits.
• Auto-refill interacts with the monthly limit. Auto-refill tops up a balance; the monthly limit still bounds total usage. Setting up auto-refill does not remove the ceiling.

Set this to a number you would be comfortable seeing on an invoice with no further explanation.

Layer 2: CLI Review Limits (Per-User and Workspace)

Local review through the Macroscope CLI is metered separately from pull request review, and has its own two-level limit:

Limit	What it covers	Default
Monthly CLI review spend limit	All CLI review spend in the workspace for the billing period	No workspace-wide limit
Default per-user monthly limit	Each developer's CLI review spend for the billing period	No per-user limit

Both default to no limit, which is worth knowing rather than discovering. CLI review is the surface where an enthusiastic engineer can generate real spend quickly, because it is fast, local, and there is no pull request ceremony to slow it down.

When a limit is hit, the message is explicit about which one and who can raise it:

• Per-user: "You've reached your monthly CLI review spend limit. Ask a workspace admin to raise your limit in billing settings, then rerun the review."
• Workspace: "Your workspace has reached its monthly CLI review spend limit. Ask a workspace admin to raise the limit in billing settings, then rerun the review."

Layer 3: Per-Run Agent Budgets with maxBudgetPerRun

The previous two layers are billing-period ceilings. maxBudgetPerRun is per-execution, and it lives in the front matter of a Check Run Agent:

---
maxBudgetPerRun: 0.05
---

The value is a positive number. The backend compares it against billable, cache-adjusted pre-markup cost; billing applies a 5% agent-credit markup on top, so actual billed spend will exceed the configured number even with no mid-turn overshoot. Treat it as a cap on billable, cache-adjusted pre-markup cost, not on your invoice line.

Three details that matter in practice:

• It is best effort, not a hard stop mid-turn. The check happens between turns, so a single expensive turn can spend substantially more than the cap and still finish normally. A turn that reaches the budget during its own execution is not interrupted; only subsequent turns are blocked. Treat it as a bound on runaway loops, not as a precise billing control.
• neutral is not a failure. The check does not go red and block your PR because it ran out of budget. It concludes neutral, which is the right behavior for a cost ceiling.
• It is not supported with input: code_object. The backend rejects this combination and the check fails. Remove maxBudgetPerRun from the agent's front matter or switch to a different input mode.

maxBudgetPerRun is the knob for an agent whose instructions might send it exploring — anything with broad file-reading permission or an open-ended "investigate whether…" prompt.

Layer 4: Run Limits with maxRuns

---
maxRuns: 3
---

maxRuns caps how many times an agent runs on a single pull request. Once the cap is reached, later pushes still create the check but conclude it as skipped with a "Maximum runs reached" message. Commenting @macroscope-app review or explicitly re-running a check via GitHub's Re-run all checks or Re-run failed checks bypasses the run cap, but monthly spend limits and credit-balance checks still apply.

This is the most important cost control in the list, for a reason that is not obviously about cost.

The Loop maxRuns Actually Prevents

Check Run Agents can write code. A write_code commit is a new push to the PR, so it can re-run the checks on that PR — including the agent that made the commit.

That is a loop. Agent pushes a fix, the push triggers the agent, the agent pushes another fix. Without a run cap it terminates when it runs out of things to change, when it runs out of balance, or when someone notices. maxRuns makes it terminate by design.

If you enable any agent with write_code, set maxRuns. It is not optional in the way the other limits are.

Related Guards

Out-of-range values are clamped rather than rejected: waitsForTimeout clamps to 1–60 minutes, waitsFor to its first 10 entries. Watch out for negative maxRuns values: the parser clamps them to 0, and 0 means unlimited — so maxRuns: -1 is a typo that removes the cap entirely. Always use a positive integer for agents with write_code enabled.

Layer 5: Model Choice

Model selection is per-agent, and model prices differ substantially. Macroscope lowered Check Run Agent pricing for GPT-5.6 Terra and Luna in July 2026 and added open-source models — kimi-k2-7-code, glm-5-2, minimax-m3, and qwen-3-7-plus — in the same month.

The practical pattern is tiering by consequence:

• Mechanical checks (does this file have a license header, is this migration reversible) do not need frontier reasoning. Put a cheap or open-source model on them.
• Correctness review on core services is where the expensive model earns its cost.

A workspace with a dozen custom agents all pinned to the most capable model is usually overspending on the majority of them.

Layer 6: Scoping Work So It Never Runs

The cheapest review is the one that does not execute:

• Path globs. include and exclude on each agent stop a frontend rule running on backend diffs.
• Correctness review limits. Settings added in August 2026 let you limit correctness review by run count and file size, but an explicit include in custom correctness instructions still reviews and bills oversized files, so do not rely on the size cap for those files.
• Ignore files. .macroscope/ignore.md replaces the built-in ignore list rather than extending it; when customizing it, preserve the default patterns for generated code, vendored dependencies, and lockfiles, or those files become reviewable and add cost. For Check Run Agents, the ignore file applies only when the agent has no include patterns — an agent-level include takes precedence over the ignore file entirely.
• Skip by author. Reviews can be skipped for specific GitHub authors, which is how you stop paying to review your own bots.

Seeing Where the Money Went

Controls only help if you can attribute spend. Macroscope added a Check Run Agent usage breakdown table in July 2026, an adjustable billing chart date range in the same month, and a daily chart view for agent credit usage in August 2026.

Use the breakdown before tuning. The common surprise is that one over-broad agent accounts for most of the bill, in which case the fix is a path glob rather than a lower budget everywhere.

A Sensible Starting Configuration

For a team adopting AI code review with cost discipline:

1. Set a monthly spend limit you would accept without explanation.
2. Set per-user CLI limits, since they default to unlimited.
3. Set maxRuns on every agent that can write code. Non-negotiable.
4. Set maxBudgetPerRun on any agent with open-ended instructions.
5. Tier your models: cheap for mechanical checks, capable for correctness.
6. Exclude generated code, vendored dependencies, and bot authors.
7. Read the usage breakdown after two weeks and tune the top line item.

Frequently Asked Questions

How do I stop AI code review from costing too much?

Set a monthly spend limit as a hard ceiling, set per-user CLI review limits (which default to unlimited), set maxRuns on any agent that writes code, and use maxBudgetPerRun on agents with open-ended instructions. Then exclude generated code and bot authors so you are not paying to review them.

What is maxBudgetPerRun?

A Check Run Agent front matter setting that caps what a single run may spend, in US dollars. The agent checks accumulated cost before each new turn and stops at the cap, concluding the check as neutral with a "Budget reached" message. It is best effort: a turn that is already running is not interrupted mid-execution, so the final turn can exceed the cap by the cost of that turn.

What is maxRuns?

A front matter setting capping how many times an agent runs on a single pull request. After the cap, later pushes conclude the check as skipped with "Maximum runs reached". Commenting @macroscope-app review or using GitHub's Re-run all checks / Re-run failed checks bypasses the run cap, but monthly spend limits and credit-balance checks still apply.

Can an AI agent that writes code get stuck in a loop?

It can, and this is the main reason maxRuns exists. A write_code commit is a new push, which can re-trigger the checks on that PR including the agent that made the commit. Always set maxRuns on agents with write_code enabled.

Can I override the monthly spend limit?

No. The monthly spend limit is a hard ceiling on total usage per billing period and cannot be overridden. That is what makes it a reliable backstop.

What happens when the spend limit is reached?

Commits pushed while your balance is exhausted are skipped until credits are added — for example, by auto-refill or a manual top-up; billing-period rollover does not replenish persistent credits. Commits blocked by the monthly spend limit resume when the limit is raised or the billing period rolls over.

Does maxBudgetPerRun work with every agent configuration?

No. It is not supported with input: code_object — the backend rejects this combination and the check fails. Remove maxBudgetPerRun or switch to a different input mode if you need a per-run budget on that agent.

Is usage-based pricing more expensive than per-seat for code review?

It depends on the ratio of merge activity to headcount. Teams that ship constantly pay more; teams with many engineers who rarely open pull requests pay less. The advantage is that spend tracks review that actually happened, and that it is capped by explicit limits rather than negotiated annually.