
macroscope
Local-first Macroscope review with an optional autopilot loop.
- version
- 2.0.0
- GitHub stars
- 6
Install
/plugin install macroscope@macroscope-localRun it inside Claude Code after adding the marketplace with /plugin marketplace add prassoai/macroscope-local.
Contents
Discovered from sourceSkills 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 withgit applyinstructions.
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, ormacroscope 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
- Capture the current branch name and
HEAD. - Keep an iteration counter and cap the loop at 5 iterations. One iteration is one
macroscope codereviewlaunch. 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. - Determine the mode:
- If the user invoked
/autoloop --isolate, set isolate mode. Pass--isolate --keep-worktreeon 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=falseto override any user config that enables isolation.
- If the user invoked
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
--baseunless 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
terminalwithbackground=true, thenprocess_managewaitorpollon the returnedsession_id. - If the host only exposes a foreground shell tool (such as OpenCode's or Pi's
bash, or OpenHands'sterminal), run the same standalone command in the foreground with an explicit timeout of at least 30 minutes in that tool's unit:1800000for OpenCode'sbash(milliseconds),1800for Pi'sbashand OpenHands'sterminal(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
terminalcan pause a command that is still running: the result has exit code-1and 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 theterminalwith the same1800timeout, and repeat until a result carries a real exit code; that code and themacroscope 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; thecd '<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 printsmacroscope 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
terminalclips 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'sbashcan drop the last lines a command writes as it exits, completion tokens and status line included, even when it reports exit code0: a launch whose output does not end withmacroscope 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 terminalissue_statuson 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=partialmeans some code objects were not fully reviewed (e.g. a detection agent hit its time limit);status=unknownmeans 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=completedorissue_status=failedline signals the end of the review. - Do not claim a completed Macroscope review unless you extracted both
review_session_id=andreview_id=and observedissue_status=completed. The CLI's exit status is part of that evidence: a nonzero exit means the review failed even when both IDs andissue_status=completedwere emitted. Terminal tokens never override a nonzero exit. Read that status from themacroscope 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:
- Narrate it with a concrete one-line summary.
Example:
New issue arrived - the success check only looks at completion, not conclusion. - Read the affected file in the fix target and enough surrounding code to understand the actual behavior.
- Validate the issue before acting.
- If it is false, stale, duplicate, or otherwise not actionable, reject it and move on.
- If it is real, fix it immediately in the fix target.
- After the fix, re-read the changed code.
- 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:
- Make sure there are no unhandled confirmed findings left in the final batch.
- Re-run the most relevant verification for the files you changed.
- Do not start an uncounted follow-up review here. Re-reviews are full iterations handled below and count toward the five-iteration cap.
- Keep consuming output from the attached
codereviewprocess untilissue_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:
- Re-run the most relevant verification.
- 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:
- Re-run the most relevant verification there.
- 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'
- Before offering
git apply, rungit apply --checkagainst 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. - 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:
- A review failed or was incomplete, regardless of findings or local test results.
- A completed review did not change code (no valid issues found or all rejected).
- 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 fromincomplete_code_objects,total_code_objects, andincomplete_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, orreview_coverageabsent 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_coveragestatus and N of M code objects fully checked, with theincomplete_by_reasonbreakdown when the status ispartial. If coverage wasunknownor absent, say so and do not describe the branch as exhaustively reviewed. - The iteration count: the exact number of
macroscope codereviewlaunches, 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 statusline. - 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 applyinstructions, 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, manualgit worktreesetup, ormacroscope 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
--baseunless 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
terminalwithbackground=true, thenprocess_managewaitorpollon the returnedsession_id. - If the host only exposes a foreground shell tool (such as OpenCode's or Pi's
bash, or OpenHands'sterminal), run the same standalone command in the foreground with an explicit timeout of at least 30 minutes in that tool's unit:1800000for OpenCode'sbash(milliseconds),1800for Pi'sbashand OpenHands'sterminal(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
terminalcan pause a command that is still running: the result has exit code-1and 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 theterminalwith the same1800timeout, and repeat until a result carries a real exit code; that code and themacroscope 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 printsmacroscope 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
terminalclips 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'sbashcan drop the last lines a command writes as it exits, completion tokens and status line included, even when it reports exit code0: a launch whose output does not end withmacroscope 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:
review_session_id=<uuid>— emitted first and stable across retries. Capture it as the startup signal.issue_event=<json>— findings stream while the review runs. Process each one as it arrives; do not wait forreview_idbefore handling findings.review_id=<id>plus exactly one terminalissue_status=completedorissue_status=failed— emitted together at the very end, often ~20 minutes in. Long silent gaps (15+ minutes after the lastissue_event) are normal.review_coverage=<json>— optional, emitted once just before the terminalissue_statuson 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=partialmeans 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=unknownmeans 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.
- State a one-line summary.
- Read the affected code and validate the claim.
- 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=andreview_id=captured from the stream. - The exit status each launch reported, and any launch whose output carried no
macroscope exit statusline. - 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