# AI code review for monorepos and large repositories

> How AI code review handles monorepos and very large repositories: folder-level configuration, indexing at scale, large pull requests and the limits.

A monorepo is where AI code review should help most and where it most often disappoints. Most bugs that matter in a large repository cross a boundary: a change in a shared package breaks a service three directories away. A reviewer that sees only the diff cannot see that. A reviewer that tries to read everything runs out of context and budget.

This guide covers what changes when you put an AI reviewer on a monorepo or a very large repository, how MergeHarbor handles it, and the limits you should know about before you roll it out. Where the documentation states a limit, it is quoted here.

## What is different about a monorepo

Three things make monorepos harder than a set of small repositories:

- **Different teams, different standards.** The payments service and the internal tools folder should not be reviewed with the same strictness, the same rules or the same depth.
- **Context is far away.** The code that a change affects is often in another top-level directory, owned by another team.
- **Size.** Indexing, searching and mirroring a repository with hundreds of thousands of files has to be incremental, or every push becomes expensive.

Each needs a different answer: configuration that follows the folder tree, retrieval that follows the code graph, and indexing that only does new work.

## Configuration that follows the folder tree

MergeHarbor reads configuration from `.mergeharbor/` folders anywhere in the repository. Each folder applies to everything below it, and the closest folder to a changed file wins. This is how you give each team its own review without a separate repository.

```
.mergeharbor.yml                          # root settings
services/payments/.mergeharbor/
  config.yml                              # settings for services/payments/**
  rules.md                                # rules for services/payments/**
  context.yml                             # files the reviewer always reads here
tools/.mergeharbor/
  config.yml                              # relaxed settings for internal tools
```

How settings combine across folders matters, because not every setting can vary per folder:

| Setting                                                           | How it applies                                                               |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `min_severity`, `categories`, `checks.disable`                    | Per file: the closest folder wins                                            |
| `depth`, `strictness`, `tier`                                     | Per pull request: the strongest value requested by any changed file's folder |
| `ignore_paths`                                                    | Adds to the inherited patterns, relative to the folder                       |
| `rules`, `context`                                                | Apply to files under the folder                                              |
| `trigger`, `filters`, `max_comments`, `status_check` and the rest | Root configuration only                                                      |

Two consequences are worth knowing. A pull request that touches both `tools/` and `services/payments/` gets the stronger tier and strictness of the two. And a folder's `rules.md` is sent to the reviewer only when a pull request changes files under that folder, so a large rule set for one service does not cost anything on unrelated pull requests.

A team can turn off an inherited rule in its own folder by listing the rule's `id` under `disable_rules`. Organization admins on the Enterprise plan can lock settings so that no folder can weaken them. The full reference is in [Repository configuration](https://mergeharbor.com/docs/repository-config).

## Spend review depth where the risk is

In a monorepo most pull requests are routine and a few are dangerous. [Review tiers](https://mergeharbor.com/docs/review-tiers) let you pay for depth only on the second kind. A Standard review uses 1 credit, Deep 3 and Max 10, and tier rules can match on changed paths:

```yaml
# .mergeharbor.yml
review:
  tier: standard
  tier_rules:
    - name: Payments
      conditions:
        - { field: path, op: include, values: ["services/payments/**"] }
      tier: max
    - name: Large changes
      conditions:
        - { field: files_changed, op: gt, values: ["30"] }
      tier: deep
```

You can also raise the tier for one folder with `tier: deep` in its `.mergeharbor/config.yml`. When several sources apply, the highest tier wins. Auto picks a tier per pull request from size, risky areas, labels, the target branch and recent findings, and says why. Changes that touch only documentation or tests always run at Standard.

Use `filters` at the root to skip what should not be reviewed at all, for example pull requests over a size you consider unreviewable, and `ignore_paths` for generated code and fixtures. The guide on [reducing false positives](https://mergeharbor.com/guides/reduce-false-positives) covers the rest of the noise controls.

## Context across the repository

The reason to index a monorepo is so the reviewer can follow a change to the code it affects. MergeHarbor builds a code graph (definitions, calls, types), a text index and a semantic index. On Deep and Max reviews, and on Standard when turned on, it traces callers, implementations and config readers of the changed code and states the blast radius in the summary. Related code from text search, semantic search and the graph is merged and trimmed to a token budget.

For code in other repositories, such as a shared library kept outside the monorepo, group the repositories into a cluster under **Memory → Cross-repo context**, or name them with `context.repos` in configuration.

## Indexing at scale

Indexing is incremental and content-addressed. After the first pass, only changed files are processed, and identical files are stored and embedded once. Several pushes in quick succession are indexed once, at the newest commit.

Not everything is indexed. Files over 1 MB, binaries, generated and vendored files, and anything in `.mergeharborignore` are left out. Code chunks are embedded for search by meaning for files changed in the last year, the files they call or that call them, entry points and documentation, and any file a pull request changes. Older files are still searchable by name and text, and are embedded when a pull request touches them.

For organizations with many repositories, indexing order follows activity. A repository with a pull request or default-branch push in the last 30 days is indexed right away, one pushed in the last 180 days is indexed in the background, and older repositories are indexed on their next push or pull request. Turn on **Index every repository** to index everything regardless of activity. Reviews never wait for the index: until it is built, the reviewer reads the files the pull request needs directly, and the summary notes that less context was available.

### Measured indexing numbers

MergeHarbor publishes indexing benchmarks. They were measured on **synthetic repositories** generated locally, on a 15-core laptop, with embeddings replaced by an in-process fake. The self-hosting sizing guide says to expect a cloud vCPU to be about half as fast. With those caveats, for a single repository:

|                                                     | 100k files (125 MB of source) | 1M files (1.25 GB of source) |
| --------------------------------------------------- | ----------------------------- | ---------------------------- |
| Full index                                          | 7.8 s                         | 94.9 s                       |
| Incremental index after a push changing 1% of files | 0.24 s                        | 2.6 s                        |
| Peak memory while indexing                          | 205 MB                        | 230 MB                       |

Memory stays roughly flat as the repository grows because every pass streams. Embedding throughput is a property of your embedding deployment and is not part of these numbers; for a large repository it usually takes longer than parsing. Treat these as an indication of how the indexer scales, not as a promise for your repository.

## Large pull requests

A monorepo invites large pull requests: a dependency bump that touches every service, a rename across packages. Three behaviours matter here:

- **Reviewed in parts.** Very large pull requests are reviewed in parts at the same time and combined into one summary. The first part to finish posts its serious, high-confidence findings straight away, labelled as posted early.
- **Bounded reads.** The model never sees a whole repository in one request. A file read returns at most 800 lines, and a tool result is limited to about 12,000 characters. This keeps cost predictable but means a very large single file is read in pieces.
- **Capped spend.** Each review runs under a cost cap, and billing admins can cap the credits any one pull request may use. When a review would exceed the cap it steps down to a tier that fits, and the summary says so.

The console's diff view does not show files over 1 MiB; open those on the code host.

If your team regularly opens pull requests with hundreds of files, consider a size filter for automatic reviews and ask for a review on demand with `@mergeharbor review` when one is wanted.

## Perforce and other large estates

Large repositories are common on Perforce. MergeHarbor reviews Perforce Helix Core changes through Helix Swarm, with documented limits per review: up to 1,000 files, 4 MB per file and 64 MB in total. Files over these limits are left out of the review. Each new version of a Swarm review is reviewed in full, because incremental reviews are not supported there yet. Whole-codebase context needs Git Fusion or Helix4Git; without it, reviews see only the files the change touches. See [Perforce Helix Core](https://mergeharbor.com/docs/perforce).

## Self-hosted monorepos

If you [self-host MergeHarbor](https://mergeharbor.com/ai-code-review/self-hosted), you control the capacity. The `large` profile sizes workers for large monorepos, and the [sizing guide](https://mergeharbor.com/docs/self-hosting-sizing) suggests giving a large monorepo a worker of its own with `cells[].pins`.

Plan worker disk for repository mirrors and the code search index; the sizing guide measures the search index at about 2.7 times the indexed code. For very large estates, repositories are spread across cells, each with its own database, vector store and workers, and the guide suggests one cell up to about 50,000 repositories. Vectors live in PostgreSQL with pgvector by default, and the guide recommends switching a cell to Qdrant when it passes about 10 million vectors.

## Limits to plan around

To summarise the documented limits honestly:

- Files over 1 MB, binaries, generated and vendored files are not indexed.
- Older files are searchable by name and text but are not embedded until a pull request touches them.
- The model reads at most 800 lines per file read and about 12,000 characters per tool result.
- Calls are resolved precisely in Go, Java, JavaScript, TypeScript and Python; other languages match symbols by name or use structural or text-level parsing. Check [supported languages](https://mergeharbor.com/docs/languages) for yours.
- On Perforce: 1,000 files, 4 MB per file and 64 MB per review, no incremental reviews, and context only with Git Fusion.

None of these stop a review from running. They decide how much context it has.

## Try it on your monorepo

The useful test is your own repository and your own large pull requests. [Start a 14-day trial of the Team plan](https://app.mergeharbor.com/signup), with no card required, add a `.mergeharbor/` folder for one team, and compare its reviews with the rest of the repository.

## Further reading

- [Repository configuration](https://mergeharbor.com/docs/repository-config): `.mergeharbor/` folders, precedence and locks
- [Review tiers and credits](https://mergeharbor.com/docs/review-tiers)
- [Self-hosting sizing guide](https://mergeharbor.com/docs/self-hosting-sizing)
- [How AI code review works, step by step](https://mergeharbor.com/guides/how-ai-code-review-works)
- [Diff-only versus codebase-aware review](https://mergeharbor.com/guides/diff-only-vs-codebase-aware-review)
- [AI code review for enterprises](https://mergeharbor.com/ai-code-review/enterprise)