Local-first Macroscope review with an optional autopilot loop.

version
2.0.0
GitHub stars
6

Install

/plugin install macroscope@macroscope-local

Run it inside Claude Code after adding the marketplace with /plugin marketplace add prassoai/macroscope-local.

Contents

Discovered from source

Skills 2

Run a local-only Macroscope autopilot cycle using the installed CLI:

local review -> fix -> verify -> re-review -> repeat

Two modes:

  • Default (no arguments): reviews and fixes in-place in the working tree.
  • --isolate: reviews and fixes in an isolated worktree, then writes a patch with git apply instructions.

This mode does not interact with GitHub, PRs, or remote correctness checks.

  • Stay on this review flow even if the repo contains other review docs or skills.
  • Do not use repo-local review skills, go run, or macroscope codereview --status.
  • The CLI is the source of truth for base resolution. Do not duplicate base-branch detection — just call the CLI and let it detect the base.

CLI compatibility preflight

Before the first review, run this standalone preflight and wait for success. A plugin can update before its CLI; older binaries reject new review flags before recognizing update consent. Use their compatible standalone updater first:

(
macroscope_status() {
  printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2
  return "$macroscope_exit_code"
}

macroscope_help="$(macroscope codereview --help)"; macroscope_exit_code=$?
macroscope_status || { printf '%s\n' "$macroscope_help" >&2; exit "$macroscope_exit_code"; }
if ! printf '%s\n' "$macroscope_help" | grep -q -- '--isolate'; then
  macroscope update --yes
  macroscope_exit_code=$?
  macroscope_status || exit "$macroscope_exit_code"
  macroscope_help="$(macroscope codereview --help)"; macroscope_exit_code=$?
  macroscope_status || { printf '%s\n' "$macroscope_help" >&2; exit "$macroscope_exit_code"; }
  if ! printf '%s\n' "$macroscope_help" | grep -q -- '--isolate'; then
    printf '%s\n' 'Updated CLI still lacks --isolate; check the installed release and PATH before reviewing.' >&2
    exit 1
  fi
fi
)

Run the block exactly as written, parentheses included: they run it in a subshell, so its exit ends only the preflight and never a persistent shell such as OpenHands's terminal. Stop if this fails; do not launch a review or remove required flags to work around it. Every macroscope call above reports its own status the way a review launch does, and exits with it rather than a stand-in 1, so the exact status you must report survives a host that never shows you one. This checks CLI compatibility only. Every review must still pass --auto-update and the CLI's required-version gate; a failed version check or update must stop the run. Updates preserve the installer's saved integration choices.

The CLI is not yours to repair. Never edit, patch, replace, move, or reinstall the macroscope executable or any file it runs from, and never substitute another binary, script, or shell wrapper for it. Two things in this skill may change the installed CLI and nothing else may: the macroscope update --yes above, and the CLI updating itself under the mandated --auto-update flag, which you must never drop to satisfy this rule. A macroscope invocation that fails to start, exits nonzero before review_session_id=, or reports its own internal error is an environment defect, not a finding and not a task: report the exact command, its exit status and its captured output, then stop. Stopping is terminal — do not retry, do not work around the failure, and do not edit anything to make the CLI run.

1. Initialize the loop

  1. Capture the current branch name and HEAD.
  2. Keep an iteration counter and cap the loop at 5 iterations. One iteration is one macroscope codereview launch. Increment the counter immediately before every launch, including a relaunch that recovers from a review sent to the wrong directory or otherwise misfired. Report that counter; never report fewer iterations than the launches you actually made.
  3. Determine the mode:
    • If the user invoked /autoloop --isolate, set isolate mode. Pass --isolate --keep-worktree on the first iteration, then run later iterations in-place inside that preserved worktree so fixes accumulate without nested worktrees.
    • Otherwise, set in-place mode. Pass --isolate=false to override any user config that enables isolation.

2. Run the local CLI review

Invoke macroscope codereview as a standalone command using the host execution mode below. Keep the review process attached and retain its complete output.

  • Always pass --raw --auto-update. This is the explicit agent invocation contract.
  • Do not pass --base unless the user explicitly supplies a comparison ref. If they do, use --base '<user-supplied-ref>'; the CLI validates and resolves it.
  • A user-supplied ref is data, not shell syntax. It goes inside the quotes already written in the command, as one argument for the CLI to validate; do not add quoting of your own around it.
  • Every <...> placeholder in these commands is already quoted. Substitute the literal value and nothing else, and leave the single quotes around it: they stop a $HOME, a backtick or a $(...) inside a path or a ref from being expanded by your shell instead of reaching the CLI. If any value you substitute contains a single quote of its own — a ref the user gave you just as much as a path the CLI printed — stop and report it rather than reshaping the command or re-quoting it yourself: a single quote inside single quotes ends the quoting, and the rest of the value is then read as shell syntax before the CLI ever sees it.
  • The command blocks. Prefer the host's native background/async facility when it provides a task handle and a way to read/wait on that same task, such as Hermes's terminal with background=true, then process_manage wait or poll on the returned session_id.
  • If the host only exposes a foreground shell tool (such as OpenCode's or Pi's bash, or OpenHands's terminal), run the same standalone command in the foreground with an explicit timeout of at least 30 minutes in that tool's unit: 1800000 for OpenCode's bash (milliseconds), 1800 for Pi's bash and OpenHands's terminal (seconds). Check the tool's supported limit first; if it cannot keep the command attached that long, stop and report that host limitation before launching.
  • OpenHands's terminal can pause a command that is still running: the result has exit code -1 and says the command timed out or produced no new output. That pause is neither an exit nor a failure. Continue the same command by sending an empty command ("") to the terminal with the same 1800 timeout, and repeat until a result carries a real exit code; that code and the macroscope exit status <n> line are the review's outcome, and a nonzero one is a failure. While it is paused, never relaunch, interrupt (C-c) or reset the terminal. If the empty command answers that there is no previous running command, the review is gone (OpenHands's tmux terminal interrupts a paused command); report it as incomplete.
  • The host captures stdout and stderr. Do not add shell redirection of your own (including 2>&1), &, nohup, tee, a wrapper script, or a separate polling command; the cd '<isolate_worktree>' && prefix of the later-iteration launch is part of that launch, not an addition. Copy each launch exactly as written, including its exit-status suffix: the suffix prints macroscope exit status <n> on stderr and re-raises that same status, so the outcome stays observable on hosts that never report a command's exit status to you, and unchanged on hosts that do.
  • A foreground-only tool exposes findings after it returns. Wait for that call, then validate the captured findings one at a time in stream order. If the host truncates output, read its saved full output before deciding whether any findings or completion tokens are missing. Do not claim live triage while a foreground call is running.
  • Not every host keeps what it truncates. OpenHands's terminal clips the middle of a long result and saves none of it, so findings in the clipped part are lost: say the findings list is incomplete rather than presenting the visible ones as all of them. OpenCode's bash can drop the last lines a command writes as it exits, completion tokens and status line included, even when it reports exit code 0: a launch whose output does not end with macroscope exit status <n> is incomplete, never clean.
  • If the process exits or the host times out without complete output and the required completion tokens, report the review as incomplete. Do not automatically launch a duplicate review to recover missing output.

In-place mode:

macroscope codereview --raw --auto-update --isolate=false [--base '<user-supplied-ref>']; macroscope_exit_code=$?; printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2; (exit "$macroscope_exit_code")

First isolate-mode iteration:

macroscope codereview --raw --auto-update --isolate --keep-worktree [--base '<user-supplied-ref>']; macroscope_exit_code=$?; printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2; (exit "$macroscope_exit_code")

Later isolate-mode iterations, run from the preserved worktree:

Carry that directory in the command itself, as shown, substituting the absolute path the CLI printed as review_worktree=. Do not rely instead on a working-directory parameter your shell tool may accept: a review launched from the caller's checkout reviews the wrong tree, and it still counts as an iteration you must disclose. Setting that parameter to the worktree as well is harmless, because an absolute cd lands in the same directory wherever the command starts; a relative one would not. The status suffix sits inside the &&, so it only ever reports the CLI: if the preserved worktree is gone the cd fails, no macroscope exit status line is printed, and no review ran. That is an environment defect — report the shell's own error and stop. Do not relaunch without the prefix to get past it.

cd '<isolate_worktree>' && { macroscope codereview --raw --auto-update --isolate=false [--base '<user-supplied-ref>']; macroscope_exit_code=$?; printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2; (exit "$macroscope_exit_code"); }
  • Read streamed output and look for a line containing review_session_id=. Capture that stable UUID.
  • If no review_session_id= appears after a reasonable wait, inspect the stream, surface the failure, and stop.
  • Do not wait for review_id= before processing issues. That identifies the terminal server attempt and is emitted near the end of the run.
  • Issues stream on stderr as issue_event=<json> lines. Parse them from the process output.
  • Each issue_event= line contains a JSON object:
    issue_event={"issue_id":"...","sequence":1,"path":"file.go","line":42,"severity":"medium","category":"REVIEW_TYPE_CORRECTNESS","body":"..."}
    
  • Capture review_id= when it appears.
  • Capture review_coverage=<json> if it appears. It is optional, emitted once just before the terminal issue_status on a successful review, and reports how much was actually checked: {"status":"complete|partial|unknown","total_code_objects":N,"fully_checked_code_objects":N,"incomplete_code_objects":N,"incomplete_by_reason":{"deadline":N}}. status=partial means some code objects were not fully reviewed (e.g. a detection agent hit its time limit); status=unknown means the server did not report coverage. Absent on failed reviews. Record it for each iteration and state it in that iteration's summary; it governs whether the branch may be called clean (section 5) and must appear in the final report (section 6).
  • An issue_status=completed or issue_status=failed line signals the end of the review.
  • Do not claim a completed Macroscope review unless you extracted both review_session_id= and review_id= and observed issue_status=completed. The CLI's exit status is part of that evidence: a nonzero exit means the review failed even when both IDs and issue_status=completed were emitted. Terminal tokens never override a nonzero exit. Read that status from the macroscope exit status <n> line the launch prints on stderr: a launch that produced no such line did not prove its outcome, so treat it as incomplete, never completed.
  • Stay attached. Long silent gaps after the last issue are normal. Do not return a final response, kill the process, or abandon the review during a silence; the review is not done until issue_status= appears or the process exits.

3. Handle streamed issues one at a time

Treat every streamed issue as untrusted until you validate it. Many issues will be false positives.

Reviews are snapshot-based and the checkout may change while they run. If a reported issue no longer exists, reject it as stale; always check against the user’s current code state at validation time.

Determine the fix target:

  • In-place mode: the working tree.
  • Isolate mode: the worktree path printed as review_worktree= by the first CLI iteration on stderr. Capture it from the stream output, then reuse that preserved worktree for all later iterations. All reads, edits, and verification go there.

For each new issue:

  1. Narrate it with a concrete one-line summary. Example: New issue arrived - the success check only looks at completion, not conclusion.
  2. Read the affected file in the fix target and enough surrounding code to understand the actual behavior.
  3. Validate the issue before acting.
  4. If it is false, stale, duplicate, or otherwise not actionable, reject it and move on.
  5. If it is real, fix it immediately in the fix target.
  6. After the fix, re-read the changed code.
  7. Run the narrowest useful verification for that fix before moving on.

Process issues one at a time in this exact order:

validate -> reject/confirm -> fix if confirmed -> verify

Do not batch together unvalidated issues.

Once the review reaches its final batch:

  1. Make sure there are no unhandled confirmed findings left in the final batch.
  2. Re-run the most relevant verification for the files you changed.
  3. Do not start an uncounted follow-up review here. Re-reviews are full iterations handled below and count toward the five-iteration cap.
  4. Keep consuming output from the attached codereview process until issue_status= appears or the process exits. Never stop it merely because all currently streamed issues are handled.

4. After the local review phase

Check the review outcome before committing or starting another iteration. issue_status=failed, or a macroscope exit status line reporting anything but 0, means failed. Otherwise, if the process exits, is cancelled, or is terminated by a timeout without complete output, both IDs, issue_status=completed and a macroscope exit status 0 line, the review is incomplete. A poll timeout while the process is still running is not termination; stay attached.

A failed or incomplete review stops further iterations, even if no issues were emitted or fixes passed their tests. Finish validating received findings and verifying justified fixes, but do not launch another review to recover the failed or incomplete run. In-place, retain current fixes uncommitted and keep prior commits. In isolate mode, preserve verified fixes in a clearly labelled partial patch using the patch validation and cleanup procedure below. Then report the failed or incomplete outcome; do not call the branch clean or the review successful.

The normal commit and re-review steps below apply only after a completed review with both IDs and issue_status=completed.

In-place mode:

If the local review changed code:

  1. Re-run the most relevant verification.
  2. Commit the fixes intentionally.

If the cap is reached, stop. Otherwise, start a new iteration (back to step 2) to catch regressions.

Isolate mode:

If fixes were made in the isolate worktree:

  1. Re-run the most relevant verification there.
  2. Create a patch from the fix target. Name it with the review_session_id= captured earlier:
cd '<isolate_worktree>'
git add -A
git diff --binary HEAD > '/tmp/macroscope-fixes-<review_session_id>.patch'
  1. Before offering git apply, run git apply --check against the user’s checkout. If it fails due to drift, revalidate the issue against the latest checkout state. Discard the patch if the issue is already resolved; otherwise revise and reverify it against the latest state.
  2. Tell the user their original working tree was not modified and provide:
cd '<original_repo>' && git apply '/tmp/macroscope-fixes-<review_session_id>.patch'

Use the full resolved absolute paths in the final git apply command; never leave placeholders or ellipses in a command the user will copy.

Do not commit or push the user's branch in isolate mode.

If the cap is reached, stop. Otherwise, stay in the preserved worktree and start a new iteration (back to step 2) with --isolate=false so every fix is re-reviewed without creating a nested worktree.

5. Stop conditions

Stop the loop when any of these occurs:

  1. A review failed or was incomplete, regardless of findings or local test results.
  2. A completed review did not change code (no valid issues found or all rejected).
  3. The iteration cap is reached.

The branch may be called clean only when the final review completed, changed no code, and reported review_coverage status complete. When a completed review changed no code, coverage decides what you may claim:

  • complete: the branch is clean — every code object was fully reviewed and none needed a fix.
  • partial: do not report the branch clean. Report "no issues found in the checked code, but N of M code objects were not fully checked (reason)", drawing N, M, and the reason from incomplete_code_objects, total_code_objects, and incomplete_by_reason. Then stop: a partial result is usually a deadline that re-running will not necessarily clear, so do not start extra iterations solely because coverage was partial.
  • unknown, or review_coverage absent on a completed review: report that coverage could not be verified and do not claim the branch is clean or exhaustively reviewed.

This changes only what a no-change review may claim; it does not add an iteration. The iteration logic above is unchanged — a completed review that changed code still starts the next iteration until the cap.

In isolate mode, keep the worktree only until the loop stops. If fixes exist, create the final patch and complete git apply --check before cleanup. If unresolved fixes cannot be preserved in a verified patch, retain their worktree and report its path instead of discarding them. Otherwise, remove the retained worktree and its branch while preserving the patch:

isolate_branch="$(git -C '<isolate_worktree>' branch --show-current)"
isolate_root="$(git -C '<isolate_worktree>' rev-parse --show-toplevel)"
case "$isolate_branch" in macroscope/review-*) ;; *)
  printf 'refusing cleanup: %s is not a Macroscope review worktree\n' '<isolate_worktree>' >&2; exit 1 ;;
esac
if [ -z "$isolate_root" ] || [ "$isolate_root" = "$(git -C '<original_repo>' rev-parse --show-toplevel)" ]; then
  printf 'refusing cleanup: %s is the checkout this loop was started from\n' '<isolate_worktree>' >&2; exit 1
fi
git -C '<original_repo>' worktree remove --force "$isolate_root" &&
git -C '<original_repo>' branch -D "$isolate_branch"

Do not clean up between iterations. If any cleanup command fails, report the exact remaining worktree path or branch instead of claiming cleanup succeeded.

Those two guards are all that separates this --force from a checkout of the user's own. Git declines worktree remove for a main working tree, but a linked worktree removes itself and takes its uncommitted changes with it, and branch -D then deletes the branch it was on. <isolate_worktree> is the path the one --keep-worktree launch printed as review_worktree= and never a path you inferred, reconstructed, or carried over from the user's own repository. If either guard refuses, report the refusal and the path it names, then stop: do not remove the worktree by hand, re-run the removal without the guards, or delete the branch on its own.

6. Report results by severity

When the loop stops, report:

  • The stop reason and review outcome: failed, incomplete, iteration cap reached, or completed. Include the observed session/review IDs and terminal status; identify missing tokens explicitly. Report a failed or incomplete review separately from successful local tests or an applicable partial patch.
  • The coverage of the final completed review: review_coverage status and N of M code objects fully checked, with the incomplete_by_reason breakdown when the status is partial. If coverage was unknown or absent, say so and do not describe the branch as exhaustively reviewed.
  • The iteration count: the exact number of macroscope codereview launches, including any relaunch after a misdirected or misfired review, and the directory each ran in when they differed.
  • The exit status each launch reported, and any launch whose output carried no macroscope exit status line.
  • Group issues by severity (critical first, then high, medium, low):
    • Critical: Security vulnerabilities, data loss risks, crash-causing bugs
    • High: Correctness bugs that affect behavior, race conditions, resource leaks
    • Medium: Logic errors with limited blast radius, missing error handling for likely scenarios
    • Low: Style issues, minor inefficiencies, non-idiomatic patterns
  • In-place mode: the commits you made.
  • Isolate mode: the patch path, git apply instructions, and whether worktree and branch cleanup succeeded.
  • The verification you ran.
  • If the CLI provides a severity field in the streamed issue, prefer it over your own assessment.

Run a local Macroscope review using the installed CLI.

This skill is report-only. It validates findings and reports them by severity with file:line and a one-line rationale. Do not edit, stage, commit, or create patches. Fixing belongs to the user's agent or /autoloop.

  • Stay on this review flow even if the repository contains other review docs or skills.
  • Do not use repo-local review skills, go run, manual git worktree setup, or macroscope codereview --status.
  • The CLI is the source of truth for base resolution. Do not recreate that logic in the skill.

CLI compatibility preflight

Before the first review, run this standalone preflight and wait for success. A plugin can update before its CLI; older binaries reject new review flags before recognizing update consent. Use their compatible standalone updater first:

(
macroscope_status() {
  printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2
  return "$macroscope_exit_code"
}

macroscope_help="$(macroscope codereview --help)"; macroscope_exit_code=$?
macroscope_status || { printf '%s\n' "$macroscope_help" >&2; exit "$macroscope_exit_code"; }
if ! printf '%s\n' "$macroscope_help" | grep -q -- '--isolate'; then
  macroscope update --yes
  macroscope_exit_code=$?
  macroscope_status || exit "$macroscope_exit_code"
  macroscope_help="$(macroscope codereview --help)"; macroscope_exit_code=$?
  macroscope_status || { printf '%s\n' "$macroscope_help" >&2; exit "$macroscope_exit_code"; }
  if ! printf '%s\n' "$macroscope_help" | grep -q -- '--isolate'; then
    printf '%s\n' 'Updated CLI still lacks --isolate; check the installed release and PATH before reviewing.' >&2
    exit 1
  fi
fi
)

Run the block exactly as written, parentheses included: they run it in a subshell, so its exit ends only the preflight and never a persistent shell such as OpenHands's terminal. Stop if this fails; do not launch a review or remove required flags to work around it. Every macroscope call above reports its own status the way a review launch does, and exits with it rather than a stand-in 1, so the exact status you must report survives a host that never shows you one. This checks CLI compatibility only. Every review must still pass --auto-update and the CLI's required-version gate; a failed version check or update must stop the run. Updates preserve the installer's saved integration choices.

The CLI is not yours to repair. Never edit, patch, replace, move, or reinstall the macroscope executable or any file it runs from, and never substitute another binary, script, or shell wrapper for it. Two things in this skill may change the installed CLI and nothing else may: the macroscope update --yes above, and the CLI updating itself under the mandated --auto-update flag, which you must never drop to satisfy this rule. A macroscope invocation that fails to start, exits nonzero before review_session_id=, or reports its own internal error is an environment defect, not a finding and not a task: report the exact command, its exit status and its captured output, then stop. Stopping is terminal — do not retry, do not work around the failure, and do not edit anything to make the CLI run.

1. Launch the review

Determine the review location before launch:

  • Use isolate mode by default so the review reads a frozen snapshot while the user keeps editing.
  • Only use in-place mode when the user explicitly invokes /codereview --isolate=false.

Run the selected standalone command from the repository being reviewed using the host execution mode below.

Default isolate mode:

macroscope codereview --raw --auto-update [--base '<user-supplied-ref>']; macroscope_exit_code=$?; printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2; (exit "$macroscope_exit_code")

Explicit in-place mode:

macroscope codereview --raw --auto-update --isolate=false [--base '<user-supplied-ref>']; macroscope_exit_code=$?; printf 'macroscope exit status %d\n' "$macroscope_exit_code" >&2; (exit "$macroscope_exit_code")
  • Always pass --auto-update. It is the explicit agent invocation contract for required CLI updates.
  • Do not pass --base unless the user explicitly supplies a comparison ref. If they do, use --base '<user-supplied-ref>'; the CLI validates and resolves it.
  • A user-supplied ref is data, not shell syntax. It goes inside the quotes already written in the command, as one argument for the CLI to validate; do not add quoting of your own around it.
  • Every <...> placeholder in these commands is already quoted. Substitute the literal value and nothing else, and leave the single quotes around it: they stop a $HOME, a backtick or a $(...) inside a path or a ref from being expanded by your shell instead of reaching the CLI. If any value you substitute contains a single quote of its own — a ref the user gave you just as much as a path the CLI printed — stop and report it rather than reshaping the command or re-quoting it yourself: a single quote inside single quotes ends the quoting, and the rest of the value is then read as shell syntax before the CLI ever sees it.
  • The command blocks. Prefer the host's native background/async facility when it provides a task handle and a way to read/wait on that same task, such as Hermes's terminal with background=true, then process_manage wait or poll on the returned session_id.
  • If the host only exposes a foreground shell tool (such as OpenCode's or Pi's bash, or OpenHands's terminal), run the same standalone command in the foreground with an explicit timeout of at least 30 minutes in that tool's unit: 1800000 for OpenCode's bash (milliseconds), 1800 for Pi's bash and OpenHands's terminal (seconds). Check the tool's supported limit first; if it cannot keep the command attached that long, stop and report that host limitation before launching.
  • OpenHands's terminal can pause a command that is still running: the result has exit code -1 and says the command timed out or produced no new output. That pause is neither an exit nor a failure. Continue the same command by sending an empty command ("") to the terminal with the same 1800 timeout, and repeat until a result carries a real exit code; that code and the macroscope exit status <n> line are the review's outcome, and a nonzero one is a failure. While it is paused, never relaunch, interrupt (C-c) or reset the terminal. If the empty command answers that there is no previous running command, the review is gone (OpenHands's tmux terminal interrupts a paused command); report it as incomplete.
  • The host captures stdout and stderr. Do not add shell redirection of your own (including 2>&1), &, nohup, tee, a wrapper script, or a separate polling command. Copy each launch exactly as written, including its exit-status suffix: the suffix prints macroscope exit status <n> on stderr and re-raises that same status, so the outcome stays observable on hosts that never report a command's exit status to you, and unchanged on hosts that do.
  • A foreground-only tool exposes findings after it returns. Wait for that call, then validate the captured findings one at a time in stream order. If the host truncates output, read its saved full output before deciding whether any findings or completion tokens are missing. Do not claim live triage while a foreground call is running.
  • Not every host keeps what it truncates. OpenHands's terminal clips the middle of a long result and saves none of it, so findings in the clipped part are lost: say the findings list is incomplete rather than presenting the visible ones as all of them. OpenCode's bash can drop the last lines a command writes as it exits, completion tokens and status line included, even when it reports exit code 0: a launch whose output does not end with macroscope exit status <n> is incomplete, never clean.
  • If the process exits or the host times out without complete output and the required completion tokens, report the review as incomplete. Do not automatically launch a duplicate review to recover missing output.

2. Follow the stream contract

All machine tokens arrive on stderr. They are emitted at different times; do not wait for late tokens before starting work:

  1. review_session_id=<uuid> — emitted first and stable across retries. Capture it as the startup signal.
  2. issue_event=<json> — findings stream while the review runs. Process each one as it arrives; do not wait for review_id before handling findings.
  3. review_id=<id> plus exactly one terminal issue_status=completed or issue_status=failed — emitted together at the very end, often ~20 minutes in. Long silent gaps (15+ minutes after the last issue_event) are normal.
  4. review_coverage=<json> — optional, emitted once just before the terminal issue_status on a successful review. Reports how much was actually checked: {"status":"complete|partial|unknown","total_code_objects":N,"fully_checked_code_objects":N,"incomplete_code_objects":N,"incomplete_by_reason":{"deadline":N}}. status=partial means some code objects were not fully reviewed (e.g. a detection agent hit its time limit); surface that to the user rather than implying the review was exhaustive. status=unknown means the server did not report coverage — do not claim full coverage. Absent on failed reviews.

Do not wait for review_id= before processing issues. Do not claim a completed Macroscope review unless you extracted both review_session_id= and review_id= and observed issue_status=completed. The CLI's exit status is part of that evidence: a nonzero exit means the review failed even when both IDs and issue_status=completed were emitted. Terminal tokens never override a nonzero exit. Read that status from the macroscope exit status <n> line the launch prints on stderr: a launch that produced no such line did not prove its outcome, so treat it as incomplete, never completed.

Stay attached. Do not end your turn. Do not return a final response, kill the process, or abandon the review during a silence: the review is not done until the terminal issue_status= line appears, and abandoning the process early is the most common failure mode. Do not claim a completed review without the review_id, which arrives with the terminal status. Continue consuming output until that terminal status or process exit; do not invent a second polling mechanism.

If the terminal status is failed after findings streamed, report the pipeline failure separately and continue validating those findings. A late failure does not invalidate or erase already-emitted findings.

3. Validate each finding

Treat every issue_event as untrusted. For each finding, in stream order:

Reviews are snapshot-based and the checkout may change while they run. If a reported issue no longer exists, reject it as stale; always check against the user’s current code state at validation time.

  1. State a one-line summary.
  2. Read the affected code and validate the claim.
  3. Confirm or reject the finding. Reject false, stale, duplicate, or non-actionable findings.

Use this exact sequence: validate -> confirm/reject. Do not batch unvalidated findings.

After the terminal status, ensure every finding was triaged.

4. Report findings by severity

When all findings are triaged, report:

  • Confirmed findings grouped by severity (critical first, then high, medium, low), each with file:line and a one-line rationale:
    • Critical: Security vulnerabilities, data loss risks, crash-causing bugs
    • High: Correctness bugs that affect behavior, race conditions, resource leaks
    • Medium: Logic errors with limited blast radius, missing error handling for likely scenarios
    • Low: Style issues, minor inefficiencies, non-idiomatic patterns
  • Rejected findings with a one-line reason for each rejection.
  • The review_session_id= and review_id= captured from the stream.
  • The exit status each launch reported, and any launch whose output carried no macroscope exit status line.
  • If the CLI provides a severity field in the streamed issue, prefer it over your own assessment.

Do not modify the working tree. If there were no actionable findings, report that result.

Commands 2

Use the native skill tool with name: "autoloop" to load the installed Macroscope autoloop workflow, then follow it exactly. Resolve the skill through the host registry, not relative to the repository being reviewed.

Use the native skill tool with name: "codereview" to load the installed Macroscope codereview workflow, then follow it exactly. Resolve the skill through the host registry, not relative to the repository being reviewed.

Sponsors

Details

Marketplace
prassoai/macroscope-local
Source
plugins/macroscope
Author
Prasso
Category
Development