Skip to main content
Check Run Agents is in beta. Contact support@macroscope.com to get access.
Check Run Agents are fully customizable AI agents that trigger on every pull request open, push, and manual check rerun. They have access to your codebase, git history, and connected integrations. You define what to check, how to format the output, and what actions to take. Macroscope automatically runs two built-in check runs on every PR: Correctness (catches runtime bugs and logic errors) and Approvability (evaluates merge readiness). Your custom agents appear alongside them in the Checks tab. Check Run Agents in the GitHub Checks tab

​
Getting Started

  1. Create a .md file in .macroscope/ in your repo root (e.g. .macroscope/web-review.md)
  2. Configure the frontmatter fields you need (all optional) and write your instructions:
---
title: Security Review          # Name in GitHub Checks UI (max 60 chars)
model: claude-opus-4-6          # claude-opus-4-5, claude-opus-4-6, gpt-5-2
reasoning: low                  # off, low, medium, high
effort: low                     # low, medium, high
input: full_diff                # full_diff or code_object
tools:                          # Omit to use defaults
  - browse_code
  - git_tools
exclude:                        # Glob patterns for files to skip
  - "*.lock"
conclusion: neutral             # neutral (non-blocking) or failure (blocking)
---

Your instructions here.
  1. Commit and push to your default branch.
Macroscope reads .macroscope/ files from your default branch. Changes won’t take effect on new PRs until they’re merged.

​
Scope and Organization

Each .md file in .macroscope/ becomes its own agent, scoped to the repo it lives in. We recommend starting with one file and splitting only when you need different configurations (e.g. different tools or input modes). If you already use a CLAUDE.md to guide how AI writes code, you can reference it from your check run agent’s instructions to keep coding conventions and review standards in sync.

​
File Format

The file has two parts: an optional YAML frontmatter block for settings and a markdown body with your instructions. Every frontmatter field is optional. If you omit frontmatter entirely, defaults apply and the filename becomes the title.
FieldDefaultOptionsDescription
titleDerived from filenameAny string (max 60 chars)Name in GitHub Checks UI
modelclaude-opus-4-6claude-opus-4-5, claude-opus-4-6, gpt-5-2Which model powers the agent
reasoninglowoff, low, medium, highExtended thinking depth
effortlowlow, medium, highHow deep the agent digs
inputfull_difffull_diff, code_objectHow the PR diff is fed to the agent
tools[browse_code, git_tools, github_api_read_only, modify_pr]See ToolsWhich tools the agent can use
excludenoneGlob patternsFiles to skip (e.g. "*.lock", "vendor/**")
conclusionneutralneutral, failureMaximum severity the agent can report

​
input: Full Diff vs Code Object

ModeWhat happensWhen to useCost
full_diff (default)One agent processes the entire PR diffEnforcement that needs PR-level context (“new function added without tests”)Lower
code_objectUp to 20 agents in parallel, one per changed code objectPer-unit enforcement (“don’t log PII in any changed file”)Higher

​
conclusion: Blocking vs Non-Blocking

By default, the conclusion is capped at neutral: issues show up in the Checks tab but never block merging. Set conclusion: failure to let the agent block PRs when it finds issues. Even with failure, the check still reports success when nothing is wrong. The setting only raises the ceiling on severity, not the floor.
If every changed file in a PR matches the exclude patterns, the check concludes as Skipped rather than running the agent.

​
Tools

​
Included by Default

ToolWhat it does
browse_codeExplore the file tree, read files, search by filename or content
git_toolsGit log, blame, diff, grep
github_api_read_onlyRead-only GitHub API: issues, labels, PR metadata, commit statuses
modify_prUpdate the PR (title, description, labels, assignees, reviewers) and post line-level review comments
Specifying tools: in frontmatter overrides the defaults. To keep defaults and add more, list them all.

​
Additional Tools

ToolRequiresWhat it does
web_toolsNo connection neededSearch the web, fetch URLs
slackSlack connectedPost messages to channels, look up users
sentrySentry connectedSearch error issues, view event history
posthogPostHog connectedQuery analytics, feature flags, session recordings
launchdarklyLaunchDarkly connectedQuery feature flags, targeting rules
bigqueryBigQuery connectedRun read-only SQL queries
amplitudeAmplitude connectedEvent segmentation, funnels, retention
gcp_cloud_loggingGCP connectedQuery log entries by severity, resource, timestamp
issue_tracking_toolsJira or Linear connectedRead issues and projects
mcpMCP server connectedInvoke tools from any connected MCP server
Connected tools require the integration in Settings > Connections. Missing connections are silently disabled.

​
Output and Instructions

​
Where Results Appear

Results appear in three places:
  1. Check run details. Click into the check in the Checks tab to see the full report: title, summary, and detailed findings. Your instructions influence how this output is structured and formatted.
  2. Inline PR comments. The agent posts comments directly on specific lines in the PR diff, attributed to the check name.
  3. Issue comments. The agent can also post top-level comments on the PR itself for broader findings or summaries.
Inline PR comment from a Check Run Agent

​
Controlling Output Format

You can control formatting in your instructions. Some examples:
  • “Use a markdown table with columns: file, line, issue, severity”
  • “Group findings by priority, critical first”
  • “Use 🔴 🟡 🟢 emoji for severity levels”
  • “Start with a one-line summary, then list details”
  • “If no issues found, just say ‘All clear’ with no extra detail”
  • “Format as a checklist so the reviewer can tick items off”
  • “Be concise. Each bullet point should be under 20 words”

​
Writing Good Instructions

  • Be specific. “Review for quality” is too vague. “Flag any function over 50 lines without a doc comment” is actionable.
  • Define severity. Spell out what critical vs minor means for your team.
  • Don’t replicate the Correctness check run. It already catches runtime bugs. Focus on your team’s conventions and workflows.
  • Scope with exclude. If your check only applies to frontend code, exclude everything else.
  • Give the agent permission to do nothing. “If nothing applies, report that no issues were found” prevents invented findings.
  • Use sections in your instructions. Markdown headings (##) in the body help the agent organize its work and output.
  • Reference specific paths. “Check files in services/auth/” is better than “check auth code.”
  • Tell it what not to flag. “Ignore test files” or “don’t flag TODOs in draft PRs” reduces noise.

​
Example

We recommend consolidating related rules into a single check rather than splitting across many files. Here’s a web team example that handles several concerns in one agent: 
---
title: Web Review
model: claude-opus-4-6
effort: medium
input: full_diff
tools:
  - browse_code
  - git_tools
  - modify_pr
  - slack
  - sentry
exclude:
  - "*.go"
  - "*.proto"
  - "schema/**"
  - "services/**"
---

Review this PR against our web team's standards:

## Event Tracking
If this PR touches payment flows, signup funnels, analytics calls,
CTA buttons, or redirect logic, check whether it could break event
tracking. Rate each issue: 🔴 will stop firing, 🟡 may fire incorrectly,
🟢 low risk.

## Accessibility
Check new or modified React components for basic accessibility:
- Images must have alt text
- Buttons and links must have accessible labels
- Form inputs must have associated labels

## Production Errors
For each file modified, check Sentry for unresolved issues. If any
active errors exist, list them with frequency and last seen date.

## Labels
Add labels to this PR based on what changed:
- "frontend" if any UI components are modified
- "styles" if CSS or styled-components changed
- "docs" if only markdown files changed

## Notifications
If any 🔴/🟡 event tracking issues or accessibility violations are
found, post a summary to #eng on Slack with the PR link.

If nothing noteworthy is found, report that all checks passed.

​
Migrating from Custom Rules

Check Run Agents replaces Custom Rules. If you have an existing macroscope.md file, move your rules into .macroscope/my-rules.md instead. Your existing rules become the instructions body, and you can optionally add frontmatter for model, tools, and input mode. Check Run Agents goes further: agents can browse the codebase, query git history, post to Slack, check Sentry, and more. You also get structured output in the Checks tab instead of just inline comments.

​
Billing

We are not yet charging for Check Run Agents. They will eventually be billed with Agent usage.
To keep costs down: use exclude to skip irrelevant files, prefer full_diff over code_object, and use lower effort for simple checks.