memtrace code-review
Review a GitHub PR, a local diff, or a git ref range with the local, deterministic review engine — and optionally post findings straight to the PR.
Usage#
memtrace code-review --pr <URL> [--post] [--watch] | memtrace code-review --diff <PATH|-> [FLAGS] | memtrace code-review --base <REF> --head <REF> [FLAGS]memtrace code-review reviews a GitHub PR, a local unified diff, or a local git ref range using Memtrace's own deterministic review engine — AST detectors plus a YAML rule pack, with optional graph-backed cross-module checks. Exactly one input mode must be given: --pr, --diff, or --base/--head together. Passing zero or more than one is a hard error before any I/O happens.
There's also a hidden memtrace code-review setup wizard that wires up @memtrace fix this on the machine. It's a completely separate code path, triggered only when the first word after code-review is literally setup — it isn't part of the review flags on this page.
Input modes#
Only GitHub PR mode can publish anything. The two local modes are read-only and CI-friendly.
--pr <URL>
A GitHub PR URL of the form https://github.com/OWNER/REPO/pull/N. Memtrace mints a short-lived GitHub App installation token, fetches the PR metadata and unified diff from api.github.com, and reviews it against your local checkout and local Memtrace graph. This is the only mode --post and --watch are valid with.
--diff <PATH|->
Reviews a unified diff read from a file path, or from stdin when the value is -. No GitHub token broker or network call is made. Output is forced to JSON and dry-run — --post and --watch are rejected outright.
--base <REF> --head <REF>
Local git-range review: Memtrace computes git merge-base(base, head) and diffs merge-base..head in the local repo. Both flags are required together, and — like --diff — output is forced to JSON and dry-run.
Flags#
| Flag | Description |
|---|---|
--post | Publish the findings as a real GitHub PR review (event=COMMENT) via the GitHub App installation token. Only valid with --pr — passing it with --diff or --base/--head is a hard error. |
--watch | After a successful --post, registers a local PR watch (written to ~/.memtrace/pr-watches.json) so memtrace pr can later track the human response — approval, requested changes, merge, or a new push. Also best-effort subscribes a server-side relay for push notifications; if that subscribe fails, it only logs a warning and doesn't fail the command. Only valid with --pr. |
--dry-run | Forces preview-only mode even if --post is present: no GitHub write, no watch registration. |
--json | Emit machine-readable JSON instead of the human-readable report. Already the forced default for --diff and --base/--head modes; only meaningful to set explicitly in --pr mode. |
--max-comments <N> | Cap on returned/posted findings, clamped to 1–30. Default is 8 with --post, 10 otherwise. |
--min-severity <low|medium|high|critical> | Severity floor for findings. Default is medium. |
--graph-mode <strict|off> | strict (default) enables graph-backed cross-module findings when a repo id resolves; off disables them and skips the graph lookup entirely. |
--review-mode <strict|online> | strict (default) keeps only benchmark-safe, high-precision findings. online (also accepts discovery) additionally runs evidence-gated repo-convention/invariant-drift detectors that read the current on-disk file at --repo-root, not just the diff. |
--repo-id <ID> | Memtrace repo id to scope graph-backed checks. Falls back to MEMTRACE_DEFAULT_REPO, then the local repo directory's basename, when graph-mode isn't off. |
--repo-root <PATH> | Local checkout root used for base-file reads, git diff/merge-base, and the working-tree HEAD comparison. Defaults to git rev-parse --show-toplevel; outside a git repo, this flag is required. |
--ignore-finding <path:line:pattern> | Repeatable. Suppresses one specific finding identified by exact path, line, and pattern-id. |
What runs where#
The review analysis itself — AST detectors, the YAML rule pack, graph cross-module checks — always runs entirely locally against your local Memtrace graph and local checkout. Local diff and git-range modes never contact GitHub or any Memtrace cloud service at all.
GitHub PR mode has one real network dependency: it needs a Memtrace auth session (memtrace auth login, or MEMTRACE_LICENSE_KEY) to mint a short-lived GitHub App installation token from the Memtrace cloud token broker. That token is then used directly against api.github.com for PR metadata and the unified diff. The cloud side is a pure token broker — it exchanges your Memtrace session for a scoped GitHub token and never sees your code or the review findings.
Reviewing a PR also never clones or checks out the PR branch. Memtrace reads GitHub's API-provided unified diff and reconstructs base-side file contents with git show <base_sha>:<path> against your local --repo-root — so before/after detectors run against your local working tree, not a fresh checkout of the PR head. If your local HEAD sha differs from the PR's head sha, the command warns to stderr but still runs, using local on-disk file content.
What gets posted#
With --post (and no --dry-run), Memtrace posts one GitHub PR review (event=COMMENT) with one inline comment per finding to the PR. Before posting, findings are filtered down to only lines actually added or changed on the diff's right side, then by your --min-severity floor and any --ignore-finding entries, then truncated to --max-comments.
Memtrace also tracks each posted finding so a re-review can update or skip duplicates instead of posting the same comment again. Posted comments use a verbose What/Evidence/Why/Fix card; dry-run previews and --json output always use a shorter, concise body for the same finding.
Without --post, --pr mode is a pure preview: findings print to the human-readable report and nothing is written to GitHub.
--watch and PR tracking#
After a successful --post --watch, Memtrace writes a watch record (status awaiting_response) to ~/.memtrace/pr-watches.json. From then on, memtrace pr status shows that PR's current state, and memtrace pr sync polls GitHub to refresh it and act on any queued @memtrace comment commands.
Every run — posted or not — also emits one telemetry event (pr_review_completed for --pr, code_review_completed for local modes) recording posted/watch flags and finding counts. The command itself never opens a port; it only attaches to an already-running Memtrace owner process's loopback endpoint if one is reachable.
Gotchas#
Both flags are silently rejected — a hard error, not a no-op — when combined with --diff or --base/--head. Only GitHub PR mode can publish.
Reviewing a PR never clones the PR branch. If your local --repo-root HEAD has drifted from the PR's head sha, you get a warning on stderr — the review still runs, potentially against stale local file content for graph and cross-module checks.
--pr mode requires memtrace auth login or MEMTRACE_LICENSE_KEY because the installation-token broker needs a real Memtrace session token. Local --diff/--base+--head modes need none of this.
online mode's extra detectors read the current on-disk file at --repo-root, not just the diff — results can shift if your working tree has uncommitted changes beyond what's being reviewed.
Examples#
$ memtrace code-review --pr https://github.com/acme/app/pull/123 # Dry-run preview: prints findings to the human-readable report, # publishes nothing to GitHub. $ memtrace code-review --pr https://github.com/acme/app/pull/123 --post --watch # Fetches the PR, reviews it with local Memtrace graph context, # posts inline review comments, and registers a local watch # for human-response tracking (see `memtrace pr`). $ memtrace code-review --diff changes.diff --repo-id app --json # CI-friendly local review of a unified diff file; # always JSON, never contacts GitHub or the auth broker. $ git diff origin/main...HEAD | memtrace code-review --diff - --repo-id app # Pipe a working-tree diff via stdin using '-' as the --diff value. $ memtrace code-review --base origin/main --head HEAD --repo-root . # Local git-range review: computes merge-base(origin/main, HEAD) # and diffs merge-base..HEAD.
See also Code reviewer for the user workflow and offline benchmark, memtrace pr, memtrace govern, and memtrace auth.