Skip to main content
A Check Run Agent is a PR check you write in Markdown. Add a file to .macroscope/check-run-agents/, and on each PR it applies to, Macroscope runs an agent with your instructions and posts the result as a GitHub check. Use Check Run Agents for enforcing rules specific to your codebase, like security patterns, migration safety, API compatibility, or PR title and ticket conventions. Each run costs the model’s usage + 5%, billed in Agent credits. The default model is claude-opus-5-5. To stop the built-in Correctness check from flagging intentional patterns, use custom instructions instead.

Define a check

Each check is one Markdown file in .macroscope/check-run-agents/. Subfolders work too. A file has two parts:
  • Front matter (optional): YAML settings at the top, between --- lines. It sets which files the check looks at, which model and tools it uses, whether it can fail the PR, and how much it can spend. Every field is optional, and anything you leave out uses the default. See Configuration for every field.
  • Instructions: the Markdown body, in plain language. Say what to look for, what counts as a problem, and when to report success. See Instructions and context.
For example, .macroscope/check-run-agents/migration-safety.md:
Push the file in a PR to try it. Macroscope reads definitions from the PR’s latest commit, so the check runs on the same PR that adds it. PRs from external forks use your default branch instead. If no check appears, turn on Check Run Agents in Settings → Repos. To run a check by hand, comment @macroscope-app run <title> on the PR. See Run a check manually.

File layout

  • Every .md file under .macroscope/check-run-agents/ is one check, including files in subfolders.
  • You can use subfolders to group checks by team or area.
  • README.md and non-Markdown files are ignored, so you can document your checks alongside them.
  • The title comes from the filename unless you set title. Duplicate titles get a number added.
  • approvability.md and ignore.md are reserved names and stay in the .macroscope/ root, not this folder.
  • The github-actions/ subfolder is reserved for agents run from GitHub Actions. Files there don’t run automatically on PRs.
  • To share text between checks, keep it in a file outside .macroscope/check-run-agents/ and import it. Any .md file inside the folder is treated as its own check.

Configuration

Configuration lists every front matter field and its default. Front matter controls which files a check reviews, which PRs it runs on, what it can access, whether it can fail the PR, and how much it can spend. The default input, incremental, saves tokens by reviewing only newly changed files on later pushes. See input modes for other tasks and required status checks for failure-conclusion settings.

Triggers and skips

Triggers and skips explains when a check runs and why one didn’t. Checks run when a PR is opened or updated, when someone mentions @macroscope-app, on a GitHub rerun, and when certain labels change.

Instructions and context

Instructions and context covers writing instructions, importing shared files with @path, controlling the output, and what happens when a PR is too large for the model.

PR context

Every input mode includes the PR’s title and description. pr_metadata adds the author, labels, and commit messages instead of the diff. Author-supplied text is treated as data, never instructions: it cannot grant permission to skip a rule or suppress a required finding. Descriptions longer than 16 KiB are truncated, and the agent is told about the truncation. This context shares the model’s context window with instructions, tools, and other PR activity.

Models and costs

Models lists model IDs and reasoning settings. Pricing explains billing, and Configuration covers per-run and per-PR budgets.

Migrating

Definitions in the legacy .macroscope/ root still work. Move definitions into .macroscope/check-run-agents/; leave approvability.md and ignore files at the root. The format is unchanged. For legacy Custom Rules, move the body of macroscope.md into a Check Run Agent definition. Add front matter only for settings you need.