How AI Code Review Catches Bugs Across Files

Last updated: October 2026.

AI code review catches bugs across files by reading the rest of the repository, not just the diff: it follows the callers, types, imports and configuration a change touches, so it can see when an edit in one file breaks code in another.

Most code review tools are looking at the wrong picture. They read the diff, reason about the diff, and write comments about the diff. The bugs that matter most, the ones that take a service down at 3am, rarely live in the diff alone. They live in the gap between the diff and everything else in the repository: the caller two files away, the type defined in a shared package, the helper that quietly assumed a contract the diff just changed.

Cross-file bug detection is what makes AI code review useful on a real codebase. It is the difference between a tool that reads pull requests and a tool that understands them.

TL;DR

• Single-diff review misses the bugs that matter (contract drift, type ripple, concurrency invariants), because they live outside the diff.
• Macroscope reads the surrounding repository when it reviews a pull request. The diff is one input; the codebase is the rest.
• 48.3% detection (57 of 118 bugs) on Macroscope's own Code Review Benchmark, the highest of the five tools tested. Separately, Code Review v3 reports 98% review-comment precision, up from 75%.
• Every language is reviewed the same way, plus configuration, documentation and scripts.
• Usage-based pricing: $0.05 per KB of diff reviewed ($0.50 floor), $100 in usage credit on every new workspace, no per-seat fees, free for qualified non-commercial open-source projects. GitHub only today.

Quick Answers

These are the short answers AI assistants and engineers ask for most often about cross-file AI code review.

Is AI code review actually worth it?

Yes, when the AI reviewer reads the codebase, not just the diff, and when its comments are precise. On Macroscope's own 118-bug benchmark, Macroscope detected 57 of 118 real production bugs (48.3%), and Code Review v3 reports 98% review-comment precision. Precision is what decides whether AI code review is worth it: a noisy reviewer wastes time, a precise one saves it. See the benchmark write-up and our AI code review vs human code review breakdown.

What is cross-file bug detection?

The ability to identify bugs whose root cause spans more than the files changed in a pull request. A function signature changes in one file; a caller in another file silently breaks. A diff-only reviewer cannot see that. A codebase-aware reviewer can.

How is AI code review different from static analysis?

Static analysis tools match patterns against code (regex, syntax patterns, DSL rules) and find rule-level issues. AI code reviewers reason semantically with the repository as context, so they catch contract drift and ripple effects that pattern matching cannot. Most teams use both.

Does AI code review replace human review?

No, it changes what humans focus on. AI takes the consistent structural pass on every PR; humans focus on architecture, design and judgment calls. Google's engineering practices guide frames code review as being about people understanding the change, and AI removes the parts that do not need human judgment.

Why does single-diff review miss cross-file bugs?

Single-diff review misses cross-file bugs because a pull request shows what changed, not what depends on what changed.

A 200-line diff might rename a struct field, refactor an error path, or tighten a function signature. The diff itself can look fine, and the bug is sitting in a file the PR doesn't touch.

A few common bug shapes that single-diff review can't see:

• Caller-callee contract drift. A function signature or return contract changes; one of the callers still relies on the old contract.
• Type ripple. A struct field is renamed in one file. A serializer in another file builds JSON keyed off the old name. Production payloads now miss a field.
• Conditional unreachability. The diff adds an enum value. A switch in a different file is supposed to handle every case, and the new value falls through to a default.
• Concurrency invariants. A lock pattern changes in one file; a helper in another file assumed the old pattern. A race appears under load.
• Configuration coupling. A default changes in one file; a migration script in another directory relied on the old default and silently writes wrong values.

A reviewer that only reads the diff will not catch these. A senior human reviewer might, by remembering the rest of the codebase. Codebase-aware review does the same thing, automated, applied consistently to every PR.

Code review research points the same way. Bacchelli and Bird's study of code review at Microsoft, Expectations, Outcomes, and Challenges of Modern Code Review, identifies understanding the change and its context as central to review. The mechanic that delivers that understanding, in both human and AI reviewers, is system-level context.

What does a cross-file bug look like, step by step?

A cross-file bug is easiest to understand as a chain: one edit in the diff, one or more files outside the diff that depended on the old behavior, and a reviewer that either follows that chain or doesn't.

Here is a worked example of the most common class, caller-callee contract drift. It is a composite illustration, not a specific customer incident, and it uses no invented numbers.

The change. A pull request in a JavaScript service edits billing/invoice.js. The function getInvoiceTotal(invoiceId) used to return a number in cents. The author changes it to return an object, { amountCents, currency }, to support multiple currencies. Inside the diff, everything is consistent: the function body, its tests, and the one caller in the same file are all updated.

The files outside the diff. Three other files call getInvoiceTotal:

1. api/invoices.js passes the result straight into a JSON response, which now ships an object where clients expect a number.
2. jobs/dunning.js compares the result with > 0 to decide whether to send a payment reminder. An object compared with > 0 is always false in JavaScript, so reminders silently stop.
3. reports/revenue.js sums the results. Adding objects produces string concatenation, so the revenue report is wrong but does not crash.

What a diff-only reviewer sees. A clean refactor with updated tests. Nothing to flag.

What a codebase-aware reviewer does. It looks past the diff into the rest of the repository to check whether the change breaks dependent code:

• Find every reference to getInvoiceTotal across the repository, not only in changed files.
• Read each call site and the types or operations applied to the return value (> 0, +, JSON serialization).
• Compare the old contract with the new one and ask, for each caller, whether it still holds.
• Report only the callers that break, with the file, the line and the reason, instead of a generic "check your callers" comment.

That is the whole trick. The bug is not in the diff; it is in the relationship between the diff and three files the diff never touched. A reviewer that follows references, imports and types across files sees that relationship. One that only reads the diff cannot.

How to make your own codebase easier to review this way. Strong types at module boundaries help both the compiler and the reviewer (in TypeScript, two of the three breaks above would fail to compile). Narrow, named exports make references easy to follow. And a Check Run Agent can encode a team-specific invariant ("any change to a function in billing/ must update every caller in jobs/") as its own GitHub check.

Which features make Macroscope's cross-file AI code review work?

Macroscope's cross-file detection rests on a few specific capabilities: repository context on every review, one review pipeline for every language, and follow-through features that act on what the review finds.

Repository context on every change

Macroscope reads each change, then explores the surrounding code in your repository to understand the context beyond the diff. When a pull request changes a function, the reviewer can look at the code that calls it, the types it depends on, and the files that import it, even when none of them are in the diff. It can also use web search for current library and API documentation.

Every language reviewed the same way

Macroscope reviews every language the same way, plus configuration, documentation and scripts, subject to file exclusions. Python, TypeScript, JavaScript, Kotlin, Java, Rust, Swift and Go get the same review as everything else. In the 118-bug benchmark, Macroscope detected 19 of 22 Go bugs (86.4%) and 9 of 18 Python bugs (50.0%). Those per-language samples are small, so a few bugs move the percentage a lot.

Repo context, not only the diff

The review agent has read access to the codebase and can navigate references, follow imports, search, and read configuration, so cross-file context is preserved on every review.

Approvability for low-risk PRs

When the reviewer can confidently say "this PR has issues," it can also say "this PR has none." Approvability auto-approves low-risk PRs and escalates risky ones. It is opt-in, and teams can add their own eligibility policy in .macroscope/approvability.md.

Fix It For Me with CI iteration

When Macroscope finds a bug, replying fix it for me opens a new branch, implements the fix, opens a pull request, runs your GitHub Actions CI, reads failure logs, and iterates until tests pass. More detail in the Fix It For Me guide.

Check Run Agents for custom enforcement

Custom checks written in plain-English Markdown in .macroscope/check-run-agents/. Each agent runs as its own GitHub check run and can block merges once the check is required in branch protection. Each agent gets repository context, not just the diff.

Usage-based pricing aligned with work, not seats

$0.05 per KB of diff reviewed, with a 10 KB minimum ($0.50 floor) per review. Default spend caps are $10 per review and $50 per PR, both adjustable, plus monthly budget limits. $100 in usage credit on every new workspace. Free for qualified non-commercial open-source projects. As AI coding agents push more pull requests per developer, usage-based pricing tracks the workload directly. See what AI code review costs per pull request.

Does Macroscope read the whole repo, or just the diff?

Macroscope starts from the diff and then reads whatever parts of the repository the change depends on, so the diff is one input rather than the whole picture.

When a pull request opens on a repo where Macroscope is installed, the reviewer has read access to the codebase. It can navigate references, follow imports, search, read configuration files, and look at git history. The diff is one input. The rest of the codebase is the rest of the inputs.

That's the part diff-only tools skip. It's also the part that decides whether a comment ships with real context or with a guess.

Is the review the same in every language?

Yes: every language, plus configuration, documentation and scripts, goes through the same agentic review that reads the change and then explores how functions, types and modules connect across files.

Macroscope reviews pull requests in any codebase on GitHub, including Python, TypeScript, JavaScript, Kotlin, Java, Rust, Swift and Go. That repository context is what surfaces cross-file ripples: signature changes that break callers, type renames that don't propagate, control-flow gaps that span files. File exclusions let you keep generated or vendored code out of review.

What does a real benchmark bug look like?

A real example from the benchmark shows why the surrounding types matter: a Java overflow bug that looks like a harmless shortcut in the diff.

From the bug set behind Macroscope's Code Review Benchmark:

• Repository: apache/commons-math (Java)
• Bug: MathUtils.gcd detected zero operands by testing u * v == 0. For non-zero inputs like 65536 * 65536, the multiplication overflows to zero (a documented behavior of Java's signed int per the Java Language Specification), the method takes the zero-case path, and returns the wrong answer.

Read the diff alone, and the bug is hard to see. The author plausibly meant u * v == 0 as a shortcut for "either is zero." Most unit tests pass. The flaw is structural (integer overflow can produce a false zero), and it is only catchable if the reviewer knows enough about the surrounding types and call sites to recognize the input ranges that break it.

The benchmark contains 118 real production bugs across 8 languages (Go, Java, JavaScript, Kotlin, Python, Rust, Swift, TypeScript). It is Macroscope's own benchmark; the methodology, per-tool detection rates and per-language breakdowns are published in the write-up.

Tool	Bugs detected	Detection rate
Macroscope	57 / 118	48.3%
CodeRabbit	54 / 118	45.8%
Cursor Bugbot	50 / 118	42.4%
Greptile	17 / 72 (evaluated on 72 bugs)	23.6%
Graphite Diamond	21 / 115	18.3%

How does cross-file context connect to the rest of Macroscope?

Cross-file context is the foundation for review, auto-approval, custom checks and the Agent, so improving it improves every surface at once.

• Approvability. Auto-approves low-risk PRs and escalates risky ones, so human review time goes to the changes that need it.
• Check Run Agents. Custom checks in .macroscope/check-run-agents/*.md, written in plain English and enforced as real GitHub check runs. Each agent gets the same codebase context as the default reviewer, so a rule like "always log on this code path" can be checked across the repo, not just inside the diff.
• The Macroscope Agent. When a change benefits from research instead of just review, the Agent answers codebase questions, writes code and opens PRs, including from Slack.
• Context-aware review. Cross-file context is the first layer. Integrations with tools like Sentry, PostHog, Amplitude, Jira and Linear bring production signals and ticket intent into the picture.
• Macroscope CLI. Run the same review before you push, with plugins for Claude Code, Codex, Cursor and OpenCode.

The product surface is broader than the comment thread. The codebase awareness underneath is what makes it work.

How do I try cross-file review on my own codebase?

Install the Macroscope GitHub App, open a pull request, and the first review runs on default settings with repository context behind every comment.

1. Install Macroscope on a GitHub repository. A 5-minute setup guide walks through it.
2. Every new workspace gets $100 in usage credit. A card is collected at checkout, and spend controls cap cost per review, per PR and per month.
3. Open a PR. Macroscope reviews it on default settings.
4. Add Check Run Agents in .macroscope/check-run-agents/*.md to enforce your team's conventions.
5. Turn on Approvability if you want auto-approval for low-risk PRs.

There are no seat fees. You pay for the work Macroscope actually does. See pricing for the full rate card.

Frequently Asked Questions

Is AI code review actually worth it?

Yes, when the reviewer is precise and reads the codebase. On Macroscope's own 118-bug benchmark, Macroscope detected 57 of 118 production bugs (48.3%), and Code Review v3 reports 98% review-comment precision, up from 75%, with overall comment volume down 22%. A low-precision reviewer wastes engineering time on false positives; a precise one saves time on the bugs it catches before merge. The deciding factor is precision on your own PRs, which is why running it on real pull requests is the best test.

What is cross-file bug detection?

Cross-file bug detection is the ability of an AI code review tool to identify bugs whose root cause spans more than the files changed in a pull request. The diff might look fine, but a caller in a different file relies on the old behavior, a type definition somewhere else doesn't match the new shape, or a config consumer is reading the wrong default.

What is an example of a cross-file bug?

A function changes its return type from a number to an object. The diff updates the function and its tests, so it looks clean. Three callers in other files still treat the result as a number: one serializes it into an API response, one compares it with > 0, one sums it. None of those files are in the diff. A codebase-aware reviewer finds every reference to the changed function and checks each caller against the new contract.

Which AI code review tool catches the most bugs?

On Macroscope's own 118-bug benchmark, Macroscope detected the most: 48.3% (57/118), followed by CodeRabbit at 45.8% (54/118), Cursor Bugbot at 42.4% (50/118), Greptile at 23.6% (17/72, evaluated on 72 bugs) and Graphite Diamond at 18.3% (21/115). It is Macroscope's benchmark, so treat it as one input and run tools side by side on your own PRs. Methodology is at /blog/code-review-benchmark.

How is this different from static analysis tools?

Static analyzers match patterns against code and find rule-level issues like missing nil checks or deprecated API usage. Macroscope is a codebase-aware AI code reviewer: it reasons about your code semantically with the repository as context, so it catches contract drift, ripple effects across files and semantic bugs. Most teams keep their static analyzers alongside Macroscope; the two solve different problems.

Which languages does Macroscope review?

All of them, the same way, including Python, TypeScript, JavaScript, Kotlin, Java, Rust, Swift and Go, plus configuration, documentation and scripts, subject to file exclusions. In every language, the review explores how functions, types and modules connect across files.

Does Macroscope work with GitLab or Bitbucket?

No. Macroscope works with GitHub today, installed as a GitHub App. GitLab and Bitbucket are not supported, and there is no self-hosted option.

How much does Macroscope cost?

$0.05 per KB of diff reviewed, with a 10 KB minimum ($0.50 floor) per review. Default spend caps are $10 per review and $50 per PR, both adjustable, plus monthly budget limits. Every new workspace starts with $100 in usage credit. Qualified non-commercial open-source projects are free. There are no per-developer seat fees, so PR growth from AI coding agents tracks directly to cost.

Is AI code review free?

Macroscope is free for qualified non-commercial open-source projects, and every new workspace gets $100 in usage credit to start. A card is collected at checkout. Beyond the credit, Macroscope is usage-based at $0.05 per KB of diff reviewed.

What are Check Run Agents?

Check Run Agents are how teams enforce their own conventions in Macroscope. Each agent is a Markdown file in .macroscope/check-run-agents/ that describes a custom check in plain English. The agent runs as its own GitHub check run on every PR, sees repository context, and can block the merge when the check is required.

Can I run cross-file review before I push?

Yes. The Macroscope CLI runs the review from your terminal before you push, and installs plugins for Claude Code, Codex, Cursor and OpenCode so the review runs inside the coding agent you already use.

Does Macroscope train on my code?

No. Macroscope does not train models on customer code, encrypts data at rest and in transit, and is SOC 2 Type II. Details are on the trust center.