### Install Macroscope CLI

Source: https://docs.macroscope.com/cli

Run this command to download and install the Macroscope CLI. It also sets up plugins for supported IDEs and starts the setup wizard.

```bash
curl -sSL https://raw.githubusercontent.com/prassoai/macroscope-local/main/install.sh | bash
```

--------------------------------

### Example Request to Slack Thread

Source: https://docs.macroscope.com/api

This example demonstrates how to post a query's results to a specific Slack thread by including the 'slackThreadTs' in the response destination. This is useful for maintaining conversation context.

```bash
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"
  }'
```

--------------------------------

### Example .macroscope/ignore file

Source: https://docs.macroscope.com/bug-detection-and-fixes

Configure Macroscope to skip specific files or directories during code review by listing glob patterns in this file. Each pattern should be on a new line. Lines starting with '#' are comments, and blank lines are ignored. Supports glob patterns like `**`, `*`, and `?`.

```text
# Vendor dependencies
vendor/**

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

# Lock files
*.lock

# Documentation assets
docs/**/*.pdf

# Log directories
logs/**
```

--------------------------------

### Example PR Template with Summary Markers

Source: https://docs.macroscope.com/pull-request-descriptions

This example demonstrates how to integrate Macroscope's PR summary markers into a standard pull request template. The summary will be placed between the specified markers.

```markdown
## Why are we making this change?
Explain the motivation here.

## Pull Request Summary
<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope's pull request summary ends here -->

## Checklist
- [ ] Code compiles and passes tests
- [ ] Documentation updated
```

--------------------------------

### Example Area Markdown Description

Source: https://docs.macroscope.com/areas

This markdown snippet shows an example of how to write an effective description for an Area. Descriptions are used by Macroscope to classify commits, so include types of work, specific terminology, team names, and related systems.

```markdown
**Area Name:** Consumer Growth

**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

```

--------------------------------

### Example Request to External URL

Source: https://docs.macroscope.com/api

Send query results to an external webhook by specifying a 'webhookUrl' in the 'responseDestination'. Ensure the URL is allowlisted in your Macroscope settings.

```bash
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"
  }'
```

--------------------------------

### Example Request to Slack Channel

Source: https://docs.macroscope.com/api

Use this curl command to send a query and have the results posted directly to a specified Slack channel. Ensure the correct channel ID is provided.

```bash
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"
  }'
```

--------------------------------

### Invoke Macroscope Code Review in IDEs

Source: https://docs.macroscope.com/cli

Commands to initiate a local code review using Macroscope within various IDEs. Ensure Macroscope is installed and your agent is relaunched if it was already open.

```text
Claude Code: /macroscope:codereview
Codex:       /macroscope:codereview
Cursor:      /codereview
OpenCode:    /macroscope-codereview
```

--------------------------------

### GitHub Actions: Check Protobuf Generated Code

Source: https://docs.macroscope.com/fix-it-for-me

This GitHub Actions workflow checks if Protobuf generated files are up-to-date. It installs protoc plugins, regenerates files, and fails the build if any changes are detected.

```yaml
name: Protobuf generated code up-to-date

on:
  push:
  pull_request:

jobs:
  protobuf-gen-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"
      - name: Install protoc plugins
        run: |
          go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
          go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
      - name: Regenerate protobuf files
        run: protoc -I=proto --go_out=. --go-grpc_out=. proto/*.proto
      - name: Fail if generated files changed
        run: git diff --exit-code

```

--------------------------------

### Invoke Macroscope Autoloop Mode in IDEs

Source: https://docs.macroscope.com/cli

Commands to start the Autoloop mode in Macroscope from supported IDEs. This mode performs an unattended review-and-fix cycle locally.

```text
Claude Code: /macroscope:autoloop
Codex:       /macroscope:autoloop
Cursor:      /autoloop
OpenCode:    /macroscope-autoloop
```

--------------------------------

### Configure Agent Model and Parameters

Source: https://docs.macroscope.com/check-run-agents

Use this front matter to specify the agent's model and configure reasoning and effort levels. Ensure the model is recognized by Macroscope to avoid falling back to the default.

```markdown
---
title: Security Review
model: claude-opus-4.5
reasoning: high
effort: medium
---

Your instructions here.
```

--------------------------------

### Custom Instruction File with Front Matter

Source: https://docs.macroscope.com/custom-instructions

Define `include` and `exclude` glob patterns in the YAML front matter of a custom instruction markdown file to scope its application. If omitted, instructions apply globally.

```yaml
---
include:
  - "**/*.go"
  - "**/config/**"
exclude:
  - "**/*_test.go"
  - "**/testdata/**"
---

**Configuration principles.** Configuration must be explicit. No empty-string-means-default. No silent fallbacks. If a required value is missing, fail fast and loud at startup — not silently at runtime with an infinite hang or mysterious behavior. One source of truth for each config value, threaded through explicitly. Misconfiguration is a bug, and bugs must be caught as early as possible.

**No backwards compatibility.** This product is pre-release and in active development, never require dual-support, deprecation warnings, migration code, proto reservations or fallback paths. When something changes, change it everywhere. Break the old way. Delete the old code. Build forward.
```

--------------------------------

### Directory Structure for Custom Instructions

Source: https://docs.macroscope.com/custom-instructions

Organize custom correctness instruction markdown files within the `.macroscope/correctness/` directory at your repository's root. Subdirectories can be used for further organization.

```tree
.macroscope/
└── correctness/
    ├── configuration-principles.md
    ├── transaction-invariants.md
    └── auth-propagation.md
```

```tree
.macroscope/
└── correctness/
    ├── shared-principles.md
    ├── backend/
    │   └── transaction-invariants.md
    └── frontend/
        └── accessibility-rules.md
```

--------------------------------

### Run Macroscope CLI Review Against a Base Branch

Source: https://docs.macroscope.com/cli

Compare your current branch against a specific base branch during a local review by providing the `--base` flag. This allows for targeted comparisons.

```bash
macroscope codereview --base <base-branch>
```

--------------------------------

### YAML Front Matter for Advanced Approvals

Source: https://docs.macroscope.com/approvability

Configure advanced approvability behavior using YAML front matter. This allows specifying tools, conclusion types, and conditions for requesting reviews.

```yaml
---
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 "needs human review" and the PR touches services/auth/,
request a review from @security-team.
```

--------------------------------

### Macroscope Default Ignore Patterns: Base

Source: https://docs.macroscope.com/bug-detection-and-fixes

These patterns cover vendored dependencies, generated code, build output, package manager files, and common asset types. They are applied automatically when no custom ignore file exists.

```text
# === Vendored / dependency directories ===
**/.git/**
**/__pycache__/**
**/.pytest_cache/**
**/.mypy_cache/**
**/.ruff_cache/**
**/venv/**
**/.venv/**
**/node_modules/**
**/site-packages/**
**/.pnpm-store/**
**/__Snapshots__/**
**/__snapshots__/**
**/.agents/skills/**
**/.claude/skills/**
**/.github/skills/**
**/bower_components/**
**/jspm_packages/**
**/.next/**
**/.svelte-kit/**
**/vendor/**
**/_vendor/**
**/third_party/**
**/Pods/**
**/.bundle/**

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--------------------------------

### Use Wildcard to Run After All Other Checks

Source: https://docs.macroscope.com/check-run-agents

Use `"*"` to ensure your agent runs only after all other check runs on the commit have completed. This is useful for summary or cleanup tasks.

```yaml
---
title: PR Summary
waitsFor:
  - "*"
---

Summarize the results of all CI checks on this PR...
```

--------------------------------

### Web Review Check Run Agent Configuration

Source: https://docs.macroscope.com/check-run-agents

Defines a comprehensive check run agent for web development, covering event tracking, accessibility, production errors, labeling, and notifications. Use this to consolidate multiple review concerns into a single agent.

```markdown
---
title: Web Review
model: claude-opus-4-6
effort: medium
input: full_diff
tools:
  - browse_code
  - git_tools
  - modify_pr
  - slack
  - sentry
include:
  - "targets/app/**"
  - "web-etc/**"
---

Review this PR against our web team's standards:

## Event Tracking
If this PR touches payment flows, signup funnels, analytics calls,
CTA buttons, or redirect logic, check whether it could break event
tracking. Rate each issue: 🔴 will stop firing, 🟡 may fire incorrectly,
🟢 low risk.

## Accessibility
Check new or modified React components for basic accessibility:
- Images must have alt text
- Buttons and links must have accessible labels
- Form inputs must have associated labels

## Production Errors
For each file modified, check Sentry for unresolved issues. If any
active errors exist, list them with frequency and last seen date.

## Labels
Add labels to this PR based on what changed:
- "frontend" if any UI components are modified
- "styles" if CSS or styled-components changed
- "docs" if only markdown files changed

## Notifications
If any 🔴/🟡 event tracking issues or accessibility violations are
found, post a summary to #eng on Slack with the PR link.

If nothing noteworthy is found, report that all checks passed.

```

--------------------------------

### Run Macroscope Direct CLI Review

Source: https://docs.macroscope.com/cli

Execute a local code review directly from the terminal using the `macroscope codereview` command. This is useful for scripting or debugging outside the editor.

```bash
macroscope codereview
```

--------------------------------

### Define Named Prerequisites for an Agent

Source: https://docs.macroscope.com/check-run-agents

Specify exact check run names your agent depends on. Use this when your agent needs specific checks to complete before running.

```yaml
---
title: Annotate Correctness
waitsFor:
  - "Macroscope - Correctness Check"  # a Macroscope check
  - "lint"                            # a job with an explicit name: field
  - "ci / test"                       # a job with no name: field (workflow / job id)
tools:
  - browse_code
  - modify_pr
---

Read the review comments left by the Correctness check and add annotations...
```

--------------------------------

### Macroscope Default Ignore Patterns: Test Files

Source: https://docs.macroscope.com/bug-detection-and-fixes

These patterns cover common test file naming conventions and directories across various programming languages. They are applied automatically when no custom ignore file exists.

```text
# === 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/**
```

--------------------------------

### Migrate Check Run Agents to Subfolder

Source: https://docs.macroscope.com/check-run-agents

Command to move existing check run agent files from the root .macroscope/ directory to the .macroscope/check-run-agents/ subfolder. This reorganizes agent files without altering their functionality.

```bash
mkdir -p .macroscope/check-run-agents
mv .macroscope/web-review.md .macroscope/check-run-agents/
# Repeat for each check run agent file. Do not move approvability.md or ignore.

```

--------------------------------

### Wait for All Checks (Wildcard Mode) in YAML

Source: https://docs.macroscope.com/approvability

Employ `waitsFor: ["*"]` to make approvability wait for all CI steps except itself. This is useful when multiple Check Run Agents post comments that should be considered.

```yaml
---
waitsFor:
  - "*"
---
```

--------------------------------

### Set Custom Timeout for Agent Prerequisites

Source: https://docs.macroscope.com/check-run-agents

Configure a custom timeout for how long the agent waits for its prerequisites. The default is 20 minutes, and this can be set between 1 and 60 minutes.

```yaml
---
title: Post-Deploy Check
waitsFor:
  - "deploy-to-staging"
waitsForTimeout: 45
---

Verify the staging deployment succeeded...
```