SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsqodo-review

qodo-review

Coding & development

View repository

Updated 10-16 04:54

About this skill

Local Review

Description

Review local changes during coding and before handing off completed work. qodo review diffs your working tree against a base commit, includes new/untracked files, and sends the diff plus any coding-session context you supply to Qodo's review engine. It returns structured findings you then evaluate and — with the user's say-so (or autofix) — fix in code. Nothing is pushed and no PR is created; only the base commit must already be on the remote (the reviewer clones it).

Use this skill for local changes, including unpushed work on an existing PR. Use qodo-review-resolver to work on findings from the PR's remote review; do not duplicate that review for an unchanged pushed snapshot.

Prerequisites

  • An authenticated Qodo CLI is available, or a connected QAR MCP server and a tested local input collector are available; review capability is enabled.
  • The comparison base exists on the remote; local changes and context need not be pushed.
  • The coding-session context and any ticket or design references are ready to attach.

Choose when and how deeply to review

Situation Selection
A coherent milestone during substantive coding --fast --async: light checkpoint; continue useful coding and collect the result.
Ordinary final review before opening/updating a PR or handing off completed work Omit both depth flags: auto. Collect and assess the result before claiming review completion.
User intent calls for unusually thorough scrutiny, or a known high blast radius warrants it --deep, with a brief reason tied to the request or affected behavior.

Automatic coding checkpoints always use --fast. A deliberate deep review can happen earlier when one of the exceptions above applies. A request such as "examine subtle races thoroughly" can justify it without the word "deep"; generic "review" or "double-check" does not. Identify concrete impact, such as shared authorization, a destructive migration, or a contract used by multiple services. Diff size, session length, PR readiness, or a security-related filename alone do not justify deep.

With no flag, the CLI omits depth and the reviewer/deployment selects it. Auto can select deep; it is not guaranteed standard and does not impose a spending cap. There is no --standard flag. --fast and --deep are mutually exclusive; depth is selected anew for each invocation.

Checkpoints and final handoff

  • Review a completed, testable slice when its feedback can guide the remaining work. Do not review unfinished exploration, every edit, trivial changes automatically, or simply because time passed. Respect the user's review scope and budget. A pause for a question or approval is not a final handoff.
  • Keep at most one automatic checkpoint active per task. Retain its operation ID, submitted scope and snapshot/context association in the task's existing state. Poll status at natural pauses while doing useful work; do not launch another review to check progress or re-review unchanged inputs.
  • Collect every submitted result within its retention window. Recheck findings against current code before acting: the working tree may have changed. A superseded result cannot certify newer work. Use the existing CLI lifecycle; no separate sub-agent or scheduler is required.
  • Before final review, collect the outstanding checkpoint and reconcile its findings. Review the full intended change with auto, or justified deep, rather than handing off on a light checkpoint. Remove temporary path restrictions that would leave part of the intended change unreviewed. If the same snapshot already has completed final coverage with compatible context, use that result.
  • Batch authorized fixes, verify them, then re-review changed work. Keep --fast for checkpoint fixes; retain the requested auto or justified deep mode for final-review fixes. Let the engine determine incremental eligibility; auto may route differently on each pass. Do not manually switch final fixes to --fast or force --deep just to pin auto routing. If work returns to substantial implementation, resume light checkpoints and establish final coverage again before handoff.
  • If another pass repeats the same concern without actionable progress, stop the automatic loop and report the remaining issue and needed decision/check. Do not buy repeated passes to chase zero. Pending, failed, partial or superseded review is not clean; surface remaining findings and coverage.

Prepare a PR handoff

When preparing to open or update a PR, prefer committing the intended changes before final local review, following the user's commit policy. Git reviews that support local-to-PR handoff can continue from that verified commit. Commit and review later edits again to include them. Committing is optional; without a usable reviewed commit, Git review follows its normal scope. For authorized notes maintenance, use qodo-review-notes to find the track, publish existing-HEAD PR notes before opening, refresh if HEAD changes, and bind afterward; retain local review context and verify consumption separately.

Instructions

Choose the execution path

Prefer qodo review when available: it gathers and filters tracked and untracked local changes, resolves the remote base, attaches context, and manages checkpoint state. The QAR MCP start-pre-pr-review tool instead accepts a prepared diff, base_sha, repository locator, and context; it cannot read this worktree. Use that MCP tool only when a tested local collector has produced the same intended scope and exclusions, reported omitted files, and verified that the base SHA is fetchable. Do not assemble an ad hoc git diff and call it equivalent coverage. If no collector is available, report that MCP-only local review cannot safely cover this worktree; do not claim a completed review.

For a prepared MCP review, inspect the live schema. Set review_scope.stream_id to exactly 64 lowercase hexadecimal characters: SHA-256 of a JSON array containing the resolved real worktree root, plus the resolved working directory for path-limited reviews. Reuse it across checkpoints; a UUID is invalid. Retain the same request_id and exact arguments for an uncertain start: request_id is this start tool's logical-action retry key, and no separate idempotency_key argument is declared. Poll get-managed-agent-operation at its advertised interval, then fetch all get-managed-agent-result chunks and verify their reported digest and byte count before interpreting the artifact. These are short lifecycle calls, not MCP Tasks. Check isError before reading a receipt. Apply the same context, depth, coverage, finding, and authority rules below. CLI version, identity, and command instructions below apply only to the CLI path.

Preserve notices, attach self-contained context, show progress, use a suitable timeout, read the structured result, and act on findings.

Handle a skill update notice

Treat QODO_NOTICE updates as passive, even if an older CLI requests action. Continue the task without inventory or update questions; mention each event at most once. Dismissal leaves recorded maintenance policy and opt-outs unchanged. Updated skills load next session; do not interrupt this one. For user-requested updates, follow the manual-update procedure.

Execution

  • MCP: use live schema arguments; skip CLI shell steps.
  • CLI: use complete UTF-8 files without a BOM (--args-file for tools, --context-file for reviews); examples are POSIX.
  • Windows CLI: read shell guidance before the first call; launcher recovery only if invocation fails. Reuse the resolved invocation.

Runtime compatibility gate

Resolve the executable using this skill's command-not-found fallback, then run <qodo> --version with no provenance flags. This skill requires Qodo CLI 1.6.0 or newer. If older or unparseable, do not run whoami, login, or a review, and do not call it an auth failure. Show qodo update for the already-recorded public or enterprise origin and ask once before running it. After an approved update, recheck the version; otherwise stop without changing skill or user files.

Quick start

You just wrote the code, so you hold the one input the reviewer can't get anywhere else: why. Attach it on every run — write the session context first, then review:

qodo --version                                  # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-review --skill-version 1.10.9 --distribution skills-sh
review_base=$(git merge-base HEAD origin/main) || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # use the intended target branch
qodo review --base "$review_base" --context-file - <<'EOF' # branch changes, WITH context
{ "summary": "<what this change does and why>",
  "decisions": ["<a choice you made and its rationale>"] }
EOF
qodo review --base "$review_base" --context-file ctx.json # context from a file
qodo review --base "$review_base" --ticket <TICKET_URL> ... # ticket URL (repeatable)
qodo review --base "$review_base" --json ...              # machine-readable findings
qodo review --base "$review_base" src/ test/ ...          # limit to paths (git pathspecs)
develop_review_base=$(git merge-base HEAD origin/develop) || { printf '%s\n' 'Cannot resolve merge base for origin/develop; fetch missing history or choose the correct target.' >&2; exit 1; } # another target branch
qodo review --base "$develop_review_base" --json --context-file ctx.json # another target branch
qodo review --base "$review_base" --fast --async --json --context-file ctx.json # checkpoint
qodo review --base "$review_base" --json --context-file ctx.json      # final: auto
qodo review --base "$review_base" --deep --json --context-file ctx.json # justified deep review
qodo review --base "$review_base" # no context only when there is truly nothing to say
qodo review status <operation-id>            # collect an --async result (exit 2 = still running)
qodo review --help                           # exact flags (renders offline)

You can also keep .qodo/session-context.json (same JSON shape) updated at the repo root — it is auto-attached to every run, so even a bare qodo review carries your context. An explicit --context-file overrides it; the file itself is never part of the reviewed diff. Don't commit it (add .qodo/ to .gitignore or .git/info/exclude). Add --json to anything you parse. For connected execution, allow a multi-minute timeout or background the process; async submission and status collection are separate short calls. Confirm the exact flags with qodo review --help (offline) — the examples here are illustrative.

Choose execution for the selected review

Use --async for coding checkpoints: submit, continue useful work, then collect with review status. For a final review, async is also valid, but collect and assess it before the handoff. If live progress is useful, read connected progress and use --json --progress with a host-native background process. Never combine --progress with --async. A review can take minutes; keep a connected process alive or use async so client exit cannot cancel it. If async is unavailable in the installed CLI, keep the selected depth and use the connected fallback.

For connected progress, the canonical execution rules are:

  • Attach context through a file; stdin heredocs are unsuitable for background execution.
  • Use a unique per-run temporary directory. Separate the single result JSON on stdout from NDJSON progress on stderr. Poll the growing progress file through the host's nonblocking process tools; never run a foreground tail that blocks the agent until completion.
  • Relay short status messages, not raw JSON or model output. Translate events by kind: cli.status gives a readable message; tool.activity gives tool name and outcome; task.delta and unknown kinds are occasional generic heartbeats, not one message per event.
  • For qar.client.reconnecting, relay attempt/delay and structured close/error codes when present. qar.client.reconnected means transport opened; resubscribeAttempts counts reattached live tasks. qar.client.reconnect_failed signals exhausted retries, not the final error explanation.
  • On task.done, inspect payload.status; on failure/cancellation or error, stop progress relay but keep waiting for process exit. Always read the result envelope, including on nonzero exit: actionable messages/hints such as closed_preview may appear only there. Progress is not findings.
  • Capture the process exit status, reap the child and disarm its PID before parsing. On interruption, terminate and reap the active child. Clean up only that run's directory on exit/failure/interruption; never reuse or remove a shared .qodo/review.* path.
  • If background progress is unavailable, run foreground with a multi-minute timeout, preserving selected depth and context. Missing progress is not a reason to fail review or downgrade depth.

qodo: command not found? On POSIX retry "${QODO_HOME:-$HOME/.qodo}/bin/qodo"; on Windows follow the linked guide. Keep the resolved invocation; report unusable launchers. For missing installs, obtain Qodo's or the administrator's checksum-pinned installer; never invent a digest or pipe scripts into a shell.

Sandbox auth diagnostic. Missing credentials can mean inaccessible keychain access. When that is plausible, request one exact read-only qodo read whoami retry through the host's approval flow before recommending login. Stop on denial; that approval covers no other command. Reuse a successful check in the same executable/workspace/deployment and execution context; request each required host approval. Network, TLS, service, and explicit authorization failures retain their own diagnosis, not a login recommendation or an automatic sandbox bypass.

Submit and collect with --async

Check support with qodo review --help. The following example submits a coding checkpoint. For final review omit --fast; add --deep only under the selection policy above. Attach the same context in all modes. Shell snippets illustrate the CLI protocol; use the host's own nonblocking wait mechanism.

--async removes the connection from the critical path. It submits the review over HTTP, prints an operation id, and exits 0 immediately. The run continues server-side whether or not your process is alive; you collect the result later with qodo review status <operation-id>.

command -v jq >/dev/null 2>&1 || { printf '%s\n' 'This async recipe requires jq; install it or use the live qodo review flow.' >&2; exit 1; }
QODO_REVIEW_CONTEXT="${QODO_REVIEW_CONTEXT:-.qodo/session-context.json}"
[ -f "$QODO_REVIEW_CONTEXT" ] || { printf '%s\n' "Write the required review context to $QODO_REVIEW_CONTEXT (or set QODO_REVIEW_CONTEXT to its path)." >&2; exit 1; }
QODO_REVIEW_BASE="$(git merge-base HEAD origin/main)" || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # substitute the intended target
if ! submission="$(qodo review --base "$QODO_REVIEW_BASE" --context-file "$QODO_REVIEW_CONTEXT" --async --json --fast)"; then printf '%s\n' "$submission" >&2; exit 1; fi
if ! id="$(printf '%s\n' "$submission" | jq -er '.operation_id | select(type == "string" and length > 0)')"; then printf '%s\n' "$submission" >&2; exit 1; fi
qodo review status "$id" --json                                # collect it

Poll the existing operation until it finishes; do useful work between status checks. Submission exit 0 means accepted, not reviewed. Collection uses these exit codes; read any returned retry delay:

Exit Meaning Do
0 Finished. Findings rendered — identical output to a live run ({findings, meta} under --json). Act on the findings as usual.
2 Still running or polling throttled. Respect retry_after when present, then poll the same ID.
1 Failed, canceled, expired, or no such operation. Read the error envelope. Follow the bounded recovery below; never assume clean. 
# This collection attempt returns failures to the host for classification under Recover a review.
# On nonzero exit, preserve the operation ID and emitted error; apply bounded recovery there.
QODO_REVIEW_TMP="$(mktemp -d "${TMPDIR:-/tmp}/qodo-review.XXXXXX")"
cleanup_qodo_review() { [ -n "${QODO_REVIEW_TMP:-}" ] && [ -d "$QODO_REVIEW_TMP" ] && rm -r -- "$QODO_REVIEW_TMP"; }
trap cleanup_qodo_review EXIT; trap 'exit 130' INT; trap 'exit 143' TERM
while :; do
  status=0; qodo review status "$id" --json > "$QODO_REVIEW_TMP/result.json" || status=$?
  case "$status" in
    0) cat "$QODO_REVIEW_TMP/result.json" || exit 1; break ;;
    2) delay=$(jq -r 'if (.retry_after | type) == "number" and .retry_after > 0 then .retry_after else 15 end' "$QODO_REVIEW_TMP/result.json") || exit 1
       sleep "$delay" ;;
    *) cat "$QODO_REVIEW_TMP/result.json" >&2; exit "$status" ;;
  esac
done

What it costs — know these before you choose it:

  • No streaming progress. There are no progress events on this path — the run isn't attached to your process — so --async and --progress are rejected together rather than emitting a stream that never arrives. There is no intermediate status beyond "still running". If the user is watching and wants to see life, use the connected progress recipe instead.
  • No human-in-the-loop. This surface runs deterministic agents only; a review that asks for input fails instead of waiting. (qodo review status says so and tells you to re-run without --async.)
  • The result is kept for 1 hour after the review finishes, then it is discarded. Collect it inside that window. Past it, qodo review status cannot tell "expired" from "never existed" or "belongs to someone else" — the runtime answers all three identically, on purpose — so it reports all of them. Report the missing review evidence before deciding whether a new run is needed.
  • Do not assume a new submission is free or deduplicated. Use review status to collect an accepted run. If admission is uncertain, follow the CLI's returned recovery command (on versions that support it, --async --retry-submission <id>); never substitute a fresh qodo review to poll. Preserve the retained request during recovery instead of gathering the changing working tree again.
  • Retain the operation id. It identifies the accepted run; a submission-recovery ID has a different purpose. Do not throw away either handle before collecting or reconciling its outcome.

The operation id is not the trace id. qodo prints a trace <id> line on failures — that's an OpenTelemetry id for support to diagnose a run with, and it cannot fetch anything. The operation_id from --async is the resumable handle. Don't pass one where the other is wanted.

Preflight

  1. Auth and catalog. Run qodo read whoami unless a successful check still covers this execution context. After the sandbox diagnostic when applicable, only explicit missing credentials call for login: preserve the organization's exact login command/endpoint, never guess or switch a customer deployment to Cloud. No tool catalog cached is not proof of missing credentials; refresh once with qodo tools --refresh and retry the check. Other failures retain their error and stop this workflow. After identity succeeds, an unknown managed command permits one catalog refresh and schema recheck. If still absent or tool_unavailable, report the missing capability; do not repeat login or refresh. An unknown built-in qodo review needs runtime recovery, not login or catalog refresh.
  2. Resolve the base. Select the intended target (origin/main unless the change targets another branch). Fetch that target before reviewing current remote history; if unavailable or deliberately offline/pinned, disclose that the review uses locally fetched history rather than claim it is current. Compute git merge-base HEAD <target-ref> and pass that SHA as --base on every submission, including checkpoints and connected runs. This also protects older CLIs whose default compares the target tip. An explicit --base is exact; passing the target branch itself can misattribute newer target-only changes. Honor a user-requested exact comparison. If no common ancestor is available, fetch missing history or report the blocker; never fall back silently to the target tip. The base must be pushed; review authority does not allow a push. Local edits and untracked files are included without committing or pushing them.
  3. Write your context. Before running, capture the session narrative — a 2–3 sentence summary of what you changed and why, plus the decisions you made along the way — as the context JSON (stdin heredoc, a file, or .qodo/session-context.json). You always have this: you just wrote the code. Run bare only when there is genuinely nothing to say.

What gets reviewed

qodo review gathers, all client-side:

  • The tracked diff vs the base, plus new/untracked files (secrets, binaries, oversized, and gitignored files are filtered out and reported — never silently dropped).
  • The branch name, HEAD commit, and a description synthesized from your commit messages.
  • Any ticket refs and session context you attach (below).

--json returns findings from this call, with optional meta and finding_state on newer engines. For repeated reviews, read finding_state.introduced and .still_open; an empty findings array alone does not mean clean. .resolved records detected fixes; .dismissed preserves dismissals. If finding_state.complete or meta.coverage.complete is false, report the incomplete coverage.

meta.analysis.mode is full, incremental, or reused. Reused means the same reviewed snapshot and compatible context; earlier open findings remain open. The CLI privately saves the submitted patch. It advances its checkpoint after collecting an eligible result, including via review status. Failed or older completions cannot replace a newer checkpoint. Keep the same base, path scope, requested depth mode and context during a fix loop. Changed context, expired or unverifiable checkpoints, and unsupported deltas fall back to full review. Never fabricate a checkpoint. For a deliberately fresh assessment use --full (confirm support with --help). It controls scope, not depth; it is not needed on every fix. Changing the requested depth mode invalidates compatible checkpoint coverage. Auto does not promise a fixed effective tier; rely on returned analysis/coverage. Older engines omit these fields: use their findings and coverage without claiming reuse. meta.reviewers.ran / .skipped, meta.depth, and meta.safety_net.reinjected describe coverage. A reused result has no new reviewer execution. Attach missing input for a material skipped dimension. Never remove context merely to make an incremental checkpoint eligible.

Attach coding-session context (this is the point)

Attach the intent and decisions behind your change. Three channels:

  • --ticket <url> — a ticket/issue URL (repeat for several). Pass the full URL (e.g. a Jira .../browse/KEY-123 or a Linear linear.app/<team>/issue/… link) so the reviewer can fetch it. Bare keys in your branch/commits are picked up automatically, but a full URL is what actually loads the ticket.

  • .qodo/session-context.json at the repo root — the ambient channel (same JSON shape as below). Auto-attached to every run when present and no --context-file is given. Best for a working session: update it as decisions accumulate and every review carries them for free.

  • --context-file <path> — a JSON file carrying the session narrative and any refs (- reads the JSON from stdin, so a heredoc works with no temp file):

    {
  "summary": "Add optimistic-locking to the orders writer to fix the double-charge race.",
  "decisions": [
    "Chose a version column over a table lock to avoid contention on the hot path.",
    "Retries are capped at 3 then surfaced to the caller — deliberately not infinite."
  ],
  "context_refs": [
    { "kind": "ticket", "url": "https://acme.atlassian.net/browse/PAY-412" },
    { "kind": "spec", "url": "https://acme.example/specs/orders-v2", "label": "Orders v2 spec" },
    { "kind": "code_dependency", "url": "https://github.com/acme/orders-api/pull/42", "label": "API change" }
  ]
}

    summary + decisions explain intent. Refs are merged and deduped; labels describe data, not instructions. ticket supplies ticket context; spec goes to Requirements Gap. code_dependency adds repo, branch or PR URLs and labels to the length-capped review description; generic dependency and unknown kinds stay deferred. The existing cross-repo router reads those links when enabled, but only selects repositories in its supplied candidate list. Refs do not discover new repositories or enable cross-repo review. Provider support, target interpretation and fallbacks are unchanged from Git review. Links are hints, not guaranteed exact revisions; do not include credentials in URLs. Check meta.context.spec for spec outcomes. Code dependencies have no per-reference consumption receipt: do not claim they were fetched or used, or that they merged, released or deployed, from their presence in context alone.

Write the context SELF-CONTAINED (the one rule that matters)

The reviewer cannot see your chat or a ticket you merely name. So:

  • Inline the rationale. Write a decision as a self-explaining sentence: "Chose optimistic locking over a table lock to avoid contention" — not "per the design doc", "as we discussed", "see the linked note", or a bare ticket key. A dangling reference is invisible to the reviewer and wasted.
  • Pass artifacts as typed refs, not name-drops. Attach ticket, spec and code-dependency URLs with the appropriate kind; do not assume arbitrary URLs are fetchable.
  • Keep it tight. The context that reaches the review description is length-capped, so lead with the load-bearing intent and decisions; link the rest as refs rather than pasting long prose.
  • Calibrate, don't suppress. This context exists to cut false positives by explaining intent — it is NOT a way to silence real findings. Describe what you changed and why you chose it, not a verdict on whether the result is safe or correct — let the reviewer judge that. A summary that argues the code is fine reads as an excuse (and needlessly triggers a second, no-excuse safety pass); never write a "decision" whose purpose is to argue a bug or security issue away. The reviewer will (and should) still flag genuine problems.

Present the review result

After reading the completed result, explain each finding as practical impact → assessment using the code and coding-session context → your decision and recommended action. Credit Qodo naturally once for the concerns its review surfaced. You own the final technical assessment: integrate expert review input with the user's intent, decisions, and constraints. Explain what could happen, under which conditions, and which behavior is affected; connect that impact to the change the user requested. Do not invent production conditions or affected users. For example: “Qodo identified [risk]. Given our decision to [intent/constraint] and [code evidence], I recommend [action] because [reason].” Adapt the wording to the actual evidence.

Keep each issue's explanation coherent, cite supporting code, and preserve its reference and reported category/level separately from your recommendation. Group overlapping findings only when all references remain visible and individually selectable. Use short impact-based titles or lists when useful; no branded headings, emoji banners, slogans, footers, or repeated summaries. Report only known counts and coverage. Lead with material skipped/failed reviewers or incomplete coverage; zero findings alone is not a clean verdict. A complete review with no findings can be one sentence. For gated/failed runs, report the actual limitation rather than a completed result.

Act on the findings

Independently evaluate every finding and own its disposition and rationale: fix a supported issue (your fix may differ from Qodo's suggestion), dismiss an unsupported concern with code evidence, or investigate uncertainty by naming the check needed. A session decision supports dismissal only when the code enforces its assumptions. Keep the tone collaborative and factual; do not routinely qualify Qodo's capability or turn a wrong finding into a broader judgment. Your technical recommendation does not grant permission; apply the user's existing scope below.

Report-only. For an explicit request to review without changes, return the assessment and stop; do not solicit edit approval.

Missing edit authority. If the intended fix scope is ambiguous, use the assessment above for every finding, keeping its [category/level] and your recommendation, then ask in a single prompt which findings to apply. Use whatever the host gives you: a multi-select if it has one (Claude Code's AskUserQuestion, say), otherwise a numbered list and "reply with the numbers to apply". One prompt either way — don't ask per finding. Nothing is pre-selected. Mark which ones you recommend, but the user must actively choose: this prompt is the last thing standing between a finding and an edit, so a bare Enter must apply nothing. Apply only what the user picks (edit as normal, matching the surrounding style); report the rest as skipped with your reason. Do not edit any code before the user has chosen.

Authorized fixes. autofix, an explicit request to fix findings, or existing implementation authority covering the necessary correction permits fixes within that scope. State the assessment and apply supported fixes without asking again. A review-only request grants no edit authority; ask once if the intended scope is ambiguous. Preserve narrower user constraints. Fix authority does not authorize stored dismissals, pushes, or unrelated changes. Report applied and skipped fixes.

When the user explicitly authorizes declining a local finding, follow Record local triage to persist the decision. A conversational "skip" alone is not a stored dismissal and must not be reported as one. On MCP, use the live pr-review-dismiss schema with finding IDs and local_review_id from that completed review, an authorized reason and explanation, and a stable idempotency_key for the batch; read back each stored outcome. The reference's CLI commands apply only to the CLI path.

After a batch of authorized fixes, verify and re-review changed work using the lifecycle policy above. Assess outstanding findings and coverage before calling the result clean; stop an unproductive loop. Commit/push per the user's workflow — ask before pushing unless they've told you to.

Recover a review

For an accepted async run, collect by operation ID. On a status transport error, retry once after the returned delay (or 15 seconds). If collection still fails, preserve the ID and report the gap; never resubmit just to poll. On a terminal failure, correct a recoverable cause and retry once with the same mode and context. Stop on entitlement, auth, permission, rate-limit, or further failure; report expired results and coverage gaps.

On repo_not_connected, MT-REPO-NO-CREDENTIAL, or “could not obtain repository credentials”, inspect origin without exposing URL credentials; an SSH alias may differ from the connected host. Use a known exact repository full_name (self-hosted names may include a host); Codebase Wisdom suggestions do not prove connectivity. Confirm qodo review --help supports --repo. If automatic retries are forbidden, stop and get explicit user approval for the corrected command. Retry the original submission once with --repo <full_name>, preserving all other flags; collect a new async operation ID if applicable. If the identity is uncertain or the retry fails, stop and report; ask an admin to check Git integration rather than assert disconnection.

For connected CLI execution, keep the process alive throughout the review; a killed client can cause server cancellation after a short grace period. If the host cannot sustain it, use async instead of repeated timeouts. Use connected progress to background a connected run while retaining status.

Concurrent reviews can complete independently. For the same owner/repository/branch, only the newest checkpoint run can publish finding updates; an older result may report superseded.

Distinguish a killed client, server cancellation after connection loss, a missing task.done after a dropped stream, and a backend review failed: <detail> response. Read the actual failure and retained-result hint before choosing recovery; do not infer a size or complexity limit from a connection failure.

For the first three, collect any retained result using the CLI's recovery hint before submitting again. If the run is confirmed canceled or unrecoverable, retry at most once with uninterrupted execution and the same selected depth/context. A pending run is not a reason to restart. Further failure means reporting incomplete review, not looping, dropping context or downgrading depth to obtain a result.

If the run is gated: closed preview

qodo review is currently in closed preview — the server rejects runs from organizations that aren't enrolled. A gated run exits non-zero with a stable machine-readable error: --json emits {"error": {"code": "closed_preview", "message": ..., "hint": ...}}; without --json the same message and hint print as prose.

On closed_preview:

  1. Surface the message and hint to the user unchanged (don't paraphrase or truncate; the --json payload carries them verbatim, while the CLI's prose output strips terminal control characters), then
  2. STOP. The gate is an entitlement, not a transient fault — retrying, backing off, watching, or looping cannot succeed until the user's organization is enrolled. Do not re-run qodo review unless the user says enrollment happened (after enrollment, access activates within ~10 minutes; no re-login needed).

Only the review itself is gated — auth (qodo read whoami) and the other qodo commands are unaffected.

Configuration

Use --fast --async --json for coding checkpoints, auto for ordinary final review, and --deep only under the stated exceptions. Use --json --progress for connected progress and the resolved merge-base SHA as --base. Stamp exact skill/version/distribution provenance on the first Qodo call after the unadorned version probe and keep session context out of the reviewed diff.

Error Handling

Read the structured result even after a non-zero command. Preserve closed-preview, cancellation, rate-limit, connection, and tool-loop states; follow the bounded recovery above and never discard context or widen authority merely to obtain a green result.

Guardrails

  • Local scope. Review coding milestones and local work before PR/update or completed-work handoff. Use qodo-review-resolver for findings already posted on a PR; avoid duplicate unchanged reviews.
  • No forge writes. qodo review reads your local diff and returns findings; it never pushes, comments, or opens a PR. Resolving a finding means editing code, not posting anywhere.
  • The base must be pushed; your local work need not be. New/untracked files are reviewed by default; secrets/binaries/oversized/gitignored files are filtered and reported.
  • Don't guess creds or the base — resolve auth first, then pass the intended target's merge-base SHA as --base, unless the user explicitly requests an exact baseline.
  • Collect every run. Background connected runs or use async; preserve recovery handles. A superseded result does not advance the incremental baseline or certify current code.
  • Never strip context to beat the clock. Dropping --context-file doesn't make a run faster — it just buys a worse review. Give it time; choose depth by lifecycle, never by timeout pressure.
  • An MT-TOOL-LOOP or MT-RATE-LIMITED error means stop/back off and change approach, not retry.
  • A closed_preview error means the org isn't enrolled in the preview — surface message + hint to the user and stop; never retry or loop on it (see "If the run is gated" above).

After authorized fixes, report what changed, how it was verified, and what remains with reasons.