> ## 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. # Configuration > Front matter fields, input modes, filters, tools, dependencies, and limits. Check Run Agent files have optional YAML front matter followed by Markdown instructions. All fields are optional; omitted fields use these defaults. ## Fields | Field | Default | Values / effect | | - | - | - | | `title` | Filename | Check title; maximum 60 characters. | | `model` | `claude-opus-5-5` | [Model ID](/model-pricing#available-models). Unavailable IDs skip the check. | | `reasoning` | `low` | `off`, `low`, `medium`, `high`, `xhigh`, `max`; [support varies by model](/model-pricing#reasoning-and-effort). | | `effort` | `low` | `low`, `medium`, `high`; Anthropic only. | | `input` | `incremental` | [Input mode](#input-modes). | | `tools` | `browse_code`, `git_tools`, `github_api_read_only`, `modify_pr` | Replaces the default tool list. See [tools](#tools). | | `include` | All changed files | Globs selecting files to review. | | `exclude` | None | Globs removing files from scope; wins over `include`. | | `labels` | Repository rule | PR must have at least one listed label. | | `authors` | Repository rule | PR author must match a listed GitHub login. | | `targets` | Repository rule | Target branch names or `only_default_branch`. | | `conclusion` | `neutral` | `neutral` or `failure`; maximum severity the check may report. | | `requiredStatusCheck` | `false` | Report `skipped` when a selected agent's scope or filters exclude the PR. | | `showToolCalls` | `true` | Show the ordered tool-call log in check details. | | `waitsFor` | None | Check names that must finish, or `["*"]`. | | `requires` | None | Check names that must pass, or `["*"]`. | | `waitsForTimeout` | `20` | 1–60 minutes for prerequisites to finish. | | `waitsForDiscoveryTimeout` | `1` | 1–60 minutes for prerequisites to appear. | | `maxRuns` | Unlimited | Positive integer; maximum runs of this agent per PR. | | `maxBudgetPerRun` | Unlimited | USD per run; checked after each turn. Unsupported with `code_object`. | | `maxBudgetPerPR` | Unlimited | USD spent by this agent across runs on a PR; checked before dispatch. | An unavailable `model`, or an option the `input` mode does not support, skips the check with a configuration message in its details. An unsupported `reasoning` level warns and falls back to `low`. ## Input modes * **`incremental` (default):** Recommended for most diff-based checks. Reviews files changed since this agent's last completed review, each shown as its full PR diff. Saves tokens on later pushes by leaving unchanged files out. * **`full_diff`:** Sends the entire PR diff on every run. Useful when the agent needs PR-wide context each time; usually uses more input tokens than incremental on later pushes. * **`code_object`:** Runs a separate agent per changed code object, with up to 20 running concurrently. Use for specialized checks that need focused, parallel review of individual objects. Can be much more expensive because each object runs its own agent. * **`pr_metadata`:** Sends the title, author, labels, description, and commit messages, without the diff. Use when the task does not need the diff, such as ticket links or title conventions. Often much more token-efficient for these tasks. An unknown `input` value warns and falls back to `full_diff`. An incremental agent's first run covers all in-scope files. Later runs use its last completed review as the baseline. Skips, errors, cancellations, and incomplete reviews do not advance it. No new in-scope changes means a free, skipped check. Force-pushes, rebases, a moved merge base, configuration or ignore-rule changes, explicit mentions, and GitHub reruns cause a full review when the prior baseline cannot be reused safely. `pr_metadata` uses the same triggers, file-scope rules, and tools as `full_diff`. Its tools can still inspect code when instructed. `conclusion: failure` is not supported with `input: incremental`. Use `conclusion: neutral`, or keep `conclusion: failure` with an explicit `input: full_diff`. ## File scope `include` selects files; `exclude` removes them. Patterns without `/` match at any depth, `*` matches within one path segment, and `**` spans directories. ```yaml theme={null} include: ["src/**"] exclude: ["src/generated/**"] ``` An explicit `include` overrides [repository ignore rules](/code-review/ignore-files), but not the agent's `exclude`. The check warns when it overrides an ignore pattern. Agents without `include` respect repository ignores. | Mode | How scope affects input | | - | - | | `full_diff` | The whole PR diff remains in context; scope tells the agent where to report. Narrowing globs does not shrink the prompt. | | `incremental` | Out-of-scope and unchanged files are removed before the run. | | `code_object` | Out-of-scope code objects are removed before the run. | | `pr_metadata` | Changed files determine whether the check runs; no diff is included. | In every mode, comments on out-of-scope files are dropped. If every file is excluded, no agent runs and no usage is billed. `include`/`exclude` normally produce no check; `requiredStatusCheck: true` produces a skipped check. Repository ignore rules that exclude everything always produce a skipped check. ## Applicability filters `authors`, `labels`, and `targets` each require at least one match within their list. All configured axes must match. A configured axis replaces the corresponding repository skip rule; omitted axes follow repository settings. ```yaml theme={null} authors: ["dependabot[bot]"] labels: ["dependencies"] targets: [only_default_branch] ``` Author and label matching is case-insensitive. Use GitHub's full bot login, including `[bot]`. Target branches are literal names, with `only_default_branch` as a special value. Blank entries are ignored and duplicates removed. Front matter filters apply even to explicit mentions and reruns. ## Required status checks `conclusion: failure` allows a check to fail when it finds a violation; a clean result still reports success. Add the check to GitHub branch protection to make that failure block merging. `conclusion: failure` requires `input: full_diff`, `code_object`, or `pr_metadata`. It is unsupported with `incremental` (the default), which cannot replay an earlier failure verdict. For scoped checks, also set `requiredStatusCheck: true`. A selected agent excluded by its applicability or file filters then reports `skipped`, which GitHub accepts, instead of leaving an indefinitely pending required check. This option does not schedule the agent. If the feature is disabled, the definition is deleted or renamed, or the event selects another agent, no check is created. Keep branch protection consistent with those settings. ## Prerequisite steps Use names from the PR's Checks tab. Matching is exact apart from case and applies to individual check runs, not whole workflows. At most **10 distinct names** across `waitsFor` and `requires`. ```yaml theme={null} waitsFor: [integration-tests] requires: [lint] waitsForDiscoveryTimeout: 2 waitsForTimeout: 20 ``` Both checks must finish; only `lint` must pass. Every waited-for result is supplied to the agent. `requires` accepts GitHub's passing conclusions: `success`, `neutral`, and `skipped`. A failed, cancelled, timed-out, stale, or action-required check prevents the agent from running. Use `waitsFor` when the agent should investigate failures. Missing prerequisites, timeouts, and dependency cycles skip the agent without starting it. Cycles across either field are detected at parse time. ### Wildcard waits `waitsFor: ["*"]` waits for all other checks, excluding itself and other wildcard agents so those agents can run in parallel. `requires: ["*"]` also requires the waited-for checks to pass. You can combine a wildcard wait with a named requirement. ### Timeouts `waitsForDiscoveryTimeout` limits how long a named check may take to appear. `waitsForTimeout` limits the total wait for completion; discovery time is included in it. Both accept 1–60 minutes. For named checks, discovery ends as soon as all names appear. For wildcard waits, the discovery window is a **minimum delay on every run**. Raising it to 10 minutes delays every wildcard run by at least 10 minutes; the check warns about this configuration. ## Run and spend limits | Limit | When checked | Result at the limit | Override | | - | - | - | - | | `maxRuns` | Before another run | Skipped | Explicit mention or GitHub rerun. | | `maxBudgetPerRun` | After each turn | Neutral, "Budget reached"; findings may be incomplete | None. | | `maxBudgetPerPR` | Before another run, against this agent's recorded spend | Skipped | Explicit mention. | Omitted or non-positive `maxRuns`, `maxBudgetPerRun`, and `maxBudgetPerPR` mean no limit. Positive budgets below `$0.00001` are raised to that amount; values above `$100,000` are clamped, with a warning. `maxBudgetPerRun` is unsupported with `code_object`. Limits are checked in this order: workspace balance and monthly limit, the workspace Check Run Agents per-PR limit, `maxBudgetPerPR`, then `maxRuns`. See [Triggers and skips](/check-run-agents/triggers#overrides) for which triggers bypass each one. Budgets are best effort. Completed work is billed, and concurrent runs can overshoot limits. The workspace's [combined agent per-PR limit](/spend-limits#cra-per-pr-limit), balance, and monthly limit also apply. Raising an agent budget does not raise workspace limits. ## Tools Specifying `tools` replaces the defaults, including comment-posting access. List every tool you want to retain. | Tool | Capability | Requirement | | - | - | - | | `browse_code` | Read and search repository files. | Default. | | `git_tools` | Read log, blame, diff, and grep. | Default. | | `github_api_read_only` | Read GitHub metadata, issues, checks, and statuses. | Default. | | `modify_pr` | Update PR metadata and reviewers; post inline and conversation comments. | Default. | | `web_tools` | Search the web and fetch URLs. | No connection. | | `slack` | Send messages and look up users. | Slack. | | `sentry` | Read error issues and event history. | Sentry. | | `posthog` | Query analytics, flags, and recordings. | PostHog. | | `launchdarkly` | Read flags and targeting rules. | LaunchDarkly. | | `bigquery` | Run read-only SQL. | BigQuery. | | `amplitude` | Query events, funnels, and retention. | Amplitude. | | `gcp_cloud_logging` | Query logs. | GCP Cloud Logging. | | `issue_tracking_tools` | Read issues and projects. | Jira or Linear. | | `image_gen` | Generate images and upload to GitHub or Slack. | No connection. | | `mcp` | Invoke connected MCP tools. | MCP server. | Connect services in [Settings → Connections](/integrations). Tools without their required connection are silently disabled. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.