How to Set Up AI Code Review on GitHub in 5 Minutes

To set up AI code review on GitHub, install an AI code reviewer as a GitHub App on your organization, choose the repositories it should cover, and open a pull request: the review runs automatically and posts comments and a check run on the PR. With Macroscope that is a browser-only flow with no CI changes, no YAML and nothing to install locally, and it takes about five minutes from sign-in to the first review starting.

Setting up AI code review on GitHub is quick because a GitHub App plugs into the pull request workflow you already have. This guide covers the install, what the first AI code review looks like, and the optional steps teams usually add next: Check Run Agents for custom rules, making AI review a required check, spend controls, and Slack, Jira and Linear.

What are the quick-start steps for AI code review on GitHub?

Five steps: install the GitHub App, complete checkout, open a pull request, read the review, then add the optional extras.

1. Install the Macroscope GitHub App. Sign in with GitHub at macroscope.com, pick the organization, and choose all repositories or a selected few.
2. Complete checkout. A card is collected at checkout, and every new workspace gets $100 in usage credit. Pricing is usage-based, with no per-seat fees.
3. Open a pull request in a connected repository. You do not need to tag a reviewer or add a label.
4. Read the review. Macroscope posts inline comments with suggested fixes, writes a PR summary, and reports Macroscope - Correctness Check in the Checks tab.
5. Optional next steps: add Check Run Agents in .macroscope/check-run-agents/, make AI code review a required check, set spend controls, and connect Slack, Jira or Linear.

What does AI code review on GitHub actually do?

AI code review on GitHub means an AI reviewer runs automatically on every pull request, the way a CI job or linter would, and leaves its findings directly on the PR. With Macroscope, the GitHub code review:

• Reads the diff, then looks past it into the rest of the repository to check whether the change breaks code that depends on it
• Finds bugs and logic errors, and explains each one in plain language with its impact
• Leaves inline comments on the lines involved, with suggested diffs for fixing them
• Writes a PR summary into an empty description, posts it as a comment if a description already exists, or inserts it between template markers if your PR template has them
• Reports a GitHub check run, Macroscope - Correctness Check, next to your CI
• Lets engineers reply to comments and react with a thumbs up or down

There is no CLI tool to install for PR review, no per-machine setup and no change to how developers work. The AI reviewer lives inside the GitHub pull request workflow and shows up on the PR next to your human reviewers.

What do you need before setting up AI code review on GitHub?

You need a GitHub organization or account you can install apps on, a pull request workflow, and a browser. That is the whole list.

• GitHub access. Macroscope is a GitHub App, and access inherits from GitHub organization membership. GitHub admins become Macroscope admins automatically.
• A pull request workflow. If your team already merges through PRs on GitHub, you are ready.
• A GitHub organization or account. Macroscope installs as a GitHub App.

You do not need any CI configuration, a YAML file, changes to branch protection rules, local installs, or custom prompts. All of those are optional, and most teams add them only after a few days of reviews.

How do I install the Macroscope GitHub App?

Sign in with GitHub, install the Macroscope GitHub App on your organization, pick the repositories to connect, and complete checkout. This is the only required step of the GitHub code review setup.

1. Go to macroscope.com and start the sign-up flow.
2. Sign in with GitHub. There is no separate account to create.
3. Choose the GitHub organization or user account to install into.
4. Pick which repositories to connect:
   • All repositories reviews every PR in the organization, which suits teams that want blanket coverage
   • Selected repositories limits the pilot to specific repos
5. Approve the install on GitHub.
6. Complete checkout in the Macroscope dashboard. A card is collected at this step, and the $100 in usage credit that every new workspace gets is applied to your balance.

Including inactive repositories is fine. Macroscope processes only the last two weeks of commits plus new activity going forward, so a dormant repo adds little. You can add or remove repositories later from GitHub's app settings without reinstalling.

What does the rest of setup ask for?

After the install, Macroscope's setup flow asks for a short Product Overview and your weekly sprint cadence, and offers to connect Jira or Linear, choose a weekly report schedule, and connect Slack. None of these are required for AI code review to run on pull requests. They power the parts of Macroscope beyond code review, such as weekly reports and plain-language commit summaries.

Once setup is done, Macroscope backfills recent GitHub history, starts reviewing pull requests, and generates commit and PR summaries automatically. Connecting tools carries no separate fee; costs come from the usage meters.

What happens when I open my first pull request?

Do what you already do: push a branch and open a pull request in a connected repository, and the AI code review starts on its own.

1. Make a change on a branch in a repository you connected.
2. Push the branch to GitHub.
3. Open a pull request against the branch you normally merge into.

You do not need to tag a reviewer, add a label or run a command. Code review is enabled by default on linked repositories. If you ever want to trigger a review by hand, for example on a repo where automatic review is off, comment @macroscope-app review on the PR.

What does the first AI code review look like?

The first AI code review on GitHub shows up in three places: a PR summary, inline comments on the lines that have issues, and a Macroscope - Correctness Check check run in the Checks tab.

1. A PR summary. A plain-language description of what changed, written into the PR description or posted as a comment depending on whether a description already exists.
2. Inline review comments. Each comment describes the issue, explains why it matters, and usually includes a suggested diff.
3. A check run. Macroscope - Correctness Check appears next to your CI, tests and other checks.

When Macroscope finds an issue, you have three options:

• Fix it yourself. Make the change and push. Each new push can trigger another review run.
• Use Fix It For Me. Macroscope creates a branch, commits a fix, opens a PR, and iterates until CI passes. It never writes directly to your main branch; its branches follow the macroscope/*/** naming pattern. Fix It For Me writes code, so it bills as Agent credits rather than under the Code Review meter.
• Reply or react. If a comment is off target, reply with why, or react with a thumbs down. Comments are advisory unless you make a check required.

That is the full out-of-the-box GitHub PR review experience, with no configuration. For most teams it is enough to get value on day one.

How do I customize AI code review with Check Run Agents?

Add a markdown file to .macroscope/check-run-agents/, and Macroscope runs it as its own GitHub check on every pull request in its scope. Check Run Agents are how teams teach the AI reviewer their own conventions, and each one reports as a separate check run named after its title.

For example, .macroscope/check-run-agents/payment-flow-safety.md:

---
title: Payment Flow Safety
input: full_diff
conclusion: failure
include:
  - "src/payments/**"
  - "src/billing/**"
---

Flag any change to the payments flow that does not include an
accompanying test file change in `tests/payments/`. Treat any
hard-coded currency conversion or tax calculation as a blocker.

The YAML frontmatter controls the agent:

• title sets the check name. This file creates a check run called Macroscope - Payment Flow Safety.
• conclusion is neutral by default, which reports findings without blocking. Set failure to make the agent a merge gate.
• input controls how the diff is processed. The default incremental mode reviews only what changed since the agent's last run and does not support conclusion: failure, so a blocking agent needs input: full_diff.
• include and exclude take glob patterns that scope the agent. If a PR touches none of the included files, the agent does not run at all.
• model, reasoning, effort and tools are optional and control which model runs the agent, how hard it thinks, how deeply it explores, and what it can access, including Slack, Sentry, PostHog, LaunchDarkly, Jira and Linear.

The body of the file is the agent's instructions in plain language. Macroscope reads agent definitions from the PR's latest commit, so the agent runs alongside Macroscope - Correctness Check on the PR that adds it, and on later PRs once merged. Check Run Agents bill as Agent credits at $0.01 per credit, and every workspace includes 1,000 Agent credits per month.

What about Custom Rules in macroscope.md?

Custom Rules are an earlier, beta surface: rules in macroscope.md files that run a separate best-practices review pass, billed under the Code Review meter. Check Run Agents are the more configurable option, with per-agent scoping, models, tools, and a check run of their own that can block merges. For the full field reference and more examples, see the Check Run Agents guide or the Check Run Agents page.

Can AI code review block merges on GitHub?

Let Macroscope review one pull request so its checks report, then add Macroscope - Correctness Check, and any Check Run Agent set to conclusion: failure, under "Require status checks to pass before merging" in a branch protection rule or ruleset. Requiring the correctness check guarantees every PR is reviewed before merge. Requiring a blocking Check Run Agent stops the merge when that agent finds a problem.

Two cautions. GitHub only lists checks that have recently run in the repository, so the check has to report once before you can select it. And a required agent scoped with include patterns never reports on PRs outside its scope, which can leave GitHub waiting. The full walkthrough, including the GitHub UI steps for both branch protection and rulesets and when AI review should and should not block a merge, is in how to make AI code review a required check on GitHub.

How do I set spend controls for AI code review?

Open Settings > Billing in the Macroscope dashboard and set per-review and per-PR caps, a monthly budget limit, and which repos, labels and files get reviewed. Macroscope is usage-based: Code Review is $0.05 per KB of diff reviewed, with a 10 KB minimum ($0.50 floor), and reviews average 55¢ on Budget and 76¢ on Balanced. Status is $0.05 per processed commit.

The spend controls:

1. Cap spend per review and per PR. Defaults are $10 per review and $50 per pull request, both adjustable.
2. Set a monthly budget limit to enforce a monthly spend ceiling.
3. Choose what gets reviewed by turning off auto-review by repo or by label.
4. Specify what to ignore by excluding files, such as generated code or vendored dependencies, from review.

A single pull request can incur several review charges, because each new push can trigger another review run. The per-PR cap is the control that matters most for teams with long-lived PRs or coding agents that push often. Billing is prepaid: one balance covers Code Review, Status and Agent, and Auto-refill can top it up when it falls below a threshold you set. See the pricing section and how to control AI code review costs for details.

How do I connect Slack, Jira and Linear?

Connect them from the Macroscope setup flow or dashboard; none of them is required for GitHub code review, and none carries a separate setup fee.

• Slack. A Slack admin installs the Macroscope Slack app. Once connected, you can subscribe Slack channels to code activity, ask Macroscope questions about your codebase in Slack, and receive weekly reports.
• Jira and Linear. Jira access inherits the permissions of the Jira account that authorizes the integration. Linear access is scoped to the teams you select during authorization.
• Sentry, PostHog, LaunchDarkly and others. These connect as tools for Check Run Agents, so an agent can, for example, look up recent Sentry errors on the files a PR changes before it decides whether to pass.

Teams that live in Slack usually connect it right after code review is running.

What happens during an AI code review?

When a pull request is opened or updated, Macroscope reads the diff, explores the surrounding repository for context, posts its findings on the PR, and updates its check runs. Knowing the sequence helps when something does not look right.

1. Trigger. GitHub notifies Macroscope when a PR is opened or a new commit is pushed.
2. Read the change. The reviewer reads the PR's diff, minus any files you have excluded.
3. Explore the repository. The review looks past the diff into the rest of the repository to check whether the change breaks code that depends on it. This is what makes cross-file bug detection possible.
4. Find issues. Bugs and logic errors are identified against that full context.
5. Run Check Run Agents. Each agent file in the PR's latest commit that matches the PR's scope runs as its own check (PRs from external forks use the default branch's files).
6. Write the PR summary. The summary is written into the description or posted as a comment.
7. Post comments. Inline comments with suggested diffs are posted on the PR.
8. Update check runs. Macroscope - Correctness Check, any Check Run Agents, and Macroscope - Approvability Check if you have turned Approvability on, report their results in the Checks tab.

What should the first two weeks with AI code review look like?

Start on one or two repositories, read the reviews for a week, then add custom rules and widen the install once the team trusts the output. A rollout plan that works for most teams:

• Days 1 to 3. Install on a scoped set of repositories where you control the review culture. Read every Macroscope comment and react with a thumbs up or down so you have a record of what was useful.
• Days 4 to 7. Lean on PR summaries during human review. Try Fix It For Me on a simple finding.
• Week 2. Write your first Check Run Agent for a convention the team already enforces by hand, and run it with the default neutral conclusion so it reports without blocking.
• After that. Promote reliable agents to conclusion: failure, consider making AI review a required check, expand the install to the rest of the organization, and look at Approvability for auto-approving low-risk PRs. Approvability is off by default.

None of this needs extra setup. It is the natural progression after the install.

What are the most common setup issues?

Most setup issues come down to repository scope, a disabled repo, or a Check Run Agent file in the wrong folder or out of scope.

I installed the app but I don't see a review on my new PR. Check that the repository is in the GitHub App's installation scope, that checkout is complete in the Macroscope dashboard, and that code review has not been disabled for that repo. Code review is on by default for linked repos, and workspace defaults control newly linked ones. You can also comment @macroscope-app review to trigger a review by hand.

My Check Run Agent didn't run. Agent files are read from the PR's latest commit (PRs from external forks use the default branch). Confirm the file is a .md file in .macroscope/check-run-agents/ (README.md is ignored), and check its include patterns: if the PR touches none of the included files, the agent does not run by design.

My blocking agent never fails. Confirm it sets both conclusion: failure and input: full_diff. The default incremental input mode does not support a failing conclusion.

The review is costing more than I expected. Each new push can trigger another review run. Set per-review and per-PR caps in Settings > Billing, and exclude generated or vendored files from review.

How do I stop AI code review on a repo temporarily? Disable code review for that repo, or turn off auto-review by repo or by label. You can still trigger reviews on demand with @macroscope-app review. Uninstalling the GitHub App is the hard off switch.

How do teams scale Check Run Agents?

Each agent is a separate .md file in .macroscope/check-run-agents/ with its own scope and merge policy, so teams stack them: blocking gates for high-risk code and advisory checks for everything else. A few common patterns:

Security gate at .macroscope/check-run-agents/security-review.md:

---
title: Security Review
reasoning: high
effort: high
input: full_diff
conclusion: failure
include:
  - "src/auth/**"
  - "src/payments/**"
  - "src/api/**"
exclude:
  - "**/*.test.ts"
---

Flag any PR that introduces new HTTP endpoints without
authentication middleware, new SQL queries without parameterized
statements, or new file upload handlers without size limits.

Migration gate at .macroscope/check-run-agents/migration-check.md:

---
title: Migration Check
input: full_diff
conclusion: failure
include:
  - "schema/migrations/**"
---

Flag any migration that drops a column, renames a table, or
changes a NOT NULL constraint without a backfill plan in the PR
description.

Advisory style nudge at .macroscope/check-run-agents/typescript-style.md, with no conclusion: failure:

---
title: TypeScript Style
include:
  - "src/**/*.ts"
  - "src/**/*.tsx"
exclude:
  - "src/**/*.generated.ts"
---

Prefer `const` over `let` unless reassignment is required.
Flag `any` types and suggest concrete alternatives.

Each agent shows up as its own check run, such as Macroscope - Security Review, on every PR in its scope. Agents with conclusion: failure can be added to GitHub's required status checks so the merge button stays blocked until they pass. Agents without it are advisory and report without blocking.

One caution when combining scoping with required checks: a path-scoped agent does not run on PRs outside its paths, so if you mark it required, GitHub may wait for a check that never arrives. The required-check guide covers how to handle that.

How does a GitHub App reviewer compare with GitHub Copilot or a GitHub Action?

A GitHub App reviewer such as Macroscope is installed once on your organization and reviews every pull request in the repositories you connect, with no workflow files; GitHub Copilot code review comes with a paid Copilot plan; and an Action-based reviewer such as the Claude Code GitHub Action runs inside your own workflows. All three put AI review on GitHub pull requests. They differ in what you set up and how you pay.

• GitHub App (Macroscope). Browser-only install, no YAML and no CI changes. Usage-based billing with no per-seat fees, and every new workspace gets $100 in usage credit. Reviews report as a Macroscope - Correctness Check check run you can make required.
• GitHub Copilot code review. Included in Copilot Pro, Pro+ and Max, and reviews consume GitHub AI Credits from the monthly allowance. It is not included in Copilot Free. See is GitHub Copilot code review good enough? for when it is enough on its own.
• GitHub Action (for example Claude Code). The anthropics/claude-code-action workflow runs Claude Code on your own GitHub Actions runners with your own API key or subscription, and responds to @claude mentions. See the Claude Code GitHub guide for that setup.

If you are choosing between dedicated reviewers rather than setup styles, see best GitHub Copilot code review alternatives.

What if you already have another AI code reviewer?

You can run Macroscope alongside CodeRabbit, Greptile, Cursor Bugbot or another AI code reviewer while you evaluate; each tool reviews the same PRs and comments independently. Side-by-side review on your own pull requests is the most reliable way to compare signal and noise for your codebase before you commit.

For published comparisons, see CodeRabbit vs Macroscope, Macroscope vs Greptile, and Macroscope's own 118-bug code review benchmark. For how to count signal and noise during a trial, see AI code review false positives and signal-to-noise. If you are comparing two other tools, see Greptile vs CodeRabbit and Cursor Bugbot vs CodeRabbit.

Frequently Asked Questions

How do I set up AI code review on GitHub?

Install an AI code reviewer such as Macroscope as a GitHub App, choose which repositories it covers, and open a pull request. With Macroscope: sign in with GitHub at macroscope.com, install the Macroscope GitHub App on your organization, pick all or selected repositories, complete checkout (a card is collected, and every new workspace gets $100 in usage credit), then open a PR. The review runs automatically, posting inline comments with suggested fixes, a PR summary, and a Macroscope - Correctness Check check run. Custom rules, required checks, spend controls and Slack are optional extras.

How long does it take to set up AI code review on GitHub?

About five minutes for the install itself: sign in, install the GitHub App, pick repositories, complete checkout, and open a PR. There is no YAML, no CI configuration and no CLI. Adding Check Run Agents, a required check, spend controls or Slack takes a few more minutes each, whenever you want them.

Do I need to change my GitHub workflow to use AI code review?

No. AI code review on GitHub drops into your existing pull request workflow. You don't need to change branch protection, add a CI step, or rework your review process. The reviewer runs on every PR in connected repositories and posts comments like any other reviewer. Making it a required check is optional.

Does AI code review work with private GitHub repositories?

Yes. Macroscope reviews the repositories you connect through the GitHub App, private ones included. Macroscope is SOC 2 Type II, does not train models on customer code, and encrypts customer data at rest and in transit. Its trust center lists subprocessors and controls.

How much does AI code review on GitHub cost?

Macroscope is usage-based, with no per-seat fees. Code Review is $0.05 per KB of diff reviewed, with a 10 KB minimum ($0.50 floor), and reviews average 55¢ on Budget and 76¢ on Balanced. Status is $0.05 per commit, and Agent work, including Check Run Agents and Fix It For Me, is $0.01 per credit with 1,000 credits included per workspace per month. Every new workspace gets $100 in usage credit. Default caps are $10 per review and $50 per PR, adjustable.

Can I customize what the AI code reviewer checks?

Yes. Add Check Run Agents: markdown files in .macroscope/check-run-agents/, each with YAML frontmatter (scope with include and exclude, plus conclusion, input, model and tools) and plain-language instructions. Each agent reports as its own GitHub check run. Older Custom Rules in macroscope.md (beta) run a separate best-practices pass. For turning team conventions into checks, see how to enforce team coding standards with AI.

Can I make AI code review a required check on GitHub?

Yes. After Macroscope has reviewed one PR, add Macroscope - Correctness Check and any Check Run Agent set to conclusion: failure (with input: full_diff) under "Require status checks to pass before merging" in a branch protection rule or ruleset. See how to make AI code review a required check on GitHub for the full steps and tradeoffs, and GitHub CODEOWNERS for pairing it with required human reviewers.

What happens if the AI code reviewer makes a mistake?

Reply to the comment explaining why it is off target, or react with a thumbs down. You can ignore a comment and merge anyway: the review is advisory unless you make a check required. If a blocking Check Run Agent is wrong often, set it back to conclusion: neutral until its instructions are tighter.

Can I turn off AI code review for a repository without uninstalling?

Yes. Disable code review for that repo in Settings > Billing, or turn off auto-review by label. You can still trigger a review on any PR by commenting @macroscope-app review. Workspace defaults control whether newly linked repos are reviewed automatically.

What is the easiest way to set up AI code review on GitHub?

Use a reviewer that installs as a GitHub App, so the setup is a browser flow with no CLI, no YAML and no CI changes. With Macroscope the path is: sign in with GitHub, install the app, pick repositories, complete checkout, open a PR. The zero-config default review is enough to get value on day one; customize with Check Run Agents later.

Should I use GitHub Copilot code review or a dedicated AI reviewer?

Start from what you already pay for. GitHub Copilot code review is included in Copilot Pro, Pro+ and Max and consumes GitHub AI Credits; a dedicated reviewer such as Macroscope installs as its own GitHub App, bills by usage with no seat fees, and adds Check Run Agents, Fix It For Me and per-review spend caps. The two install independently, so you can run both on the same PRs and compare. See is GitHub Copilot code review good enough?.

How does Macroscope compare to CodeRabbit or Greptile?

All three run on GitHub pull requests. On Macroscope's own 118-bug benchmark, Macroscope detected 48% of bugs and CodeRabbit 46%; Greptile detected 24% of the 72 bugs it was evaluated on. Pricing differs too: Macroscope is usage-based with no seat fees. For head-to-head detail, see CodeRabbit vs Macroscope and Macroscope vs Greptile.

---

Setting up AI code review on GitHub is one of the rare engineering tool installs that is as quick as it sounds: a few minutes to install, a review on the next PR you open, and everything past that (custom checks, required checks, Slack, Fix It For Me) is incremental.

Ready to start? Install Macroscope on your GitHub organization. Every new workspace gets $100 in usage credit, and your first AI code review on GitHub runs on the next pull request you open.