# Macroscope's Agent Source: https://docs.macroscope.com/agent An AI agent that knows your codebase, git history, and connected tools Macroscope's agent researches your codebase, git history, and connected tools to answer questions and take action. To use Macroscope's Agent, you must configure Status. To configure Status, click on Status in the left sidebar, then complete the Product Overview and Sprint Cadence. Once your backfill has finished, you'll be able to use the Agent. Until setup is done, the sidebar stays trimmed to code review: see [Set Up Status](/setup-instructions#3-set-up-status). ## Tools ### Built-in These tools work out of the box once your repositories are connected. | Tool | What it can do | | - | - | | **Code search** | Finds relevant code, patterns, and implementations across all connected repos. | | **Git history** | Traces what changed, when, and why across commits, branches, and contributors. | | **Pull requests** | Searches PRs by status, date range, reviewer, or label. Views PR metadata, summaries, and review activity. | | **GitHub API** | Makes read-only queries for issues, check runs, deployments, commit statuses, and releases. | | **Code changes** | Creates branches, writes code, opens pull requests, updates existing branches, and adds reviewers. | | **Contributor metrics** | Queries engineering output and productivity metrics for individuals or teams over time. | | **Sprint reports** | Retrieves precomputed sprint summaries covering what the team shipped, organized by project and area. | | **Image generation** | Generates AI images from text descriptions, including diagrams, flowcharts, and illustrations. | | **Web search** | Searches the web for context beyond your codebase. | | **Docs search** | Searches Macroscope's own docs. | ### Connected Services These tools become available when you connect the corresponding service. See [Integrations](/integrations) for setup instructions. | Tool | What it can do | | - | - | | **Jira** | Looks up issues, tracks project progress, creates new issues across projects. | | **Linear** | Looks up issues, tracks project progress, creates new issues across teams, and breaks an existing issue into sub-issues. | | **BigQuery** | Browses datasets, inspects schemas, runs read-only SQL. Includes a methodology summary with each answer so you can verify the analysis. | | **PostHog** | Queries product analytics events, analyzes trends, searches session recordings, inspects feature flags, and runs HogQL queries. | | **Amplitude** | Runs event segmentation queries, analyzes conversion funnels and retention, searches for users, and inspects individual user event streams. | | **LaunchDarkly** | Lists projects, environments, and feature flags. Checks flag status, targeting rules, and variations across environments. | | **Sentry** | Searches error issues across projects, views issue details and event history, and investigates crashes and exceptions. | | **GCP Cloud Logging** | Discovers available log sources and queries log entries with filters on severity, resource type, timestamps, and payload content. | | **MCP Connectors** | Connect any [MCP-compatible server](https://modelcontextprotocol.io/) to extend the agent with custom tools (e.g. Datadog, PagerDuty, internal APIs). Configure in **Settings โ†’ Connections** (admin only). | ## Where to Interact with Macroscope's Agent * **Slack**: DM Macroscope (under **Apps**), tag `@Macroscope` in a channel, or add it to a group DM. * **GitHub**: Mention **@macroscope-app** in any PR discussion thread, or reply to any of Macroscope's inline code review comments. * **API**: Trigger the agent programmatically via [webhooks](/api). In Slack and GitHub, the agent reacts with ๐Ÿ‘€ to acknowledge a query and replies in-thread. You can attach images, screenshots, PDFs, and code snippets anywhere in a thread and the agent will use them as context. ## Pricing Agent usage is billed via **credits**. 1 credit = \$0.01. You get **1000 free credits per month**. Beyond the free credits, credits draw from your balance. Credits scale with LLM cost: a quick Slack question costs \~7 credits (\$0.07), a complex research task \~470 credits (\$4.70). Credits apply to: Slack queries, [Macros](/macros), [Webhooks](/api), and [Check Run Agents](/check-run-agents). See [Pricing](/pricing#agent) for details. ## Custom Instructions Set preferred tone, domain context, output format, or person-specific rules in **Settings โ†’ Workspace โ†’ Custom AMA (Ask Macroscope Anything) Instructions** (e.g. "customer success teammates should get less technical responses"). ## Examples * *"What did the team ship yesterday?"* * *"Draft release notes for everything shipped in the past 2 weeks."* * *"How does the authentication flow work?"* * *"Here's a screenshot of a bug. What's causing it? Open a PR to fix it and assign Eliza as a reviewer."* * *"How many signups did we get last week?"* (uses BigQuery or PostHog) * *"What feature flags are enabled in production right now?"* (requires LaunchDarkly) * *"Make a Jira ticket to track this bug. Assign it to Ikshita."* (requires Jira) * *"What's the status of Linear ticket ENG-431?"* (requires Linear) * *"Break ENG-431 into sub-issues, one per migration step."* (requires Linear) # API Source: https://docs.macroscope.com/api Trigger Macroscope's agent programmatically via webhooks To use the API, you must configure Status. To configure Status, click on Status in the left sidebar, then complete the Product Overview and Sprint Cadence. Once your backfill has finished, you'll be able to use the API. Macroscope exposes an inbound webhook that triggers the agent. It's the same agent you use in Slack and GitHub, but invoked via HTTP so you can call it from CI pipelines, scripts, cron jobs, or any other system. When the agent finishes, you can get the results two ways: * **Push**: Macroscope delivers them to a destination you specify (a Slack channel or an external URL). * **Pull**: omit the destination and poll for the result using the token returned by the trigger. ## Setup 1. Go to **Settings โ†’ Connections โ†’ Webhooks** 2. Click **Add Webhook** and give it a name (e.g. `ci-pipeline`) 3. Copy your **API key**. It's shown once and can't be retrieved later. 4. Copy your **Trigger URL**. You can access it anytime in Settings โ†’ Connections โ†’ Webhooks. Your **Trigger URL** will follow this format: ``` POST https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger ``` ## URL Allowlisting If you want Macroscope to deliver results to an external URL (rather than Slack), that URL must be allowlisted first. For example, if you're routing results to a Zapier or n8n webhook endpoint, add that URL here. Manage the list in **Settings โ†’ Connections โ†’ Webhooks โ†’ Allowed External URLs**. Only GitHub organization admins can add or remove URLs. A delivery URL must be a public HTTPS endpoint. Macroscope rejects a URL that is not `https://`, carries credentials in the URL (`https://user:pass@host`), or names a private, loopback, link-local, or otherwise reserved address, whether it is written as a literal (`https://10.0.0.5/hook`) or resolves to one at delivery time. Redirects are not followed. A `3xx` response is reported as a delivery failure rather than chased to a new destination, so point the allowlist at the final endpoint. ## Request Every request needs two headers: ```bash theme={null} -H "Content-Type: application/json" -H "X-Webhook-Secret: your-api-key" ``` POST a JSON body to your trigger URL: The question to ask the agent. Where to deliver the results. Use `slackChannelId` (string) to post to Slack, or `webhookUrl` (string) to POST to an external URL (must be [allowlisted](#allowed-external-urls)). Optionally include `slackThreadTs` (string) to reply in a specific Slack thread. **Optional.** Omit it to retrieve the result by [polling](#polling-for-results) instead. IANA timezone (e.g. `America/Los_Angeles`). Affects date references in the query. The request returns `202 Accepted` with a job token and poll URL: ```json theme={null} { "jobToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "pollUrl": "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-jobs", "workflowId": "abc-123-def-456" } ``` * **`jobToken`**: a signed token (valid \~1 hour) authorizing you to read this one job's result. Send it as an `Authorization: Bearer` header when polling. * **`pollUrl`**: where to poll for the result. The token is **not** in the URL. * **`workflowId`**: *deprecated*. ## Example Requests **Deliver results to Slack:** ```bash theme={null} curl -X POST \ "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \ -H "Content-Type: application/json" \ -H "X-Webhook-Secret: your-api-key" \ -d '{ "query": "What were the main changes this week?", "responseDestination": { "slackChannelId": "C0123456789" }, "timezone": "America/Los_Angeles" }' ``` **Deliver results to a Slack thread:** ```bash theme={null} curl -X POST \ "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \ -H "Content-Type: application/json" \ -H "X-Webhook-Secret: your-api-key" \ -d '{ "query": "Investigate this alert and respond in thread", "responseDestination": { "slackChannelId": "C0123456789", "slackThreadTs": "1234567890.123456" }, "timezone": "America/Los_Angeles" }' ``` **Deliver results to an external URL:** ```bash theme={null} curl -X POST \ "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \ -H "Content-Type: application/json" \ -H "X-Webhook-Secret: your-api-key" \ -d '{ "query": "What were the main changes this week?", "responseDestination": { "webhookUrl": "https://your-endpoint.com/callback" }, "timezone": "America/Los_Angeles" }' ``` ## Polling for results If you didn't set a `responseDestination`, poll the `pollUrl` from the trigger response. Send the `jobToken` as a bearer token: ```bash theme={null} curl -i "$POLL_URL" -H "Authorization: Bearer $JOB_TOKEN" ``` | Status | HTTP | Body | | - | - | - | | Still running | `202` | `{ "status": "running" }` | | Finished | `200` | `{ "status": "completed", "response": "..." }` | | Failed | `200` | `{ "status": "failed" }` | While running, the response carries a `Retry-After` header (seconds) suggesting how long to wait before polling again. The job token is valid for about **one hour**. If it expires before the job finishes, you'll get `403`; re-trigger to get a fresh one. ### Example: trigger and poll ```bash theme={null} # 1. Trigger without a destination RESP=$(curl -s -X POST \ "https://hooks.macroscope.com/api/v1/workspaces/{workspaceType}/{workspaceId}/query-agent-webhook-trigger" \ -H "Content-Type: application/json" \ -H "X-Webhook-Secret: your-api-key" \ -d '{ "query": "What were the main changes this week?" }') JOB_TOKEN=$(echo "$RESP" | jq -r .jobToken) POLL_URL=$(echo "$RESP" | jq -r .pollUrl) # 2. Poll until done while :; do OUT=$(curl -s "$POLL_URL" -H "Authorization: Bearer $JOB_TOKEN") [ "$(echo "$OUT" | jq -r .status)" != "running" ] && break sleep 10 done echo "$OUT" | jq -r .response ``` ## Response Payload When the agent finishes, Macroscope POSTs this to your Slack channel or URL: ```json theme={null} { "query": "What were the main changes this week?", "response": "Here are the main changes...", "workflowId": "abc-123-def-456" } ``` ## Error Codes | Code | Meaning | | - | - | | `202` | Query accepted. | | `400` | Malformed request or missing `query`. | | `401` | Missing or invalid `X-Webhook-Secret`. | | `403` | Wrong workspace, or webhook URL not allowlisted or not a permitted public HTTPS endpoint. | When polling: | Code | Meaning | | - | - | | `200` | Job finished (`completed` or `failed`). | | `202` | Still running; retry after the `Retry-After` interval. | | `401` | Missing or invalid job token. | | `403` | Job token expired, or doesn't match this workspace. | | `404` | Job not found. | ## Use Cases * **Post-deploy summaries**: GitHub Actions runs a deploy, triggers a webhook asking "what changed in this release?", and Macroscope posts a plain-English summary to your team's Slack channel. * **Incident response**: wire a PagerDuty or Sentry alert to trigger a Macroscope webhook. The agent can investigate the error, open a PR with a proposed fix, assign the most relevant teammate as a reviewer, and post a summary to your on-call Slack channel. * **No-code automations**: a Zapier or n8n workflow triggers Macroscope every Monday morning to generate a weekly engineering digest and routes the answer to email, Notion, or wherever your team tracks updates. * **Synchronous Q\&A / chatbots**: trigger a query from your own app with no destination, poll until complete, and show the answer inline in a custom "ask Macroscope" experience. # Approvability Source: https://docs.macroscope.com/approvability Auto-approve low-risk PRs that pass code review Disabled by default. Turn it on per repo under [**Settings โ†’ Repos โ†’ Features**](/settings#features); the settings below it appear once it's on. Only a **GitHub Admin** can change it. Approvability ## How It Works When a PR is opened or updated, Macroscope evaluates up to three criteria before auto-approving. Ownership (via CODEOWNERS) is disabled by default; Eligibility and Correctness are always active. All active criteria must pass for auto-approval. If any fail, the PR can still be approved manually. ### The verdict Every PR gets a comment leading with one of four verdicts, followed by a sentence giving Macroscope's own assessment of the PR and the reasoning behind it. The verdict is what happened to the PR; the assessment is Macroscope's view of it, and the two are separate because a PR Macroscope finds approvable can still go unapproved because of how your workspace is configured. | Verdict | Meaning | | - | - | | **Approved** | Approvable, nothing blocking, and automatic approval is on. Macroscope posted a real GitHub approval. | | **Would Approve** | Approvable, but something held it: automatic approval is off, an ownership requirement, outstanding correctness findings, a correctness review that could not report, or [a correctness review a limit stopped from running](#limit-stops-correctness). The comment lists everything blocking it. | | **Not approved** | The eligibility agent judged the PR not a candidate for automatic approval, and says why. | | **Skipped** | Macroscope reached no verdict at all: a protected path, a diff too large to analyze, an unparseable result, or [a spend limit that stopped the check itself](#limit-stops-approvability). | A **Would Approve** verdict is not a hedge on your code: Macroscope found the PR eligible and is telling you which setting or requirement stopped the approval. ### 1. Eligibility Is this PR a good candidate for auto-approval? Macroscope evaluates the changes, code ownership, git blame history, and the author's role. If your repo has a `CODEOWNERS` file, Macroscope factors in the author's relationship to changed files. * **Typically eligible**: docs, tests, code behind feature flags, simple bug fixes, copy changes. * **Not eligible**: large refactors, schema changes, security/auth/billing code, breaking changes. ### 2. **Correctness** Are there unresolved correctness findings at or above your repo's Minimum Blocking Severity? By default, correctness is a **hard gate**: an unresolved correctness finding at or above your repo's Minimum Blocking Severity blocks automatic approval. Resolving the final blocking review thread clears that gate automatically. If nothing else blocks approval and automatic approval is enabled, Macroscope approves the PR without requiring a new commit or Approvability run. If resolving the final blocking thread does not update an existing PR, rerun Approvability once from the Checks tab. The way to disable this is to set [**Minimum Blocking Severity**](#minimum-blocking-severity) to **Off**, which stops outstanding comments from automatically blocking approvability. The approvability agent then makes a non-deterministic evaluation based on all available information, including outstanding correctness comments, so it may still return **Not approved** on their merits. Your [custom instructions](#custom-eligibility-rules) control how it weighs them; see also [Letting Eligibility decide correctness instead](#letting-eligibility-decide-correctness-instead), which tells the agent to leave correctness out of the judgment altogether. By default, a correctness review that cannot report also blocks approval. If the review finds issues but cannot post them, Approvability reports **Would Approve** instead of approving on findings nobody can see. It states that the assessment omitted those findings and lists the missing review as a blocker. **Off** covers this case too by removing the deterministic failure regardless of what the review found or whether it posted the findings. Telling Macroscope to ignore correctness in your guidelines does the same. With either setting, Eligibility decides alone. Whether a review that never ran blocks depends on **why** it never ran, and the line is not about severity: * **You turned it off**: correctness disabled for the repo, an excluded target branch, a skipped author, or simply no reviewable code in the PR. Nothing was owed, so nothing is missing: these never block, and approvals continue exactly as before. * **A limit stopped it**: a spend limit, a cost limit, an exhausted credit balance, or the per-PR cap on automatic reviews. Here a review *was* expected and did not happen, so Macroscope is missing an input it normally weighs. These now hold the PR at **Would Approve** rather than approving without it. See [When a limit stops the correctness review](#limit-stops-correctness). Comments from an *earlier* review still count either way. They remain outstanding until resolved, so a review that never ran does not clear a blocker raised by a previous review. If those comments exist, they hold the PR, not the missing review.
#### When a limit stops the correctness review If a spend limit, cost limit, credit balance, or the per-PR cap on automatic reviews stops a correctness review from running, that PR is held at **Would Approve** instead of being approved. Macroscope normally weighs a correctness verdict when deciding approvability; a limit means the review was expected and did not happen, so the verdict is missing rather than clean. This is not a severity question, and there is nothing in the PR to fix: no finding was produced. The comment names the limit that stopped the review and links the setting that clears it: | What stopped it | What clears it | | - | - | | Monthly spend limit, or an exhausted credit balance | Raise the limit or add credits in **Billing settings**. A manual review does **not** help here: the workspace cap applies to it too. | | Per-review or per-PR cost limit | Raise the limit in **Billing settings**, or comment `@macroscope-app review this PR` to bypass the limit and review this PR now. | | Per-PR cap on automatic correctness reviews | Raise the limit in repo settings, or comment `@macroscope-app review this PR` to bypass the cap and review this PR now. | Repos that have correctness **disabled** are unaffected and keep approving as before: see the two cases listed under Correctness above. A repo that hits a limit stops auto-approving until the limit clears or is raised; once a correctness review runs again, the next Approvability run approves normally. Both ways of taking correctness out of the gate cover this too. With [**Minimum Blocking Severity: Off**](#minimum-blocking-severity), or with [custom rules telling Macroscope to ignore correctness](#letting-eligibility-decide-correctness-instead), a limit-stopped review does **not** hold the PR: Eligibility decides alone, and the comment notes that no correctness review stood behind the verdict.
#### When a limit stops the Approvability check itself The section above is about a limit stopping the **correctness review**: Approvability still runs and holds the PR at **Would Approve**, naming the missing input. A limit can also stop **Approvability itself**, which looks different: there is no verdict and no comment, only a check run concluded **skipped**. | What stopped it | What you see | What clears it | | - | - | - | | Monthly spend limit, or an exhausted credit balance | The check is concluded **skipped**, naming the limit | Raise the limit or add credits in **Billing settings** | | Correctness per-PR cost limit | The check is concluded **skipped**, reporting what the PR has cost so far against the cap | Raise the cap in **Billing settings**, or comment `@macroscope-app review this PR` | A skipped check never fails, so [using Approvability as a required status check](#using-approvability-as-a-required-status-check) will not block a merge because a limit was reached: a red check nobody on the PR can turn green would only block the wrong person. Worth knowing about the per-PR cost limit specifically: it totals only **Code Review** spend on the PR. Approvability's own spend does not add to it, so Approvability can be stopped by a cap it never contributed to. This applies to every workspace, including one that has never touched the setting: the Correctness per-PR cap cannot be turned off and defaults to \$50. That is intentional rather than an oversight. Approvability reads the correctness review's findings to reach a verdict, so once the cap has stopped correctness on a PR, continuing to run Approvability would produce a verdict from incomplete input: worse than reporting no verdict at all. The separate [Check Run Agents per-PR limit](/pricing#cra-per-pr-limit) does **not** affect Approvability. Reaching it stops agents on the PR and leaves the Approvability check alone. See [What the Correctness per-PR cap counts](/pricing#per-pr-cap). The Eligibility agent runs even when correctness is already blocking. Its verdict cannot change the outcome, but it tells you something correctness cannot: whether Macroscope would have approved the PR but for the findings, or would have held it anyway. That is the difference between a **Would Approve** verdict and a **Not approved** one. #### Minimum Blocking Severity **Minimum Blocking Severity** is a per-repo setting that controls which severity of unresolved correctness comments blocks auto-approval. Outstanding correctness comments at or above the configured severity block approval; comments below the threshold do not. Choose from **Low**, **Medium**, **High**, **Critical**, or **Off**: the default is **Medium**. **Off** removes the deterministic gate entirely. Correctness never fails a PR on its own, even for a ๐Ÿ”ด **Critical** finding or when the review could not post its findings. It does *not* do two things: * It does not silence correctness review. Findings are still posted on the PR as usual; they just stop holding up approval by themselves. * It does not override the Eligibility agent. The agent still runs, sees the findings, and reports its view. A ๐Ÿ”ด **Critical** finding describing a real defect can still send the PR to human review based on its content rather than its badge. That second point is the distinction worth holding on to: **Off** removes the automatic block, not the judgment. If you want correctness excluded from the judgment as well, use [Letting Eligibility decide correctness instead](#letting-eligibility-decide-correctness-instead). Find it in **Settings โ†’ Repos โ†’ Approvability** (shown once Approvability is enabled). Only a **GitHub Admin** can change it. A comment counts as outstanding until its review thread is resolved on GitHub, or the comment is deleted. Comments with no recorded severity are treated as **Medium**. The threshold applies to the Eligibility judgment as well: a Macroscope correctness comment below it does not, on its own, send the PR to human review. Comments at or above the threshold still do, and so does anything else that warrants review: a comment from a human reviewer or another tool, or the nature of the changes themselves. #### Check Run Conclusion **Check Run Conclusion** is a per-repo setting that controls how the approvability check reports a PR it does not approve: **Neutral** (the default) or **Failure**. It is the settings-page equivalent of the [`conclusion`](#supported-fields) front matter field, for teams that cannot commit `.macroscope/approvability.md` into every repository. * **Neutral**: the check is informational. It reports the verdict and never blocks merging. * **Failure:** The check fails, so adding `Macroscope - Approvability Check` as a [required status check](#using-approvability-as-a-required-status-check) blocks the merge until the PR becomes approvable. Only two outcomes the author can clear ever fail: a **Not approved** verdict and outstanding correctness findings at or above your [Minimum Blocking Severity](#minimum-blocking-severity). A **Skipped** verdict never fails, regardless of this setting. Neither does [a correctness review stopped by a limit](#limit-stops-correctness). That case holds the PR at **Would Approve** but concludes **Neutral** because the author cannot clear a workspace limit, and a red check they cannot turn green would block the wrong person. Everything documented under [Using approvability as a required status check](#using-approvability-as-a-required-status-check) applies identically however you set it, including the full list of outcomes on each side and how a `failure` is cleared. In particular, PRs held by [protected configuration paths](#protecting-review-configuration) still conclude **Neutral**, so this setting can never make a configuration PR unmergeable. Find it in **Settings โ†’ Repos โ†’ Approvability** (shown once Approvability is enabled). Only a **GitHub Admin** can change it. It also has a workspace default and can be applied across many repos at once from **Settings โ†’ Repos** with repos selected: the same batch flow as [Minimum Blocking Severity](#minimum-blocking-severity). **Front matter always wins.** If `.macroscope/approvability.md` sets `conclusion`, that value applies and this setting is ignored for that repo: including `conclusion: neutral`, which is how a single repo opts out of a workspace-wide **Failure**. A file that omits `conclusion` does not override anything, so repos keep whatever the setting says even when they have guidelines for other purposes. The workspace default seeds **newly added** repos. Changing it does not move repos that already exist: batch-edit them for that. #### Letting Eligibility decide correctness instead This is the stronger of the two ways to stop correctness from gating approval, and unlike [**Minimum Blocking Severity: Off**](#minimum-blocking-severity) it is not a setting: state it in your [custom eligibility rules](#custom-eligibility-rules). If your `.macroscope/approvability.md` **explicitly** says correctness issues must not factor into approvability, Macroscope stops treating correctness as a gate for that repo and lets the Eligibility judgment weigh the findings on its own: ```text theme={null} Correctness issues and bugs found by code review must NOT factor into the approvability decision. Judge this PR on the nature of the change alone. ``` This has to be explicit about correctness issues or bugs. Guidelines that only mention external reviewers' comments do not qualify, and silence or ambiguity leaves the gate on. The difference from **Off** is what each asks of the agent: **Off** stops correctness from failing the PR automatically but leaves the agent weighing the findings, whereas this tells the agent to leave them out of the judgment altogether. It also keeps the choice visible in the repo rather than in a settings page. *** Results appear as `Macroscope - Approvability Check` in the Checks tab and as a PR comment with detailed reasoning. Approvability ## Custom Eligibility Rules Add a `.macroscope/approvability.md` file to your repo to define rules on top of the defaults. Your custom rules are **additive**: they are combined with the built-in eligibility criteria, not a replacement. ### Plain text rules The simplest approach is a plain markdown file with your rules: ```text theme={null} If a PR changes files in any of the following paths, DO NOT auto-approve: - services/auth - services/billing - targets/auth ``` ### Front matter configuration For more control, add YAML front matter to configure the approvability agent's behavior: ```markdown theme={null} --- tools: - github_api_read_only - modify_pr conclusion: neutral --- If a PR changes files in any of the following paths, DO NOT auto-approve: - services/auth - services/billing - targets/auth If the verdict is "not approved" and the PR touches services/auth/, request a review from @security-team. ``` #### Supported fields | Field | Default | Description | | - | - | - | | `tools` | `[]` | Additional tools for the approvability agent. The agent always has file browsing and git tools; this field adds more capabilities. | | `conclusion` | [Check Run Conclusion](#check-run-conclusion) setting, or `neutral` | Controls the check run result when a PR is not approved. `neutral` (recommended) makes the check informational, so it never blocks merging. To gate merges on human approval, use GitHub's [required reviewers](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging). `failure` makes the check block merges through [required status checks](#using-approvability-as-a-required-status-check); review the caveats before enabling it. `failure` does not apply to PRs held by [protected configuration paths](#protecting-review-configuration), which always conclude `neutral`. Setting this field here **overrides** the [Check Run Conclusion](#check-run-conclusion) repo setting; omit it to use that setting. | | `waitsFor` | Correctness, Check Run Agents & external review tools | Additional check run names that must complete before approvability runs. Even when unset, approvability automatically waits for the Correctness check, every [Check Run Agent](/check-run-agents) on the commit, and recognized third-party review tools (Cursor BugBot, Greptile) before deciding: this field adds prerequisites on top of those. Supports `["*"]` wildcard to wait for all check runs. See [Waiting for Other Checks](#waiting-for-other-checks). | | `waitsForTimeout` | `20` | How long to wait for prerequisites to **finish**, in minutes (`1` to `60`). Only meaningful when `waitsFor` is set. | | `waitsForDiscoveryTimeout` | `1` (60 seconds) | How long to wait for a prerequisite to **appear** on the commit before treating it as absent, in minutes (`1` to `60`). Raise this when a check is published conditionally or late. See [Check Run Agents](/check-run-agents#late-prerequisites) for the full explanation and trade-off. With named prerequisites, it is a deadline and costs nothing once they appear. With `waitsFor: ["*"]`, it is a **floor paid on every run**, so every PR's verdict is delayed by that window. That combination triggers a warning on the check run page. The value is capped at `waitsForTimeout` and only matters when `waitsFor` is set. | | `neverApprove` | `[]` | Additional paths that are never auto-approved when a PR changes them. Glob patterns, same syntax as Check Run Agent `include`/`exclude`. This list only ever **adds** to the always-on protection on your approvability file: see [Protecting review configuration](#protecting-review-configuration). | | `alwaysApprove` | `[]` | Paths that skip the eligibility agent, but only when **every** file the PR changes matches one of them. Glob patterns, same syntax as `neverApprove`. Skips the agent, not the other approval conditions: see [`alwaysApprove`](#alwaysapprove--skipping-the-agent-for-routine-paths). | #### Available tools Tools extend what the approvability agent can do beyond its defaults (file browsing and git tools): * `github_api_read_only`: search code and read GitHub metadata * `modify_pr`: request reviewers or post PR reviews * `slack`: post messages to Slack channels * `launchdarkly`: check feature flag status * `web_tools`: search the web * `issue_tracking_tools`: query linked Jira/Linear tickets The `modify_pr` tool enables instructions like "request a review from @security-team when the verdict is not approved." Without it, the agent can only analyze and report: it can't take actions on the PR.
#### Waiting for other checks By default, approvability waits for the Correctness check, any [Check Run Agents](/check-run-agents), and recognized third-party review tools (Cursor BugBot, Greptile) before making its decision, so their findings are considered in the verdict. Use `waitsFor` to add CI steps whose results should affect the verdict, such as linters, deployment checks, or other external tools not covered by the built-in list. **Wait for specific checks:** ```yaml theme={null} --- waitsFor: - "CI / lint" - "Macroscope - Security Review" conclusion: neutral --- If CI lint or the security review flagged issues, DO NOT auto-approve. ``` **Wait for all checks (wildcard mode):** ```yaml theme={null} --- waitsFor: - "*" --- Consider findings from ALL CI steps when deciding whether to auto-approve. ``` Wildcard mode waits for every check run on the commit except `Macroscope - Approvability Check` itself. This is useful when you have multiple Check Run Agents posting review comments and want approvability to consider all of their findings. **Custom timeout:** The default wait is 20 minutes. Set `waitsForTimeout` to change it (1-60 minutes): ```yaml theme={null} --- waitsFor: - "deploy-to-staging" waitsForTimeout: 45 --- ``` A prerequisite also has to *appear* on the commit within a shorter discovery window (60 seconds by default) or it is treated as absent. Set `waitsForDiscoveryTimeout` to give more time to a check published conditionally, behind an earlier job, or by a workflow queued while a previous run is still cancelling: ```yaml theme={null} --- waitsFor: - "pre-commit / pre-commit" waitsForDiscoveryTimeout: 10 --- ``` The cost of a longer window is that a check which never appears at all takes that long to give up on. See [Check Run Agents](/check-run-agents#late-prerequisites) for the full explanation. Combining a longer window with `waitsFor: ["*"]` costs more. With named prerequisites, the window is a deadline for *appearance*. Once they appear, the window ends and the wait continues only until they conclude. A wildcard wait has no names to look for, so it must outlast the window before it can conclude that every check on the commit has finished. Every PR's approvability verdict is delayed by at least that window, whether or not anything was published late. The check run page warns about this combination rather than rejecting it, because the delay may be appropriate for a check that is genuinely published that late. **Behavior summary:** | Scenario | What happens | | - | - | | Prerequisites complete | Approvability proceeds with its eligibility assessment, considering review comments posted by the waited-for checks. | | Prerequisite never appears within the discovery window (60 seconds by default) | The prerequisite is treated as absent and approvability proceeds. Check that the name in `waitsFor` matches the check run name exactly as it appears on GitHub; if the step is real but published late, raise `waitsForDiscoveryTimeout`. | | Prerequisite does not complete within timeout | Approvability proceeds without waiting further. Increase `waitsForTimeout` if the step is slow. | | Circular dependency | Detected at parse time. For example, if a CRA has `waitsFor: ["Macroscope - Approvability Check"]` and approvability has `waitsFor: ["*"]`, the cycle is detected and the affected CRA skips with a descriptive error. | Approvability always waits for the Correctness check and recognized third-party review tools (Cursor BugBot, Greptile) regardless of `waitsFor`: this field controls additional prerequisites beyond those built-in waits. Named mode supports up to 10 entries. #### Using approvability as a required status check Most teams should leave `conclusion` at the default (`neutral`) and use GitHub's [required reviewers](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging) to gate merge on human approval. The approvability check surfaces the verdict; the reviewer requirement does the blocking. This is the simplest and most predictable setup. If you want the approvability check itself to hard-block merge when a PR is not approved, turn the conclusion to `failure` and add `Macroscope - Approvability Check` as a [required status check](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) in your branch protection rules. There are two ways to turn it on, and they behave identically from here on: * Set the [**Check Run Conclusion**](#check-run-conclusion) repo setting to **Failure**. This needs no file, has a workspace default, and can be applied to many repos at once. * Set `conclusion: failure` in `.macroscope/approvability.md` front matter. This is per-repo, lives in source control, and overrides the setting. Be aware of how GitHub handles this combination. **When the check concludes `failure` (merge blocked).** Only two outcomes fail the check, and both are ones the author can clear by acting on the PR: * The approvability agent returned a verdict of **Not approved**. * Correctness findings are posted on the PR and still outstanding at or above your repo's [Minimum Blocking Severity](#minimum-blocking-severity). Setting that to **Off** removes this outcome entirely, leaving the agent's verdict as the only way the check fails. **When the check concludes `neutral` or `skipped` (merge NOT blocked).** GitHub counts [`success`, `skipped`, and `neutral`](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks) as passing a required status check. Approvability deliberately concludes `neutral` instead of `failure` whenever the hold is something the author cannot clear by changing the PR: failing on those would leave the PR permanently unmergeable: * The PR modifies `.macroscope/approvability.md`, modifies a path protected by `neverApprove` (see [Protecting review configuration](#protecting-review-configuration)), or modifies `CODEOWNERS` without owning it. * The diff is too large to analyze, or the agent returned no usable response. * Correctness could not report: it found issues but was unable to post them, reached no verdict, or never ran. * The PR was authored by Macroscope, or auto-approval is switched off for the repo. * The approvability agent itself errored or timed out. It concludes `skipped`, which also passes, when approvability is disabled for the PR (draft PR, repo setting off, skipped author), when a billing or usage limit is reached, and when a push leaves the diff unchanged (for example a rebase, where the prior analysis is reused). `conclusion: failure` gates on the **verdict**, not on availability. If the agent errors, times out, hits a usage limit, or otherwise cannot reach a verdict, the check concludes `neutral` and GitHub allows the merge: it is **not** a fail-closed gate. If you need a PR to stay blocked whenever Macroscope cannot decide, use GitHub's [required reviewers](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging) instead. **Clearing a `failure`.** How you clear it depends on which of the two outcomes failed the check. * **Outstanding correctness findings: resolve them.** Resolving the final blocking thread clears the correctness gate automatically. If nothing else blocks approval, Macroscope updates the Approvability check and comment and, when automatic approval is enabled, approves the PR. Reopening a blocking thread withdraws that approval. * **A Not approved verdict: re-trigger the check.** Resolving comments says nothing about that verdict, so the conclusion stands until approvability re-evaluates the PR: a new commit, a re-run from the Checks tab, or an `@macroscope` mention. One thing that looks like it should clear a `failure` does not: **a PR review approval alone does not clear a failing required status check.** GitHub treats approvals and status checks as independent gates, so a human approval leaves the check exactly where it was. The legacy path `macroscope_approvability.md` at the repo root is still supported for backward compatibility, but `.macroscope/approvability.md` is the recommended location. Front matter is only supported in the `.macroscope/approvability.md` path: the legacy path treats the entire file as plain text rules.
## Protecting review configuration Macroscope reads `.macroscope/approvability.md` from the pull request's most recent commit, so an edit takes effect in the PR that makes it. A PR that changes the rules Macroscope approves by should not then be approved using the rules it just changed. Two things prevent that. ### Your approvability file is always held for a human Any PR that adds, edits, renames, or deletes `.macroscope/approvability.md` (or the legacy `macroscope_approvability.md`) automatically gets the verdict **Skipped**, and the eligibility agent never runs. Macroscope decides this before the approvability agent starts, so nothing written in the file, including custom rules, front matter, or instructions to approve config changes, can change the outcome. This is always on. There is no setting that turns it off, and that is deliberate: it is what makes your own `neverApprove` list trustworthy. What the hold protects is the **eligibility rules**: the instructions the agent reads to decide whether a PR is approvable. Those live only in the file, so editing them always goes through code review. [Check Run Conclusion](#check-run-conclusion) is not one of them: it changes how a verdict is *reported*, never how it is *reached*, and it can only ever make the check stricter than the `neutral` default. That is why it is safe to expose as a setting, and why the rules themselves are not. ### `neverApprove`: additional protected paths Use `neverApprove` to extend that protection to any other path you want a human to look at: ```markdown theme={null} --- neverApprove: - .macroscope/ignore.md - .macroscope/check-run-agents/** - .github/workflows/** - CODEOWNERS --- Approve routine dependency bumps and documentation changes. ``` Any PR that changes a file matching one of these patterns gets the verdict **Skipped**, without the agent running. Patterns use the same glob syntax as Check Run Agent `include`/`exclude`: a pattern with no `/` matches at any depth (`CODEOWNERS` matches `CODEOWNERS` and `docs/CODEOWNERS`), and `**` matches across directories. Matching is case-sensitive. A pattern Macroscope cannot parse is skipped, with a warning in the check run details: check there after editing the list, since a skipped pattern protects nothing. Renames and deletions count as changes to both the old and the new path, so moving a protected file out of the way still holds the PR. `neverApprove` can only **add** paths. It cannot remove or narrow the protection on your approvability file, and no setting can. It takes priority over [`alwaysApprove`](#alwaysapprove--skipping-the-agent-for-routine-paths), so a path in both lists is held. This is also why the list is safe to trust: a PR cannot quietly delete an entry from it without editing `.macroscope/approvability.md`, which is itself always held for a human. ### What these holds do and don't do A hold from either rule means the PR is not auto-approved and is marked **Skipped**. It does not block merging on its own. These checks conclude `neutral` even when you set `conclusion: failure` in front matter or through the [Check Run Conclusion](#check-run-conclusion) setting. A PR that updates your Macroscope configuration therefore cannot be made unmergeable by the check itself. Merge protection stays with your GitHub [required reviewers](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging), where a human reviews and merges the change. For the full list of what concludes `failure` versus `neutral`, see [Using approvability as a required status check](#using-approvability-as-a-required-status-check).
## `alwaysApprove`: skipping the agent for routine paths Some changes do not need a judgment call. Lockfile bumps, vendored dependencies, generated code, a translations directory: if a PR touches nothing else, there is nothing for the eligibility agent to weigh. `alwaysApprove` names those paths. When **every** file a PR changes matches one of the patterns, Macroscope finds the PR approvable without running the agent, and the run is [free](#pricing): ```markdown theme={null} --- alwaysApprove: - "**/*.lock" - vendor/** - "**/*.pb.go" --- Approve routine dependency bumps and documentation changes. ``` ### All, not any This is the opposite of how `neverApprove` matches, and the difference is the point. `neverApprove` fires when **any** changed file matches: one protected file is enough to hold the whole PR. `alwaysApprove` fires only when **every** changed file matches. A PR that updates `vendor/` *and* changes your scheduler is not a vendor PR, so it goes to the agent exactly as it would have. That also means a partial match costs you nothing and changes nothing. If you are unsure whether a pattern is too broad, the worst case is that PRs you expected to skip the agent do not. Renames count as changes to both the old and the new path, so moving a file *out* of a covered directory is not covered: the destination is a path you did not list. ### What it skips, and what it does not `alwaysApprove` skips the eligibility agent. It does not skip anything else that has to be true before Macroscope approves a PR: | Still applies | Effect | | - | - | | Correctness findings at or above your [Minimum Blocking Severity](#minimum-blocking-severity) | The PR is not approved. The verdict is **Would Approve**. | | Approvability not enabled for the repo | The PR is not approved. The verdict is **Would Approve**. | | The PR was authored by Macroscope | The PR is not approved. The verdict is **Skipped**. | | Every [wait](#waiting-for-other-checks): Correctness, Check Run Agents, external review tools, `waitsFor` | Approvability still waits for all of them before deciding. | One hold does *not* apply. A diff **too large to analyze** does not stop a fully covered PR: that hold exists because the agent cannot read the change, and on these paths there is nothing for it to read. A large vendored dependency bump is exactly the shape that is both too big to analyze and entirely covered. The review still runs. What you are switching off is the judgment about whether the change is worth a human's attention, not the analysis of whether it is correct. ### Precedence Three rules are evaluated before `alwaysApprove`, and none of them can be overridden by it: 1. **Your approvability file.** A PR that adds, edits, renames, or deletes `.macroscope/approvability.md` is held for a human: including the PR that adds `alwaysApprove` itself. See [Protecting review configuration](#protecting-review-configuration). 2. **[`neverApprove`](#neverapprove-additional-protected-paths).** If a path appears in both lists, or a PR matches both, `neverApprove` wins and the PR is held. 3. **`CODEOWNERS` changed by a non-owner.** Held, unchanged. Even `alwaysApprove: ["**"]`, meaning "approve everything," cannot approve a PR that rewrites your approval rules, strips a protection you added, or changes `CODEOWNERS`. This ordering makes the list safe to use. Patterns use the same glob syntax as `neverApprove` and Check Run Agent `include`/`exclude`: a pattern with no `/` matches at any depth, `**` matches across directories, and matching is case-sensitive. A pattern Macroscope cannot parse is skipped, with a warning in the check run details: check there after editing the list, since a skipped pattern means files it would have covered go back to the agent. ## Pricing Approvability is billed in [agent credits](/pricing#agent) at a **flat 30 credits (\$0.30) per run**. The price does not depend on the size of the PR or on what the run cost to produce: every verdict costs the same. **You are only charged when a verdict needs the agent.** Whenever Macroscope can reach the verdict on its own, no agent runs and the run is free: | Outcome | Charge | | - | - | | The Eligibility agent judged the PR | 30 credits | | The PR changes your [approvability configuration](#protecting-review-configuration) | Free | | The PR matches a [`neverApprove`](#protecting-review-configuration) pattern | Free | | Every file in the PR matches an [`alwaysApprove`](#alwaysapprove--skipping-the-agent-for-routine-paths) pattern | Free | | The PR changes `CODEOWNERS` and the author is not an owner | Free | | The diff is too large to analyze | Free | Most free runs show a **Skipped** verdict, but the two are not the same thing. If the agent ran and could not return a usable verdict, the result is **Skipped** and the run is still charged: what you pay for is the agent being asked, not the verdict it managed to produce. Every approvability check run states what it cost on its details page, including the runs that cost nothing: ```text theme={null} **Agent Credits:** 30 credits Approvability runs at a flat rate of 30 credits whenever the agent is asked for a verdict. ``` Approvability draws on the same balance and the same **1000 free credits per month** as every other agent feature, and is subject to your workspace's [monthly spend limit and per-PR cost limit](/pricing#how-billing-works). When either limit is reached the check run is marked **Skipped** with the reason, and nothing is charged. The \$0.30 figure is the price at the standard rate of \$0.01 per credit. Workspaces on a negotiated credit rate pay 30 credits at their own rate. ## Setup 1. Enable Approvability in **Settings โ†’ Repos**. 2. (Recommended) Add a [`CODEOWNERS` file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) to your repo. 3. (Optional) Add a `.macroscope/approvability.md` file with custom eligibility rules and front matter configuration. Macroscope cannot approve its own PRs. # Areas Source: https://docs.macroscope.com/areas Group code activity into high-level categories that match how your team thinks about work Areas let you categorize development activity into groups that align with your roadmap, like organizational units, product divisions, or cross-functional teams. Once defined, Macroscope automatically: * **Classifies all commit activity** into the appropriate Area using codebase context, linked tickets, and IdP metadata * **Generates executive summaries** for each Area, updated multiple times per day * **Enables Area-specific questions** via the agent * **Sends Area-specific weekly email digests** If your team is fewer than 20 developers, you probably don't need Areas. Macroscope treats your whole organization as a single Area by default and still generates executive summaries. ## Executive Summaries Macroscope generates executive summaries for each Area, displayed on the Home page and sent via [weekly email digests](/productivity#email-reports). Macroscope's Areas ## Example Areas * By org or business unit (e.g. Consumer Team, Revenue Team) * By product strategy group (e.g. Code Review, Platform) ## Writing Effective Descriptions Macroscope uses your Area descriptions to classify commits, so detail matters. Include: * Types of work that belong in this Area * Specific terminology your team uses * Team names associated with this Area * Related systems, services, or products Edit descriptions anytime on the Areas page. ### Example **Area Name:** Consumer Growth ```markdown theme={null} **Overview:** The Consumer Growth team drives user acquisition and activation. **Work in this Area:** - User onboarding flows and tutorials - Sign-up and authentication experiences - Marketing landing pages and conversion funnels - A/B testing frameworks for growth experiments - Referral and invite systems **Teams:** Growth Engineering, Consumer Acquisition, Onboarding Experience **Related Systems:** Consumer web app, mobile sign-up, marketing website, email service, experimentation platform, analytics infrastructure ``` # Backfilling Source: https://docs.macroscope.com/backfilling How Macroscope processes historical data from your repos When you sign up, Macroscope automatically backfills recent commits from your GitHub repos. This typically takes about 60 minutes depending on the size and history of your repos. Once complete, your Home page will show summaries of your team's recent activity. Need a longer backfill window? We can accommodate extended historical backfills for an added per-commit fee. Contact us at [support@macroscope.com](mailto:support@macroscope.com) with the timeframe you have in mind. # Code Review Source: https://docs.macroscope.com/bug-detection-and-fixes 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 * Set how Correctness runs on a repo under [**Settings โ†’ Repos โ†’ Features**](/settings#features): **Always run**, **Manual invocation only**, or **Never run**. * Change the default for newly linked repos in **Settings โ†’ Repos โ†’ Defaults**. New workspaces start with that default **off**; onboarding turns it on for the repos you pick there. * Set **always-review labels** to force a review even when automatic review is off, **skip labels** to prevent review even when automatic review is on, **mode labels** to run a review in a specific Detection Mode. Learn more about [Magic PR Labels](https://docs.macroscope.com/bug-detection-and-fixes#magic-pr-labels). Go to **Settings โ†’ Repos** in the Macroscope web app to edit code review settings per-repo or in batch. ## Detection Mode Detection Mode tunes how Macroscope correctness review balances **recall**, **precision**, and **latency**. Detection Modes can be set per developer or per repo, or overridden for a single PR or single review run. | Mode | What it does | | - | - | | **Budget** | Fast, low cost bug detection. Lower bug detection and precision compared to more premium modes. | | **Balanced**
(default) | Industry leading high bug detection. Recommended for teams who use Agents to review PR comments, where the inconvenience of occasional false positives is minimal. | | **Precise** | Similar bug detection as Balanced mode, but higher confidence findings due to additional agentic validation to reduce noise from false positives and low-value findings. Recommended for teams who prefer to spend more budget (dollars and latency) to ensure high precision findings. | | **Ultra** | Frontier bug detection for the most consequential reviews. Leverages a much higher number of parallel agents using more advanced coding models. Useful when maximizing bug detection matters more than cost. | Each Detection Mode is billed at its own per-KB rate per review, based on the byte size of the diff that Macroscope reviews. See [Pricing](/pricing) for the rate of each mode. We regularly assess the performance of these modes using an internal benchmark to give you the best understanding of the tradeoffs. ### Adjusting Detection Modes There are a few ways to configure which Detection Mode is used during a review: * **At the repository level:** Configure the Detection Mode in **Settings โ†’ Repos โ†’ Detection Mode**. This applies to every PR in the repository. The default mode is **Balanced**. * **At the developer level:** Configure your personal Detection Mode in **Settings โ†’ Personal โ†’ Code Review โ†’ Detection Mode**. This setting allows a developer to override the Detection Mode configured on the repository for all of authored PRs. * **For a single review:** Comment `@macroscope-app review using mode` on the PR. This applies only to that review and bypasses per-review and per-PR spend caps. * **For a single PR:** Add one of Macroscope's Magic PR labels (`macroscope-`) to the PR. For example, use `macroscope-ultra`, `macroscope-balanced`, `macroscope-precise`, or `macroscope-budget`. Every review of that PR will use the selected mode until the label is removed. ## PR Labels **Always-review** Force a review even when automatic review is off. Configurable in Settings โ†’ Repos. **Skip labels** Prevents review even when automatic review is on. Skip labels take precedence over always-review labels. Configurable in Settings โ†’ Repos. **Detection Mode labels** Runs a review in a specified mode. * Available modes: `macroscope-budget`, `macroscope-balanced`, `macroscope-precise`, `macroscope-ultra` * Every later review of that pull request runs in the same mode until the label is removed. * A mode label acts as an **always-review label**. It runs a review even on a pull request that a skip label would otherwise exclude, and it triggers the Check Run Agents and Approvability check alongside the correctness review. Skip authors are the one filter it never overrides. * Removing a label does not trigger a review; the next review returns to the configured mode. * If a PR carries two labels naming different modes, no reviews will run. ## Minimum Severity to Comment **Minimum Severity to Comment** sets how severe a correctness finding must be before Macroscope comments on it. Findings at or above it are posted; findings below it are withheld, as are findings with no recorded severity. Choose **Low**, **Medium**, **High**, **Critical**, or **Off**: the default is **Off**, which posts everything. See [Issue Severity Levels](#issue-severity-levels) for what each level means. Set it in **Settings โ†’ Repos**, per repo or across several at once, and under **Defaults** for newly added repos. Changing the default does not move repos that already exist. Developers can set a personal floor in **Settings โ†’ Personal**, which overrides the repo for PRs they author; **Repo Default** defers to the repo. The PR author's setting is the one that applies, not that of whoever pushed last. [CLI](/cli) reviews honor both tiers. Three things it does not do: * **Change what the review looks for.** That is [Detection Mode](#detection-mode); this only decides which findings become comments. * **Apply beyond correctness.** [Check Run Agents](/check-run-agents) and summaries are unaffected. * **Hide the withheld findings.** They are listed on the correctness check run, under the dropdown **Filtered Issues Details** with a tag \[**Below severity threshold**], and [Approvability](/approvability) still weighs them as risk signals. It is separate from Approvability's [Minimum Blocking Severity](/approvability#minimum-blocking-severity), which decides which comments block auto-approval rather than which get posted. ## Manually Triggering a Review Comment **"@macroscope-app review"** on any PR in GitHub to trigger a review, even when the repo is set to [**Manual invocation only**](/settings#features) and nothing would have started one on its own. Unless a Detection Mode is explicitly mentioned (or the author has a personal override configured), the review will use the repository's configured [Detection Mode](#detection-mode). A repo set to [**Never run**](/settings#features) does not review on request either. The mention is ignored, no check run appears, and no personal setting or label changes that. If you expected a review and got nothing, check the repo's **Correctness** mode first. A manual review is an explicit request, so it bypasses the limits that gate automatic reviews: * [**Max Automatic Runs per PR**](/settings#pull-request-settings): a PR that has already hit its run cap is still reviewed. * [**Per-review and per-PR spend caps**](/pricing#spend-controls): the \$10-per-review and \$50-per-PR caps are not applied, regardless of the values your workspace has set. Two limits are never bypassed: your workspace's [**monthly spend limit**](/pricing#spend-controls), which is an absolute ceiling whatever the trigger, and [**Max Reviewable File Size**](/settings#pull-request-settings), so oversized files stay excluded. ## 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` 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. On pull request reviews, the file is read from the PR's most recent commit, so pushing it to a PR takes effect on that PR right away; other open PRs pick it up once they include the change. Pull requests from external forks always read it from your default branch, and [Macroscope CLI](/cli#excluding-files-from-review) reviews read it from the most recent commit on the branch you're reviewing. Macroscope looks for three paths, in this order, and the first one that exists wins: even if it is empty: `.macroscope/ignore.md`, then the extensionless `.macroscope/ignore`, then the legacy `.macroscope-ignore` at the repo root. The older two are supported for backward compatibility, but `.macroscope/ignore.md` is the recommended location, since it consolidates all Macroscope configuration into the `.macroscope/` directory. ### Example ```text theme={null} # Vendor dependencies vendor/** # Generated code *.pb.go *.generated.go # Lock files *.lock # Documentation assets docs/**/*.pdf # Log directories logs/** ``` 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. ### 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. 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. ```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/** **/.nuxt/** **/.output/** **/.vercel/** **/.angular/** **/vendor/** **/_vendor/** **/third_party/** **/Pods/** **/.bundle/** # === Root-anchored ambiguous directories === build/** out/** env/** ENV/** # === Generated / build-output directories (match anywhere) === **/target/** **/dist/** **/generated/** **/intermediates/** **/generated_sources/** **/generated-sources/** **/generated-src/** **/src/main/generated/** # === Minified build output === **/*.min.js **/*.min.css **/*.bundle.js # === Yarn PnP loader files === **/.pnp.cjs **/.pnp.loader.mjs # === 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 **/*.d.ts **/*.gen.ts **/*.gen.tsx **/*.gen.js **/*.gen.jsx # === 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 ``` ```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/** ``` ### Reviewing Your Test Code By default, Macroscope ignores files it identifies as test files. Identification is by **file path**: Macroscope matches each language's test-file naming and directory conventions: a Go `_test.go` suffix, a test-like directory, and the equivalent for each other supported language. It does not read a file's contents to decide. To opt out of test detection, add a YAML front-matter block at the very top of your `.macroscope/ignore.md`: ```markdown theme={null} --- ignoreTests: false --- # Everything below the front matter is unchanged: one pattern per line vendor/** *.lock ``` * `ignoreTests` states whether to **ignore** tests: the same direction as every other line in the file. `true` means ignore them, so they are **not** reviewed. `false` means don't ignore them, so they **are** reviewed like any other code. * Omitting the key, or having no front matter at all, means tests are not reviewed. * Because identification is by path and not by content, this toggle moves whole **files** in and out of review. A test function that lives in a file whose path does not look like a test is unaffected by it: that function is already reviewed as ordinary code. * The block is treated as front matter only if it sets a recognized key. A `---` block used as a horizontal rule, or one with only unrecognized keys, is read as an ignore pattern. If a block looks like it was meant as front matter but isn't usable, the check run conclusion says so and the review continues. ### 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. * **Some file types are always excluded.** Genuinely unreviewable, non-text files such as images, fonts, archives, and compiled binaries are skipped whether or not you have an ignore file. An `include` pattern never brings them back. The patterns above are the *overridable* defaults; this always-on exclusion sits underneath them, so replacing the defaults with your own file cannot pull a binary into review or into what you're billed for. `.macroscope/ignore.md` affects code review on GitHub and in the [Macroscope CLI](/cli#excluding-files-from-review), as well as [Check Run Agents](/check-run-agents#macroscope-ignore). It does not affect commit summaries, status, or the Slack agent. ## How Does Code Review Work? 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 through 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 through Macroscope's agentic analysis engine with full cross-file codebase context. Review latency is slightly higher than for languages with native AST codewalkers, which build the reference graph in advance. ### 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). # Cancel Subscription Source: https://docs.macroscope.com/cancel-subscription Learn how to cancel your Macroscope subscription We're sorry you're thinking about cancelling Macroscope.

Feel free to write to us at [support@macroscope.com](mailto:support@macroscope.com) if you have feedback to share or [book 15 minutes to tell us about your experience.](https://cal.com/team/macroscope/feedback) ## Self-Service 1. Log in to your Macroscope account 2. Navigate to the **Billing** section 3. Click the **"Manage Plan"** button 4. You'll be redirected to our secure billing portal 5. Click on "Cancel Subscription"
Cancel Subscription Button Your access will continue until the end of your current billing period. ## Contact Support Email **[support@macroscope.com](mailto:support@macroscope.com)** to request cancellation. Uninstalling the Macroscope GitHub app will also automatically cancel your subscription at the end of the trial or billing period. # Release Notes Source: https://docs.macroscope.com/changelog **New Default Repo Settings Available** Skip PRs by Author, Skip PRs by Labels, Skip PRs by Target Branches, and Always Review PR Labels are now available under [**Settings โ†’ Repos โ†’ Defaults**](https://app.macroscope.com/settings#Repos). Values set here apply to every newly linked repository by default; existing repos keep their current settings and can override defaults individually. **New Models in Check Run Agents** Check Run Agents now support `claude-sonnet-5-5` and `gpt-6-1-sol`. [Learn more about Check Run Agent models and pricing](/model-pricing#available-models). **GPT-6.1 Sol Joins MacroscopeBench** [MacroscopeBench](https://macroscope.com/benchmark) now publishes GPT-6.1 Sol at all five of its reasoning levels, bringing the benchmark to twelve model families and 41 scored configurations. **MacroscopeBench Is Now Public** [MacroscopeBench](https://macroscope.com/benchmark), the benchmark we've used internally for the past year to tune our code review, is now public: 12,000+ validated bugs from 1,500+ open source repos across 14 languages, each replayed at the introducing commit and scored on recall, precision, signal-to-noise, cost, and latency. It's now the code review benchmark on [Fireworks AI's Specialized Intelligence Index](https://fireworks.ai/specialized-intelligence-index/#benchmark/code-review%2Fmacroscope-code-review-benchmark). [Read the blog post](https://macroscope.com/blog/macroscopebench). **New Models in Check Run Agents** Check Run Agents now support `claude-opus-5-5` (1M-token context; effort `low`, `medium`, `high`), `gpt-6-sol`, `gpt-6-luna`, and `deepseek-v4-1-flash`. [Learn more about Check Run Agent models and pricing](/model-pricing#reasoning-and-effort). **Four Fireworks-Retired Models Removed from Check Run Agents** `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5-2`, and `kimi-k2-7-code` are no longer available in Check Run Agents. A check that still names one of them is skipped ("model not available") until you update it. [Learn more about Check Run Agent models and pricing](/model-pricing). **More Reasoning Levels for Sol, Terra, and Luna Check Run Agents** Check Run Agents now support `xhigh` and `max` reasoning for `gpt-5-6-sol`, `gpt-5-6-terra`, and `gpt-5-6-luna`. [Learn more about Check Run Agent models and pricing](/model-pricing#reasoning-and-effort). **Turn a Review Feature Completely Off with Feature Switches** A new **Feature Switches** section at the top of **Settings โ†’ Repos** lets you switch Correctness, Approvability, and Check Run Agents off outright. A feature switched off does not run at all: no `@macroscope` mention, always-review label, or personal setting can start it. Set it for one repo, under **Defaults** for newly linked repos, or across several repos at once. **New** `incremental `**Input Mode for Check Run Agents** Check Run Agents have a new `incremental` input mode, and it is now the default. In this mode, when you push additional commits to a PR, the agent reviews only the files changed in that push, instead of every file changed by the PR (the same way correctness review works). **GPT-6 Astra Support in Check Run Agents** Check Run Agents now support `gpt-6-astra`, a flagship model with a large context window and reasoning at `low`, `medium`, `high`, `xhigh`, and `max`: it is the only model that accepts `max`. [Learn more about Check Run Agent models and pricing](/model-pricing). **Run Correctness Review After Your CI, or Only When It's Green** Correctness review can now wait for your CI steps before it starts, and skip entirely unless they passed. Set `waitsFor`, `requires`, `waitsForTimeout`, and `waitsForDiscoveryTimeout` in `.macroscope/correctness/correctness.md`: the governing file for the whole correctness check, alongside your other instruction files, which keep their own `include`/`exclude` patterns. [**Learn more**](https://docs.macroscope.com/custom-instructions#prerequisites). **Check Run Agents Now Know What Has Already Been Said on Your Pull Request** A [**Check Run Agent**](https://docs.macroscope.com/check-run-agents#what-an-agent-remembers) now starts every run already holding the pull request's discussion. You do not have to write instructions telling it to go and read the comments, and it spends no tool calls or tokens fetching them. [**Learn more**](https://docs.macroscope.com/check-run-agents#what-an-agent-remembers). **Expanding Detection Mode: More Control Over Every Review** We've expanded Macroscope [Detection Mode](/bug-detection-and-fixes#detection-mode), giving you more control over how each code review balances recall, precision, latency, and cost. Now, you can select the ideal performance profile for each review: * **Ultra** (\$0.20/KB): Frontier bug detection for the most consequential reviews. * **Balanced** (\$0.05/KB, default): Industry leading high bug detection. * **Precise** (\$0.06/KB): Balanced-level detection with higher-confidence findings, using extra agentic validation to reduce false positives and low-value noise. * **Budget** (\$0.025/KB): Fast, low cost bug detection. You can set Detection Mode per author, repository, PR, or review. Every mode keeps the 10KB per-review minimum. [Check out the docs](/bug-detection-and-fixes#detection-mode) and [read the blog announcement](https://macroscope.com/blog/expanding-detection-mode). **Skip the Approvability Agent for Routine Paths with `alwaysApprove`** Approvability has a new `alwaysApprove` key in the front matter of `.macroscope/approvability.md`. List glob patterns for paths such as lockfiles, vendored dependencies, and generated code. A PR whose files **all** match is approved on eligibility without running the agent, so the run is free. It is all-or-nothing: one file outside the list and the PR goes to the agent as usual. It skips the agent, not the rest of approval. Correctness findings, the repo's approval setting, and every prerequisite wait still apply. It never overrides `neverApprove` or the always-on protection on your approvability file. [Learn more](/approvability#alwaysapprove--skipping-the-agent-for-routine-paths). **GLM-5.3 support in Check Run Agents** Check Run Agents now support `glm-5-3`, a large-context model with configurable reasoning levels. [Learn more about Check Run Agent models and pricing](/model-pricing). **Give a Late-Publishing Check Longer to Appear with `waitsForDiscoveryTimeout`** [Check Run Agents](/check-run-agents) and [Approvability](/approvability) now support `waitsForDiscoveryTimeout`, which gives conditionally published prerequisites, such as checks behind earlier jobs or queued workflows, longer to appear before they are treated as absent. It supports 1-60 minutes; named prerequisites stop waiting once found, while `waitsFor: ["*"]` waits the full floor on every run and shows a warning. **Skip PRs by Author Now Covers Every Trigger** Accounts listed under **Settings โ†’ Repos โ†’ Pull Requests โ†’ Skip PRs by Author** now have their PRs skipped across [correctness review](/bug-detection-and-fixes), [Check Run Agents](/check-run-agents), and [Approvability](/approvability). **Config Changes Now Take Effect in Your PR, No Merge Required** Files in `.macroscope/` are now read from the most recent commit on the pull request rather than from your default branch, so a config change takes effect in the PR that makes it. This covers [Check Run Agents](/check-run-agents) (`.macroscope/check-run-agents/`), [ignore rules](/bug-detection-and-fixes#macroscope-ignore) (`.macroscope/ignore.md`), and [correctness review custom instructions](/custom-instructions) (`.macroscope/correctness/`), along with any file they import with `@path`. **DeepSeek V4 Pro Support in Check Run Agents** Check Run Agents now support `deepseek-v4-pro` (DeepSeek V4 Pro), a large-context model with binary reasoning. [Learn more about Check Run Agent models and pricing](/model-pricing). **Gate a Check Run Agent on Its Prerequisites with `requires`** Check Run Agents have a new `requires` key option in front matter. [`waitsFor`](/check-run-agents#prerequisite-steps) only controls ordering, and any conclusion satisfies it. `requires` also gates on the outcome: the agent waits the same way, then runs only if every prerequisite passed. [Learn more](/check-run-agents#requires). **New Correctness Review Setting: Minimum Severity to Comment** A new control in **Settings โ†’ Repos** sets how severe a correctness finding must be before Macroscope comments on it: **Low**, **Medium**, **High**, **Critical**, or **Off**. The default is **Off**, which posts everything. Available per repo, across several at once, under **Defaults**, and as a personal floor in **Settings โ†’ Personal**. **New Models in Check Run Agents** Check Run Agents now support: `grok-4-6` (xAI Grok 4.6) and `qwen-3-8-max` (Qwen3.8-Max), both with reasoning effort up to `xhigh`. [Learn more about Check Run Agent models and pricing](/model-pricing). **Ignore Files in Macroscope CLI Reviews** Macroscope CLI reviews now honor your repository's [`.macroscope/ignore.md`](/bug-detection-and-fixes#macroscope-ignore) file. Ignored files are skipped from review, and Macroscope's built-in defaults (vendored dependencies, generated code, binaries, and test files) apply when a repo has no ignore file. [Learn more](/cli#excluding-files-from-review). **Protect Paths from Auto-Approval with `neverApprove`** Approvability has a new `neverApprove` key in the front matter of `.macroscope/approvability.md`. List glob patterns there and any PR touching a matching path will never get approval from approvability check. [Learn more](/approvability#neverapprove-additional-protected-paths). **Daily Chart View for Agent Credit Usage** The Agent Usage Detail section in the [Billing Dashboard](https://app.macroscope.com/settings/billing) has a new **Daily chart** view alongside the pie chart. It plots agent credit usage per day, grouped by type, repo, or Check Run Agent, and you can select any slice to see that series on its own with its run count, totals, and per-run cost range. **New Correctness Review Settings: Limit by Run Count and File Size** Two new per-repo controls in **Settings โ†’ Repos** let you bound how many correctness review invocations a single PR can trigger and how large a file Macroscope will review: * **Max Automatic Reviews** caps how many times correctness review runs automatically on one PR: once the cap is reached the check concludes as `skipped`, titled "Maximum runs reached", with a summary referencing your limit. Manually triggered reviews, check re-runs, and moving a PR from draft to ready are exempt. * **Max File Size** skips files larger than the configured KB limit when reviewing for correctness; useful for repos with large generated or vendored files. Larger files are listed on the check run with the reason "File too large (exceeds configured limit)." Glob-based excludes in `.macroscope/ignore.md` still work; this adds a size-based option. **Including Test Files in Correctness Review** Macroscope correctness review ignores test files by default. You can now opt out, per repo, by adding an `ignoreTests: false` front-matter block to the top of your `.macroscope/ignore.md`, and Macroscope will review the repo's test files as it would any other code. **Spend Limits for Check Run Agents** You can set `maxBudgetPerRun` in a Check Run Agent's front matter to cap what a single run of that agent may spend (in US dollars). The agent checks its accumulated cost after each turn and stops once it reaches the cap, concluding the check as `neutral` with a "Budget reached" message. **Referencing Other Files in Check Run Agent Instructions** Check Run Agent instructions can now embed other files from your repository with `@path/to/file.md`, so you can pull existing docs and context into an agent's instructions. **New Models in Check Run Agents** Check Run Agents now support Kimi K3. K3 delivers performance rivaling top frontier closed models, at a fraction of the price of Fable 5 or GPT-5.6 Sol. Check Run Agents also now support Claude Opus 5. [Learn more about Check Run Agent models and pricing](/model-pricing). **Lower Check Run Agent Model Pricing for GPT-5.6 Terra and Luna** We've reduced Check Run Agent pricing for two GPT-5.6 models: `gpt-5-6-luna` is now \$0.20 per 1M input tokens and \$1.20 per 1M output tokens, and `gpt-5-6-terra` is now \$2.00 and \$12.00. [See the full pricing table](/model-pricing#pricing). **Screen Recordings in Slack Commit Summaries** Screen recordings attached to a PR in its description or a comment now appear in that commit's Slack summary thread, alongside the images Macroscope already posts. Your team can review visual PR context without leaving Slack. **Faster, More Accurate Code Review** We've shipped a major update to Code Review that makes reviews faster and better at finding bugs: up to 20% lower latency on average and up to 20% better recall, depending on your [Detection Mode](/bug-detection-and-fixes#detection-mode) setting. **Bug Grouping in Review Comments** We've improved how findings are surfaced in PR comments: * Critical and High severity bugs are now separated from related lower-severity findings. * Related findings are grouped more accurately. **Macroscope CLI Interactive Code Review** The [Macroscope CLI](/cli) now has a full-screen interactive review experience. Run `macroscope` with no arguments for a guided setup wizard. You can also run Macroscope from inside Claude Code, Codex, Cursor, and OpenCode using the agent plugin installed alongside the CLI. [Read more on the blog](https://macroscope.com/blog/introducing-macroscope-cli). **Code Review Improvements** We've made several improvements to our code review pipeline, particularly for Go, Rust, and Python. **Run Limits for Check Run Agents** You can now set `maxRuns` in a Check Run Agent's front matter to cap how many times it runs on a single pull request. Once the cap is reached, later pushes conclude the check as skipped with a "Maximum runs reached" message instead of running the agent: commenting `@macroscope review` still runs it past the cap. [Learn more](/check-run-agents#run-limits). **Adjust Billing Chart Date Range** You can now drag across the usage chart in [Billing](https://app.macroscope.com/settings/billing) to select a date range within the billing period. The usage tables and totals update to reflect just the selected range. **Code Review Improvements for Swift and Rust** We've made improvements to our code review pipeline for Swift and Rust, helping Macroscope catch more idiomatic issues in those languages. **Open-Source Models in Check Run Agents** Check Run Agents now support `kimi-k2-7-code`, `glm-5-2`, `minimax-m3`, and `qwen-3-7-plus`. [Learn more about Check Run Agent models and pricing](/model-pricing). **GPT-5.6 Models in Check Run Agents** Check Run Agents now support GPT-5.6 Sol, Terra, and Luna. **Run Filters for Check Run Agents** You can now configure Check Run Agents to run only on specific PRs via `runFilters` in the front matter. Use the `labels`, `authors`, and `targets` fields to scope CRA to PRs that carry a specific label, come from a specific author, or target a specific branch. **PR Metadata Input Mode for Check Run Agents** Check Run Agents now support `input: pr_metadata`, a new mode for reviewing a PR's title, author, description, labels, and commit messages instead of the code diff. This is useful for checks that enforce PR conventions, ticket requirements, or metadata standards. **Required Status Checks for Check Run Agents** You can now set `requiredStatusCheck: true` on a Check Run Agent so it always reports a conclusion, even when its `include`, `exclude`, or applicability filters skip a PR. Skipped runs report as `skipped`, which GitHub branch protection treats as passing, so the agent can be used as a required status check without blocking unrelated PRs. **Improved Cache Hits for Check Run Agents** We've improved cache hit rates for Check Run Agents to help you save on costs. Unchanged runs are now more likely to return cached results (e.g. after a rebase) so you don't pay to recompute the same review. **Check Run Agent Filters Override Soft Exclusions** Check Run Agent `include` and `exclude` patterns now override Macroscope's default soft exclusion patterns, so your CRA runs on exactly the files you've configured. The same override applies to [custom correctness instruction](/custom-instructions) `include` and `exclude` patterns. **Check Run Agent Usage Breakdown Table** Settings โ†’ Billing now has a Check Run Agents section that breaks down your workspace's spend and usage over a billing period. The top row summarizes active agents, total runs, total credits consumed, and total cost. Below it, a table breaks that down per agent: repo, total runs, credits consumed, cost, per-run avg/min/max cost, and the last PR each agent ran on. Check Run Agent usage table in Billing showing cost and frequency details **New Models in Check Run Agents** Check Run Agents now support two additional models: `fable-5` and `claude-sonnet-5`. [Learn more](/model-pricing). **New Code Review Pipeline** We've released a new version of Code Review that finds substantially more bugs. In our benchmarks it surfaces: * 71% more critical issues * 27% more high-severity issues * 50% more medium-severity issues * 31% more valid issues overall This is now the default pipeline ("Prefer Coverage"). If you prefer the previous behavior, you can switch to "Prefer Precision" using the new Detection Mode setting below. **Detection Mode** Detection Mode is a new setting that controls how Macroscope balances finding more bugs against minimizing noise: * **Prefer Coverage** (default): maximizes detection, with higher comment volume and more false positives. Built for teams using coding agents to validate PR comments. * **Prefer Precision**: prioritizes high-confidence findings: fewer bugs caught, but fewer false positives. Mirrors the experience of the past few months. You can set Detection Mode from **Settings** at the [repository level](https://app.macroscope.com/settings#Repos) or at the [individual developer level](https://app.macroscope.com/settings#Personal). Betterres **Templates for Check Run Agents** Teams can create [Check Run Agents](/check-run-agents) from pre-built templates. Browse templates on the [Code Review page](https://app.macroscope.com/code-review) and select a template to customize it or use as-is. Templates cover common review patterns including ticket requirements, language idioms, architecture standards, and security review. **Organize Check Run Agents into Subfolders** [Check Run Agents](/check-run-agents) now support nested directories inside `.macroscope/check-run-agents/`, so teams can organize their configuration files into subfolders. **Manual Review Links to Check Runs** When you manually trigger a review with `@macroscope review`, Macroscope now posts a link from the PR thread to the generated check run. **Improved Python Code Understanding** We've improved our Python codewalker to follow imports, type hints, class relationships, and nearby dependencies more accurately during review. **Personal MCP Connections** You can now connect your own MCP servers as personal connections from **Settings** โ†’ **Personal**. These connections are separate from the MCP connections admins can set up for their workspace. Macroscope can use those personal connections on your behalf when answering your questions in Slack. [Learn more about MCP Connectors](/integrations#mcp-connectors). **Skip Automatic Reviews by Author** Workspace admins can now skip automatic Code Review for specific GitHub authors under **Settings โ†’ Repos โ†’ Pull Requests** โ†’ **Skip PRs by Author**. **Default View for the Commits Feed** You can now save your preferred filters as the default view for your commits feed. **Slack Agent Improvements** We've made several improvements to how [Macroscope's agent](/agent) answers questions in Slack, including: * **Live "Thinking..." status.** When you @ mention Macroscope, a native status indicator appears on the thread while it works, then clears when the answer posts. * **Native tables.** Tabular answers render as tables instead of plain text. * **Clickable links.** Links render as clickable labels instead of bare URLs. **Landed vs. Pushed Coding Time** Productivity stats now separate **pushed** coding time (everything authored and pushed to git) from **landed** coding time (the portion that merged to your default branch), showing how much code was written and how much shipped. Available with [Status](/productivity) enabled, with rollups at the organization, team, engineer, and agent level. [Read the blog](https://macroscope.com/blog/beyond-tokenmaxxing). Image (24) **Async Agent API Polling** Webhook-triggered agent jobs now return a `jobToken` and `pollUrl` so integrations can trigger long-running agent jobs and poll for completion, rather than waiting for a synchronous response. [Learn more about the agent API](/api). **Check Run Agent Tool-Call Visibility** A Check Run Agent's GitHub check run now includes a "Tool Calls" section in the check details, showing what the agent did during its review. Available for workspaces using [Check Run Agents](/check-run-agents). **New Code Review Pipeline** A new code review pipeline is now available, improving overall bug detection by catching 40% more critical issues and 25% more medium severity issues. The tradeoff is slightly lower precision and higher latency, which we've found is a worthwhile tradeoff for teams heavily using coding agents in their PR review process. Manage Detection Mode from **Settings** under workspace defaults or repository pull request review settings. **MCP Connector Access Controls** MCP connectors now support per-user access controls. When creating or editing an MCP connection, use the **Access** tab to define an allow list of users who can use it. [Learn more about MCP Connectors](/integrations#mcp-connectors). MCP connector access controls **Code Review Feedback Analysis** The Code Review activity log now includes a **Feedback Source** column and filter, so that you can see how feedback was captured: * **Explicit** feedback covers emoji reactions (i.e. ๐Ÿ‘ or ๐Ÿ‘Ž) on review comments * **Inferred** feedback reflects sentiment Macroscope classifies from replies when a PR is closed. **Macro Author Filtering** Event-triggered Macros now support filtering by author, letting you include or exclude specific authors when defining trigger conditions. [Learn more about Macros](/macros). **Check Run Agent Prerequisite Steps** Custom Review Agents now support prerequisite CI step gating with the `waitsFor` configuration option. Specify CI checks that must complete before a review agent runs. This is useful for sequencing reviews after builds, tests, or other checks. Configure per-agent prerequisites with optional custom timeouts, or use `"*"` to wait for all other checks. See [Check Run Agents](/check-run-agents#prerequisite-steps) for details. **Claude Opus 4.8 for Check Run Agents** Claude Opus 4.8 (`claude-opus-4-8`) is now available as a model option for Check Run Agents. Set `model: claude-opus-4-8` in your agent's front matter to use the latest Opus generation. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increased recall for TypeScript, Rust, Swift, Kotlin, JavaScript, Python, Java, and Go. **Exclude GitHub Authors from Commit Processing** Admins can exclude specific GitHub authors from commit summarization and productivity metrics (i.e. Status features). Manage the list under **Settings** โ†’ **Workspace โ†’ Excluded Commit Authors**. **Check Run Cost Visibility** [Check Run Agents](/check-run-agents) display their billed total directly in the GitHub Checks tab, so you can see the cost of each run. **Slack Connection Refresh** Admins can reconnect their Slack workspace from **Settings โ†’ Connections** to reauthorize new OAuth scopes. Use this whenever we add new bot capabilities and you want your existing connection to pick them up without uninstalling. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increased precision and recall for Go. **Macroscope CLI** You can now run Macroscope code review locally from your terminal, against your branch changes before you push. [Learn more about the CLI](/cli). **Check Run Agents: now GA!** Check Run Agents are fully customizable AI agents that execute as GitHub Check Runs on your pull requests. For each Check Run Agent, you can define exactly what the agent checks, which files it should/shouldn't review, which tools it can use, what actions it should take, and how it formats its output: all from a markdown file in your `.macroscope/` directory. [Learn more in our docs](/check-run-agents) and [check out our video about it](https://x.com/kayvz/status/2050259933409792386). **Delegated Admins** Workspace admins can now delegate admin permissions to other members from **Settings โ†’ Macroscope Access โ†’ Members**. Delegated admins can manage Macroscope settings on behalf of the workspace. GitHub roles and permissions are unaffected. **One-Time Credit Purchase** Admins on usage based billing can make one-time credit purchases from **Settings โ†’ Billing**. **Check Run Agents** Check Run Agents are fully customizable AI agents that execute as GitHub Check Runs on every pull request. They have full access to your codebase, git history, and connected integrations. You can define exactly what an agent checks, which files it reviews, which tools it can use, what actions it can take, and how it formats its output: all from a markdown file in your `.macroscope/` directory. [Learn more in our docs](/check-run-agents). **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increased recall for Kotlin and Swift. **Event-Driven Macros** Macros can now trigger on new commits and new pull requests, in addition to recurring schedules. Configure repo and branch filters to control which events run your Macro. Results can be delivered to Slack or forwarded to a webhook URL. **New Integrations** We've added several new integrations, including Amplitude, Sentry, and GCP Cloud Logging. You can configure your integrations in **Settings โ†’ Connections**. [Learn more about supported integrations in our docs](/integrations). **Image Generation** The Macroscope Agent can now generate images on demand, including architecture diagrams, flowcharts, and visual explanations. **Code Review Filter Persistence** Filters in the Code Review activity log now persist in the URL. Copy the link to share a filtered view with your team. **New Code Review Settings** "Review Draft PRs" and "Automatically merge Macroscope's PRs" can now be configured at the workspace and repo level. Admins can set organization-wide defaults and manage settings in batch across repos; contributors can override in their account settings. **MCP Connector Support** Macroscope's Agent can now connect to any [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) compatible server, so you can give it access to tools like Datadog, PagerDuty, or your own internal APIs. Macroscope auto-discovers available tools and supports OAuth 2.1 and header-based auth. [Learn more](/integrations#mcp-connectors). **Webhooks** You can now trigger Macroscope's Agent programmatically via webhooks. Send a query over HTTP and specify where to deliver the results: a Slack channel or an external URL. Note: using Webhooks requires Status to be enabled. [Learn more](/api). **Cross-Repo PR Reviews** Macroscope can now review pull requests where the head branch and base branch are in different repositories. Enable per repo with the new **Review Cross-Repo PRs** toggle in **Settings โ†’ Repos**. **Ask Macroscope Anything: GitHub API + Docs Search** AMA can now query the GitHub REST API for live data on PRs, issues, check runs, and deployments. Ask "what checks failed on PR #42?" or "show me the latest deployment" and get real-time answers. The agent can also search [Macroscope's help docs](https://docs.macroscope.com) to answer any product questions. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increased recall for Rust and TypeScript. **Next Scheduled Run for Macros** Macros now show when they'll next run. The next run time appears in the macro header and as a tooltip on the cadence pill, so you always know when to expect your next scheduled report. Next scheduled run for macros **Approvability: Now Generally Available** Approvability has graduated from beta and is available to all workspaces. Approvability lets Macroscope automatically approve low-risk PRs from trusted authors when they pass code review with zero issues: freeing engineers from rubber-stamping routine changes. Enable it in **Settings** under the **Code Review** section. [Learn more about Approvability](/approvability). **Slack Group DMs** You can now create a Slack group DM that includes Macroscope alongside your teammates, so you can collaborate with Macroscope outside of a channel. **Ask Macroscope to Add PR Reviewers** You can ask Macroscope to assign a reviewer to any pull request directly from Slack: just tell it who to add and to which PR. **Per-File Exclusion Reasons in Check Runs** Check run details now surface per-file exclusion reasons, showing why specific files were skipped during review. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increases in precision for Elixir, Starlark, and PHP, as well as increased recall for Python, Rust, Java, JavaScript, Swift, Kotlin, and PHP. **Biweekly Macro Cadence** Macros now support a Biweekly schedule (i.e. every other week) in addition to Daily and Weekly. biweekly **PR Description Formatting** When a PR already contains user-written text, Macroscope's review summary renders as a blockquoted note rather than replacing the content. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increases in precision for Go as well as increased recall for TypeScript and Elixir. **Webhooks** You can now trigger Macroscope queries from external services like Zapier, n8n, or your own APIs. Pass in a query and a destination (either a Slack channel ID or forwarding URL), and Macroscope will post the result to the provided destination. You can create webhooks and see detailed instructions in Settings โ†’ Connections โ†’ Webhooks. **PostHog Integration** Macroscope now connects to PostHog as a data source. With this connection, you can query your PostHog event data, run HogQL queries, and explore feature flags directly through Macroscope. Connect PostHog in Settings โ†’ Connections โ†’ PostHog. **Always-Review PR Labels** You can now add "always-review" labels to have Macroscope review any PR, even on repositories where automatic reviews are turned off. This also overrides skip-review labels. Go to Settings โ†’ Code Review โ†’ Always Review PR Labels to add a label (e.g., `macroscope-review`), then apply it to any PR on GitHub to trigger a review. **Slack Attachment Support** Macroscope now reads attachments from all messages in a Slack thread, including images, text documents, and code snippets. For example, you can tag @Macroscope in a thread with a screenshot of a bug and it can parse the attachment and open a PR with a fix. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increased recall for Go, Java, Rust, and TypeScript. **Filter by PR Status in Code Review Dashboard** In the Code Review Dashboard, you can now filter code review issues by the status of the pull request (draft, open, merged, or closed), enabling you to see a more focused list of issues and analyze more specific code review stats. Filter by PR Status **Code Review Improvements** We've made improvements to our code review pipeline, resulting in increases in precision for Ruby, Rust, and Starlark, as well as increased recall for Go, Java, and Starlark, Swift. **V3 Code Review** We released a new version of Macroscope Code Review. Based on our benchmark, v3 leaves 22% fewer comments overall, with 64% fewer nitpicks in Python and 80% fewer in TypeScript, and demonstrates a step-change improvement in precision from 75% to 98%. [Learn more on our v3 Code Review blog](https://macroscope.com/blog/code-review-v3). **Approvability \[beta]** We're launching Approvability, which enables Macroscope to automatically approve PRs when low-risk changes from trusted authors meet safety criteria. When a PR is opened or updated, Macroscope runs two automated checks: 1. **Eligibility**: Do the changes meet your team's criteria for auto-approval? This includes evaluating code ownership as a contextual signal: factoring in `CODEOWNERS`, blame history, and author role. 2. **Correctness**: Does the PR pass Macroscope code review with zero issues? If both hurdles are cleared, Macroscope will approve the PR automatically. [Learn more about Approvability in our help docs](/approvability). Reach out to [support@macroscope.com](mailto:support@macroscope.com) if you would like to use this feature. **Impact Severity on Code Review Comments** Review comments now display impact severity (Critical / High / Medium / Low) so you can quickly triage which issues need immediate attention. high severity bug **Updates to Code Review Dashboard** We've released several updates to the Code Review dashboard, including: * Filter comments by author, date, feedback reaction (or ), and addressed status (whether a review comment has been resolved). * View high-level stats, including total PRs reviewed, average issues per PR, total comments left, % comments addressed, fix-it-for-me tasks started, and time saved resulting from fix-it-for-me. * "Useful Comments Over Time" chart shows the % of review comments that were addressed by PR close or that received positive feedback (from a reaction or a reply). * Download your code review history as a CSV. new dash **Universal File Support** Previously, Macroscope code review only reviewed files in languages with native AST-parsing. Now, every file in your PR gets reviewed. **Linked Issues in Slack Commit Summaries** Commit summary notifications in Slack now display linked Linear and Jira tickets when available. You'll see a "Linked Issues" section with ticket IDs linked to their URLs, making it easier to trace commits back to the work they address. **PR Closed Notifications** Macroscope now sends PR closed notifications even when a PR is closed without merging. **Code Review Improvements** We've made improvements to our code review pipeline, resulting in measurable increases in precision for Java, Kotlin, and Swift, as well as increased recall for Python. **Custom AMA Instructions** You can customize how Macroscope responds to questions about your codebase. Go to **Workspace Settings โ†’ Custom AMA Instructions** to add your instructions, such as preferred response tone, domain-specific context, or output format preferences. You can also define person-specific instructions, like: "customer success teammates should get less technical responses." **Code Review Improvements** We've made several improvements to our code review pipeline, resulting in measurable increases in precision for TypeScript, Python, Go, Java, Ruby, and Kotlin, as well as increased recall for Java and Elixir. **Pre-Configured Macro Templates** You can now create Macros from pre-built templates. Browse templates on the Macros page and click any template to create a new Macro that you can customize or use as-is. Templates **Reassign Project Areas from Breakdown Chart** When hovering over a Project in the Project Focus Breakdown chart, you can click the "Move Area" button to reassign the Project to a different Area. areas **Skip Labels Now Work for PR Summaries** Labels configured to skip code review now also skip PR summary posting. Add your configured skip label to any PR to disable both features at once. **Improvements to Code Review** Better handling of language-specific patterns and reduced noise from non-actionable issues. **Comment Resolution Tracking** Code review comments now link to the commit where they were resolved and indicate if feedback has been addressed. Macroscope automatically evaluates and updates comments when new code is pushed to a PR. Comment Resolution Tracking **Per-PR Auto-Merge Control** You can override your default auto-merge settings when asking Macroscope to fix an issue by adding instructions like "Fix it for me and auto-merge" or "Fix it but don't auto-merge." **Timezone-Aware Date Selection** Date presets (e.g. "Yesterday", "This Month") in the Macroscope web app now automatically align with your local timezone. **Neutral Check Run Status** When Macroscope reviews your code and posts comments with issues that need addressing, check runs now complete with `NEUTRAL` status instead of `SUCCESS`, so it's clear when there's pending feedback to address. **Explanations for Blocked Auto-Merges** When you use Macroscope's coding agent to automatically fix issues on a feature branch, the agent creates a pull request with the fixes and attempts to auto-merge it back to your base branch (if you have auto-merge enabled). If auto-merge is blocked, Macroscope now posts a comment explaining the specific GitHub requirement preventing the merge (e.g. missing reviews, merge conflicts, failed checks). **Flexible @Mention Support in GitHub** Macroscope now responds to both `@macroscope` and `@macroscope-app`. **Fix It For Me** Macroscope can directly fix issues found during code review. Just reply to a GitHub review comment and ask Macroscope to fix it. Macroscope will create a branch, push commits, open a PR, and merge it back into your working branch. [See help docs for more details](/fix-it-for-me). Fix It For Me **Updated Check Run Labels** GitHub Check Runs now display as "Macroscope - Correctness Check" and "Macroscope - Custom Rules Check" (previously "Review for correctness" and "Review custom rules"). **Pull Request Closure Messages** When someone manually closes a PR, Macroscope now posts a comment identifying who closed it and whether it was merged. **Personal Code Review Settings** Individuals can now customize their individual preferences for PR Summaries and Code Review that override their workspace defaults. Select "Repo Default" to inherit preferences from the repository level. Personal Code Review Settings **Timezone Support in AMA** When asking Macroscope questions, the query agent now automatically uses your timezone to interpret dates and times. This improves results for questions about "yesterday," "this week," or specific dates. **v2 Code Review by Opus 4.5** We released a new version of Code Review powered exclusively by Claude Opus 4.5. Compared to our previous code review pipeline, the new pipeline has 40% higher recall and generates 10% fewer false positives. [Learn more in our blog post](https://blog.macroscope.com/blog/opus-4.5-code-review). **Invoking Macroscope in PR Discussions** Macroscope can now respond to comments in the main PR discussion thread as well as inline code comments. When you mention @macroscope-app in a comment, Macroscope will react with ๐Ÿ‘€ to acknowledge the question and then respond in the main discussion thread. **Ignoring Bot Comments in GitHub** @macroscope-app no longer responds to comments authored by other bots in GitHub. **Improved Executive Summaries** We've simplified summaries on the home page. Summaries are organized by [Areas](/areas) and have collapsible sections, so you can easily see a high level view of what's changed in your codebase this sprint. Executive Summaries **@mentions in Slack** Users can configure whether or not Macroscope can @mention them directly in Slack. When enabled, Macroscope will @mention them when relevant, such as when they are assigned as a reviewer on a PR. When disabled, Macroscope will reference the user's Slack name instead of @mentioning them directly. This setting is configurable per user in Settings โ†’ Account. **Language Support for Elixir and Starlark** Macroscope code review now supports Elixir (.ex, .exs files) and Starlark (.star, Tiltfile, BUILD files). **Login Improvements for Enterprise/SAML Customers** For customers using SAML login alongside GitHub Enterprise Managed Users, Macroscope's login flow should be smoother and smarter about automatically detecting expired tokens. **Streamlined Macros Scheduling** Scheduling regular reports with Macros is now even easier. After you set your daily/weekly cadence and write your prompt, all you need to do is copy/paste the generated Slack command into any Slack channel(s) you want to subscribe to the Macro. [Learn more about Macros in our help docs](/macros). Macros GIF **Manually Trigger Code Review in GitHub** You can now manually trigger a code review on a PR in GitHub by commenting `@macroscope-app review`, regardless of whether Macroscope code review is enabled for the repository. Macroscope will acknowledge your comment with a thumbs-up reaction and run a code review on the PR. This is useful when you want Macroscope to run another review after making changes, or when automatic reviews are disabled for a repo. **Visualize Your Code in Slack** Want to see how tables are connected in a database? Map a diagram of a workflow's lifecycle? You can ask @Macroscope to generate ASCII diagrams of anything related to your code. ASCII Art **Updates to Query Agent (a.k.a. Ask Macroscope Anything)** * **Smarter Guidance** - Query Agent can provide guidance when you explicitly request help, even for tasks outside its direct capabilities. * **Adaptive Tone** - Macroscope adapts to your communication style. If you use humor or casual language, Query Agent will respond in kind while maintaining accurate and factual responses. * **Content for External Stakeholders** - When you need content for external audiences, Query Agent can format responses and links appropriately for sharing outside your organization. Just request externally-facing content when preparing materials. * **More Flexibility** - Under the hood, Query Agent's underlying prompt system supports broader interaction patterns, allowing it to handle a wider variety of interactions with users. **Merge Notifications in Slack** Macroscope now notifies you in Slack in real-time when commits are merged to release branches. When a merge occurs, Macroscope reacts to the original PR summary message with a ๐Ÿš€ emoji and posts a reply in the message thread. This works for all merge types, including squash, rebase, and fast-forward merges. Note: this requires subscribing to commit notifications in a Slack channel with the `/macroscope subscribe-commits` command. Merge Notifications **Skip Code Review with GitHub Labels** You can now tell Macroscope to skip code review on PRs tagged with specific [GitHub labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels). In Settings โ†’ Repos โ†’ Skip PR Labels, you can specify which GitHub labels that you want Macroscope to ignore during code review (e.g. "docs-only"). When you apply any of these designated labels to a PR, Macroscope will automatically skip the code review process for that PR. Skip Code Review **New Rendering Modes for Suggested Fixes in Review Comments** Macroscope now automatically selects the best format for displaying suggested code fixes in review comments. Depending on the context, Macroscope chooses between three options: * GitHub's native inline suggestion block (i.e. "accept diff") * Unified diff blocks (i.e. static code diff) * No diff (i.e. text-only explanations) **Code Review Latency** We significantly improved code review latency in the case where you push multiple commits to a PR in quick succession. **Batch Repository Settings** You can now configure settings for multiple repositories at once. The new interface, found in Settings โ†’ Repos, allows you to search repos, select multiple repos, and apply settings across multiple repos simultaneously. Multiple Repos Settings **AMA for Repos with Summaries Disabled** Macroscope's Slackbot can answer questions about any repository you've linked to Macroscope, even if PR summaries are disabled. Based on customer feedback, we changed the PR summary setting so that it only controls whether generated summaries are posted to GitHub. This allows your Slack users to @ mention Macroscope with questions about PRs in repos where the PR summary posting feature is disabled. **Shorter Code Review Comments** We've adjusted Macroscope code review comments to be more succinct. **Path-Based Filters for Slack Subscriptions** With path-based filters, you can limit code activity subscriptions to specific parts of a repository. Any activity that modifies files matching the specified path filter(s) will trigger a Slack notification in the subscribed Slack channel. To create a code activity subscription that is filtered by file path, add the`--paths=` flag to the end of a `/macroscope` subscription command, and specify which file path(s) you want to filter by. [Learn more about path-based filters in our help docs](/slack-subscriptions#path-based-filters). **Filtered Issues in Code Review** If you've been curious which comments Macroscope considered leaving on your pull request but didn't, you can now see them. By default, these lower-signal comments are hidden to keep reviews focused. However, you can expand the "Filtered Issues" section at the bottom of the PR description to see which comments were excluded, by file, and expand each file to view the specific comment(s) identified. Filtered Comment **Custom Rules \[deprecated for [Check Run Agents](/check-run-agents)]** We're introducing the ability for Macroscope to run an independent code review focused on your team's best practices, based on custom rules you define. In `macroscope.md` files throughout your codebase, you can define your team's best practices (i.e. anything that's idiomatic of how you want code to be written). During reviews, Macroscope will run a separate CheckRun that flags violations and leaves inline comments that reference the relevant rule. Code Review Rules **AI Web Research in Code Review** Code review now has web research capabilities, meaning that Macroscope can search the web for external knowledge sources. When reviewing your code, Macroscope uses [Parallel](https://www.parallel.ai/)'s search API to find the latest documentation, so that code reviews take into account every library and package you use. Web Search with Parallel **Ticket Creation in Slack** You can now ask the Macroscope Slackbot to create Jira and Linear tickets. Ask @Macroscope to create a ticket and Macroscope will use the context provided to generate a ticket on your behalf. To enable this, you will need to re-authorize your Jira / Linear integrations in Settings โ†’ Connections. [Learn more about our Jira / Linear integrations here](/issue-management-integrations). Make a Jira Ticket **Displaying Teammate Names** The web app now shows contributors' GitHub display names (instead of their GitHub usernames) across commits, contributors, and team views, making it easier to identify team members. **Contributor Metrics in AMA** Macroscope AMA now has access to Contributor Productivity Metrics (e.g. # commits, # PR, coding time), so you can ask questions like "@Macroscope how many PRs were opened in the last 2 days?". Macroscope's agent can retrieve any metrics that are visible on the Macroscope website, across any time range. **Linear Integration v2** Macroscope is now using Linear's new "Agents" framework. Soon, Macroscope will be able to take actions on behalf of users in Linear. Existing customers will need to unlink and re-link their Linear application in their Macroscope settings in order to authorize fresh permissions. **Jira Integration v2** We are building a deeper Jira integration in Macroscope AMA. Soon, Macroscope will be able to create Jira issues and answer questions about your Jira projects and issues. **Squash Merge Summaries** The Commits page now displays summaries for squash merges. Users can hover over a branch's release details to view the summary, which shows the number of commits squashed and the date range covered. Squash Merge **Support for GitHub PR Templates** You can now add Macroscope summaries directly into a PR template by placing special markers where you want the summary to appear. [Learn more in our help center.](https://docs.macroscope.com/pull-request-descriptions#inserting-macroscope-summaries-into-your-pr-templates) PR Template **Exportable Contributor Stats across Custom Time Ranges** The Contributors page shows engineering productivity metrics grouped by individual contributors or by GitHub Team. This page now includes total opened PRs, in addition to Commits and Coding Time. Metrics can be filtered across any custom date range and exported as a CSV. Contributors Date Range **Smarter, Faster "PR Assistant"** The PR bot now retains the code research gathered during review. Follow-up questions and implementation discussions in review comments receive better-informed responses with lower latency. **Better Code Review** We have made several improvements to code review that increase bug detection rate while reducing false positives. **Slack Messages** We have improved the formatting of code activity updates in Slack so that messages are easier to scan and understand. **We're Live!** As of September 17, we're officially out of private beta. **Coding Time Estimates** Improved our Coding Time estimate algorithm to provide more accurate estimations based on the complexity of code changes. **Code Review Improvements** Optimized our code review pipeline to reduce the likelihood of false positives. In our testing, this results in \~30% lower comment volume without a meaningful impact to overall bug detection rate. **Deployment Tracking for Commits**
Deployment tracking with rocket icon
Deployment tracking with rocket icon
Deployment tracking with rocket icon
Commits now display a "Released to" indicator with a rocket icon and linked branch tag when released to a specific branch, making it easier to track deployment status. **Slackbot Resilience** Improved reliability and resilience of responses from Macroscope's Slackbot. Sometimes, when users asked code research questions, the Slackbot would struggle to respond when the response included emojis due to Slack API compatibility issues. Now, the Slackbot responds without failure. **Mobile Viewing** Better viewing on tablets and larger mobile devices, plus improved chart displays. **Resynchronize with GitHub** In the rare event your repositories or related data in Macroscope ever fall out of sync with GitHub, you can click the "Resynchronize Now" button in Settings โ†’ Support to manually trigger a resynchronization. **Code Review Improvements** Improved bug detection across the 8 languages Macroscope code review supports. Our new pipeline will identify many more potential issues than before. In testing, we observed a significant improvement in detection rates with only a marginal increase in disapproval rates. **Status for "Run Now" Macros** When clicked, the "Run Now" button on the Macros Page shows live status, so users know when a Macro is executing and that the results will be posted to Slack soon. **Project Focus Breakdown Chart Tooltips** Tooltips in the Project Focus Breakdown chart on the Productivity Page have been improved for readability. **Account Settings Code Review Toggle** Users now have the flexibility to turn off correctness code reviews for their own PRs at the account level. This toggle is available in Settings โ†’ Account and gives each user more control over their review experience. **Mobile Experience Improvements** Improved scrolling behavior and updated UI for a smoother, more consistent experience on mobile. # Check Run Agents Source: https://docs.macroscope.com/check-run-agents Custom agentic check runs that enforce your rules and take action on every PR Check Run Agents are customizable AI agents that can run on pull request opens, pushes, label changes, and manual re-runs. They can access your codebase, git history, and connected integrations, and you define what to check, how to format output, and what actions to take. Macroscope automatically runs two built-in check runs on every PR: [**Correctness**](/bug-detection-and-fixes) (catches runtime bugs and logic errors) and [**Approvability**](/approvability) (evaluates merge readiness). Your custom agents appear alongside them in the Checks tab.