> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Selection & Costs

> Pick the model behind a Check Run Agent, tune reasoning and effort, and see how a run is billed

Every [Check Run Agent](/check-run-agents) runs on a model you choose in its front matter. This page covers how to select one, how `reasoning` and `effort` behave on an agent, and how a run is billed. The model list and the per-token rates live on [Models & Token Pricing](/model-pricing) — the shared reference every Macroscope feature bills against.

## Choosing a Model

Set `model:` in your front matter to choose which model powers the agent. Any model in the [shared model list](/model-pricing#available-models) can be used.

The default model is `claude-opus-4-6`.

<Info>
  If you omit `model:`, the agent uses the default (`claude-opus-4-6`). If you set `model:` to a value Macroscope doesn't recognize (or a deprecated one), the check run completes as `skipped` — neither pass nor fail — with a "model is not available on Macroscope" message on its details page. It never silently falls back to a default.
</Info>

<Note>
  Open-source models are opt-in per agent (the default model stays `claude-opus-4-6`) — a good fit for specialized, high-volume, or narrowly-scoped checks, while Opus remains the default for reviews that need the strongest model. `model:` only changes which LLM powers the agent — every other front-matter control (`tools`, `input`, `include`, `exclude`, and the rest) works the same on every model.
</Note>

## Reasoning and Effort

`reasoning` and `effort` tune how hard the model thinks. Which one applies depends on the model — see [per-model support](/model-pricing#reasoning-and-effort) for the full rules and the levels each model accepts.

Writing a `reasoning` level a model does not support falls back to `low` and surfaces a warning on the check run details page.

For example:

```md theme={null}
---
title: Security Review
model: claude-opus-4-5
reasoning: high
effort: medium
---

Your instructions here.
```

## How Runs Are Billed

Check Run Agents bill in Agent Credits based on what the run's model calls cost. The underlying token rates are the [raw model rates](/model-pricing#pricing), which are the same everywhere they are used; this page covers what Check Run Agents add on top. `claude-opus-4-6` is the default when no model is set.

<Note>
  A Check Run Agent's usage is billed in credits: **raw model cost + 5% markup**, then ÷ \$0.01 per credit (1 credit = \$0.01).
</Note>

## Managing Costs

To keep costs down: use `include`/`exclude` or [`.macroscope/ignore.md`](/bug-detection-and-fixes#macroscope-ignore) to scope to relevant files, use [`incremental`](/check-run-agents#input-modes) for non-blocking checks that should avoid re-reviewing unchanged files on every push, prefer `full_diff` over `code_object`, use [`pr_metadata`](/check-run-agents#input-modes) for checks that only judge the PR's title, labels, description, or commit messages, and use lower `effort` for simple checks.

Cost information is available in two places:

* **Settings → Billing** — Admins can see a full cost breakdown across all Check Run Agents.
* **GitHub Check Run details page** — Shows the billed total for each individual run, plus the token usage behind it.

### Reading the billing footer

Every Check Run Agent's details page ends with what the run cost and what it consumed:

> **Agent Credits:** 44 credits
>
> **Token usage:** 2 uncached input · 0 cache-read input · 44,885 cache-write input · 5,534 output

The four figures cover the whole run — every model call the agent made, including the nested ones its research tools make on its behalf. They do not overlap, so each token is counted once:

| Metric                | What it counts                                                                                            |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| **Uncached input**    | Prompt tokens the model read fresh, with no cache involved.                                               |
| **Cache-read input**  | Prompt tokens the model reused from the provider's prompt cache instead of re-reading.                    |
| **Cache-write input** | Prompt tokens written into the provider's prompt cache so later calls in the same run can read them back. |
| **Output**            | Everything the model generated, including any reasoning tokens.                                           |

You are billed in Agent Credits, not per token — these figures are what the run consumed, not four separate charges.

A long agent run typically shows a large **cache-write** number and a small **uncached input** number. That is the intended shape: the agent writes its context to the prompt cache once and reads it back on every subsequent turn instead of re-reading the whole prompt, which is what keeps a long run's credits down.

<Note>
  **Two different caches, and only one of them makes a run free.**

  **Provider prompt caching** is what **cache-read** and **cache-write** measure. The model still runs, so the run still costs Agent Credits — caching just makes it cost fewer of them. This happens within a single run, turn to turn.

  **Macroscope response reuse** is separate. When a check runs again over work it has already reviewed, Macroscope can reuse the complete stored result instead of calling the model at all. Nothing is metered, so the run costs **0 credits** and the details page says the result was reused rather than showing token figures. Re-running the check from GitHub forces a fresh review.
</Note>

<Note>
  Agent Credits can also include charges from tools that bill per call rather than per token — web research, for instance. Those add to the credits total without appearing in any of the four token figures, and the footer says so when they apply.
</Note>