> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Review

> Automatic bug detection and fixes on every pull request

Macroscope automatically reviews every pull request for correctness. When it finds an issue, it leaves a comment on the PR describing the problem and suggesting a fix.

You can also configure fully customizable AI agents that trigger on every pull request open, push, and manual check rerun by setting up [Check Run Agents](/check-run-agents).

You can reply to any comment, give 👍 or 👎 feedback to help Macroscope learn, or ask it to [fix the issue for you](/fix-it-for-me).

## Code Review Settings

* Enabled by default on every linked repo.
* Toggle on/off per repo in **Settings → Repos**.
* Change the default for new repos in **Settings → Repos → Defaults**.
* Set **always-review labels** to force a review even when automatic review is off.
* Set **skip labels** to prevent review even when automatic review is on. Skip labels take precedence over always-review labels.

<Note>
  Go to **Settings → Repos** in the Macroscope web app to edit code review settings per-repo or in batch.
</Note>

## Detection Mode

Detection Mode lets you tune how Macroscope code review balances finding more bugs vs. minimizing noise. There are two options:

* **Prefer Coverage**: detects as many issues as possible. This gives higher bug detection rates, with an increase in overall comment volume and a higher likelihood of false positives. Recommended for teams who use coding agents to review and validate PR comments, since an agent can absorb the occasional false positive.
* **Prefer Precision**: prioritizes high-confidence findings. This gives lower bug detection rates, but also a lower likelihood of false positives. Recommended for teams who review comments manually in GitHub.

**Prefer Coverage** is the default for new and existing repositories.

### Configuring Detection Mode

Detection Mode can be set at two levels:

* **Per repository**, in **Settings → Repos**. Select one or more repos and choose a mode. Use **Defaults** to set the mode applied to newly linked repos.
* **Per developer**, in **Settings → Personal** under **Code Review → Detection Mode**. Choose **Prefer Coverage**, **Prefer Precision**, or **Repo Default**.

<Tip>
  A developer's Detection Mode overrides the repository setting for that developer's pull requests. Leaving the personal setting on **Repo Default** defers to the repository's mode.
</Tip>

## Manually Triggering a Review

Comment **"@macroscope-app review"** on any PR in GitHub to trigger a review, even if automatic code review is disabled for that repo.

## Code Review Activity Log

The Code Review activity log in the Macroscope web app shows all review comments across your repositories.

### Source Column and Filtering

Each comment displays a **Source** column indicating where the feedback originated (e.g. Correctness, Check Run Agent). Use the source filter to focus on comments from a specific review type.

Filters persist in the URL, so you can bookmark or share filtered views. When exporting to CSV, the export respects your current filters.

### Review Type Filtering in Feedback Metrics

Feedback metrics pages support filtering by review type. Select a specific type to see metrics for that review source, or view a cross-type overview to compare feedback across all review types.

## How Reviews Appear in GitHub

### Check Runs

When issues are found, the GitHub check run completes with `NEUTRAL` instead of `SUCCESS`. Check run details show per-file exclusion reasons.

### Comment Resolution

Comments link to the commit where they were resolved. Macroscope re-evaluates automatically when new code is pushed.

### Issue Severity Levels

* **CRITICAL**: data loss, security breach
* **HIGH**: production crashes, security degradation
* **MEDIUM**: broken functionality (recoverable)
* **LOW**: cosmetic, edge-case issues

## Excluding Files with `.macroscope/ignore.md`

<a id="excluding-files-from-code-review" />

<a id="macroscope-ignore" />

You can tell Macroscope to skip specific files during code review by adding a `.macroscope/ignore.md` file to your repository. The file uses a simplified [glob pattern](https://en.wikipedia.org/wiki/Glob_\(programming\)) syntax, one pattern per line. Lines starting with `#` are comments, blank lines are ignored.

### Setup

1. Create a file named `.macroscope/ignore.md` in your repository.
2. Add one file path pattern per line.
3. Commit and push. Macroscope picks it up automatically on the next review.

<Note>
  The legacy path `.macroscope-ignore` at the repo root is still supported for backward compatibility, but `.macroscope/ignore.md` is the recommended location. This consolidates all Macroscope configuration into the `.macroscope/` directory.
</Note>

### Example

```text theme={null}
# Vendor dependencies
vendor/**

# Generated code
*.pb.go
*.generated.go

# Lock files
*.lock

# Documentation assets
docs/**/*.pdf

# Log directories
logs/**
```

<Tip>
  Use `**` to match across directories, `*` to match within a single path segment, and `?` to match a single character. Patterns without a `/` match at any depth. Maximum 1,000 patterns.
</Tip>

### Default Ignore Patterns

Macroscope ships with a built-in set of ignore patterns covering vendored dependencies, generated code, binary assets, and test files. These are applied automatically when no `.macroscope/ignore.md` file exists in your repo.

<Warning>
  Creating your own `.macroscope/ignore.md` **replaces** these defaults rather than extending them. To preserve the defaults, copy the patterns below into your `.macroscope/ignore.md` file and add your own on top.
</Warning>

<AccordionGroup>
  <Accordion title="Default base patterns (vendored, generated, binary, etc.)">
    ```text theme={null}
    # === Vendored / dependency directories ===
    **/.git/**
    **/__pycache__/**
    **/.pytest_cache/**
    **/.mypy_cache/**
    **/.ruff_cache/**
    **/venv/**
    **/.venv/**
    **/node_modules/**
    **/site-packages/**
    **/.pnpm-store/**
    **/__Snapshots__/**
    **/__snapshots__/**
    **/.agents/skills/**
    **/.claude/skills/**
    **/.github/skills/**
    **/bower_components/**
    **/jspm_packages/**
    **/.next/**
    **/.svelte-kit/**
    **/vendor/**
    **/_vendor/**
    **/third_party/**
    **/Pods/**
    **/.bundle/**

    # === Root-anchored ambiguous directories ===
    build/**
    env/**
    ENV/**

    # === Generated / build-output directories (match anywhere) ===
    **/target/**
    **/generated/**
    **/intermediates/**
    **/generated_sources/**
    **/generated-sources/**
    **/generated-src/**
    **/src/main/generated/**

    # === Minified build output ===
    **/*.min.js
    **/*.min.css

    # === Generated protobuf / codegen files ===
    **/*_pb.d.ts
    **/*_pb.js
    **/*.pb.go
    **/*_pb2.py
    **/*_pb2_grpc.py
    **/*_pb2.pyi
    **/*.grpc.swift
    **/*.pb.swift
    **/*.sql.go
    **/*.designer.cs
    **/*.g.dart
    **/*.pb.dart
    **/*_pb.rb

    # === Package manager files ===
    **/go.mod
    **/package.json
    **/*.pbxproj
    **/*.xcstrings
    **/*.strings
    **/*.properties
    **/pom.xml
    **/Package.swift
    **/bun.lock
    **/.eslintrc
    **/.eslintignore

    # === Lock / sum files ===
    **/go.sum
    **/package-lock.json
    **/pnpm-lock.yaml
    **/yarn.lock
    **/Package.resolved

    # === Images ===
    **/*.jpg
    **/*.jpeg
    **/*.png
    **/*.gif
    **/*.svg
    **/*.ico
    **/*.webp
    **/*.bmp
    **/*.tiff

    # === Fonts ===
    **/*.woff
    **/*.woff2
    **/*.ttf
    **/*.eot
    **/*.otf

    # === Media ===
    **/*.mp3
    **/*.mp4
    **/*.wav
    **/*.avi
    **/*.mov
    **/*.mkv
    **/*.flac
    **/*.ogg
    **/*.srt

    # === Archives ===
    **/*.zip
    **/*.tar
    **/*.gz
    **/*.rar
    **/*.7z
    **/*.bz2

    # === Documents ===
    **/*.pdf
    **/*.doc
    **/*.docx
    **/*.xls
    **/*.xlsx
    **/*.ppt
    **/*.pptx

    # === Data / serialized ===
    **/*.db
    **/*.sqlite
    **/*.sqlite3
    **/*.parquet
    **/*.avro
    **/*.arrow
    **/*.npy
    **/*.pkl
    **/*.jsonl

    # === ML models ===
    **/*.onnx
    **/*.tflite
    **/*.h5
    **/*.safetensors

    # === Compiled / binary ===
    **/*.exe
    **/*.dll
    **/*.so
    **/*.dylib
    **/*.bin
    **/*.pyc
    **/*.class
    **/*.o
    **/*.a
    **/*.wasm

    # === Certificates / keys ===
    **/*.cer
    **/*.pem
    **/*.p12

    # === Platform-specific / non-reviewable ===
    **/*.stringsdict
    **/*.snap
    **/*.adoc
    **/*.arb
    **/*.lock
    **/*.po
    **/*.fbx
    **/*.log
    **/*.xib
    **/*.meta
    **/*.kml
    **/*.prefab
    **/*.eml
    **/*.csv
    **/*.grpc.reflection
    **/*.js.map
    ```
  </Accordion>

  <Accordion title="Default test file patterns">
    ```text theme={null}
    # === Go ===
    **/*_test.go

    # === TypeScript / JavaScript ===
    **/*.test.ts
    **/*.test.tsx
    **/*.test.js
    **/*.test.jsx
    **/*.test.mjs
    **/*.test.cjs
    **/*.test.mts
    **/*.test.cts
    **/*.spec.ts
    **/*.spec.tsx
    **/*.spec.js
    **/*.spec.jsx
    **/*.spec.mjs
    **/*.spec.cjs
    **/*.spec.mts
    **/*.spec.cts
    **/*.e2e.ts
    **/*.e2e.tsx
    **/*.e2e.js
    **/*.e2e.jsx
    **/*.e2e.mjs
    **/*.e2e.cjs
    **/*.integration.ts
    **/*.integration.tsx
    **/*.integration.js
    **/*.integration.jsx
    **/*.integration.mjs
    **/*.integration.cjs
    **/__tests__/**

    # === Python ===
    **/test_*.py
    **/*_test.py

    # === Java / Kotlin ===
    **/*Test.java
    **/*Tests.java
    **/*Spec.java
    **/*IT.java
    **/*ITCase.java
    **/*Test.kt
    **/*Tests.kt
    **/*Spec.kt
    **/*IT.kt
    **/*ITCase.kt
    **/src/test/java/**
    **/src/test/kotlin/**
    **/src/androidTest/**
    **/src/integrationTest/**

    # === Swift ===
    **/*Tests.swift
    **/*UITests.swift
    **/*Tests/**
    **/*UITests/**

    # === Rust ===
    **/tests/*.rs
    **/*_test.rs
    **/test_*.rs

    # === Ruby ===
    **/*_test.rb
    **/*_spec.rb
    **/test_*.rb

    # === Generic test directories ===
    **/test/**
    **/tests/**
    **/spec/**
    **/specs/**
    **/e2e/**
    ```
  </Accordion>
</AccordionGroup>

### Behavior

* Pattern matching is deterministic. If a file matches, it is always skipped, including on manual invocations. There is no override mechanism.
* Skipped files are listed in the check run details.

<Note>
  `.macroscope/ignore.md` affects code review and [Check Run Agents](/check-run-agents#macroscope-ignore). It does not affect commit summaries, status, or the Slack agent.
</Note>

## How Does Code Review Work?

<a id="how-code-review-works" />

Macroscope reviews every file in a PR. For ten natively-supported languages, dedicated AST codewalkers build a reference graph for lower-latency reviews. All other languages — including Elixir, Starlark, C/C++, PHP, and more — are fully reviewed via Macroscope's agentic analysis engine.

### Native AST Codewalkers

For natively-supported languages, Macroscope's code walkers parse the Abstract Syntax Tree to build a graph-based representation of your codebase. This enables deep, language-aware review with per-language model tuning and framework-specific handling (e.g. parsing `.vue` single-file components and Nuxt conventions). Pre-building the reference graph makes these reviews lower-latency.

**Languages with native AST codewalkers**: Go, Python, TypeScript, JavaScript, Vue.js (including Nuxt), Java, Rust, Kotlin, Swift, Ruby.

### Agentic Analysis

All other languages — including Elixir, Starlark, C/C++, PHP, and more — are fully reviewed via Macroscope's agentic analysis engine with full cross-file codebase context. Review latency is slightly higher than native-AST-walked languages, which pre-build the reference graph.

### Universal File Support

Config files, documentation, scripts, and other non-code files are also reviewed. Every file in a PR gets examined.

Macroscope also uses web search during review to pull in up-to-date context, such as latest library documentation, API signatures, and deprecation notices.

### Models

Macroscope's auto-tune system tests multiple model, prompt, and parameter combinations per language to find the best config. An LLM-driven curator analyzes failures and proposes improvements each iteration. [Learn more about our auto-tune system](https://macroscope.com/blog/we-stopped-writing-prompts).