Install
macroscope to your PATH, installs plugins for supported Claude Code, Codex, Cursor, and OpenCode setups, and starts sign-in and workspace selection. Relaunch an already-open coding agent to load the plugin.
Run from the terminal
--base to detect the comparison base automatically. Run macroscope without arguments for the interactive setup and review interface.
Detection mode
CLI reviews default to Balanced.--mode accepts budget, balanced, precise, or ultra; invalid values fail before review. Choosing a mode requires Detection Modes to be enabled for the workspace.
Review location and isolation
Reviews use a frozen snapshot of the branch, including work in progress, in a temporary worktree. You can keep editing without changing the review’s input. The worktree is removed on exit; a later review cleans up leftovers from crashes. Use--isolate=false to review the live tree, --keep-worktree to retain the snapshot, or --worktree-dir to choose its parent directory. The latter two imply isolation, but an explicit --isolate=false wins.
Review flags
--in-place is the deprecated spelling of --isolate=false. It still works, but use --isolate=false in new scripts.
Run macroscope --help for the complete command overview or macroscope codereview --help for review-specific examples and flags.
Setting your own defaults
Set defaults for the isolation flags in~/.macroscope/config.yaml:
MACROSCOPE_WORKTREE_DIR sets the worktree directory too. Settings resolve in this order: flags, then environment variables, then the config file, then the built-in defaults.
A saved worktree_dir or keep_worktree: true implies isolation, so it overrides isolate: false in the same file: those settings only mean something in a worktree. To review the live working tree while keeping them, pass --isolate=false on the command line; an explicit flag beats the whole config.
Machine-readable output
Use--raw for a blocking, wizard-free review:
review_session_id=... token, then writes line-oriented issue_event=<json> records to stderr as findings arrive. With --keep-worktree it also emits review_worktree=..., the absolute path of the worktree the review ran in. At the terminal state, it emits a per-attempt review_id=... and issue_status=completed or issue_status=failed, so automation can track the run from startup through completion.
Raw mode is a streaming protocol, not a single JSON document. To collect only the issue payloads as a JSON array, use:
pipefail subshell matters: without it the pipeline reports jq’s status, so a review that failed or needs an update looks like a success. With it, review or parsing failures return non-zero, and a run with no findings still prints a valid empty [].
Exit codes
Other commands
Use the agent plugin
The review skill validates findings and reports confirmed issues by severity, file, and line. It does not edit files.
Run the autopilot loop
Autoloop reviews, fixes confirmed issues in your working tree, commits, and reviews again, up to five iterations or a clean pass. It runs locally without opening PRs or waiting for GitHub checks. Add--isolate to run the loop in a separate worktree. The agent verifies the patch against your current checkout and provides git apply instructions.
Excluding files from review
CLI reviews use the latest committed ignore file on the reviewed branch. Uncommitted edits to the ignore file do not affect review scope. Defaults,ignoreTests: false, and always-excluded binary types behave as on GitHub.
Ignored files are not reviewed or billed. If all changes are ignored, the review succeeds with “All changed files are excluded by ignore rules - nothing to review”.
Signing in on Linux without a keyring
The CLI uses the OS credential service by default. On Linux without Secret Service, setup offers file storage. Accepting savescredential_store: file in ~/.macroscope/config.yaml; declining exits with keyring setup guidance.
To select file storage explicitly:
~/.macroscope/credentials with mode 0600, under a 0700 directory.
The environment variable overrides the saved preference. Accepted values are keyring and file; there is no automatic fallback or migration. Switching stores uses an existing session in that store or requires sign-in. macroscope logout clears only the selected store, so log out before switching if you want to remove the old session.