-
Notifications
You must be signed in to change notification settings - Fork 0
Concepts
Drift means the difference between a chosen baseline commit and the current git working tree — uncommitted edits, plus any commits made since the baseline.
The default baseline is HEAD, which scopes drift to uncommitted changes. Other baselines keep drift visible after an agent commits its work.
The baseline is the "before" side of every comparison. In the toolbar this is exposed as Scope:
-
Current work (default): uncommitted drift since the last commit (
HEAD). - Since last review: the commit pinned by the last Mark reviewed — everything since you last trusted the code. This keeps drift visible when an agent commits as it works.
-
Entire branch: the common ancestor with
main/master— everything this branch adds. - Custom ref: any branch, tag, or SHA.
The choice persists per repo via the toolbar's Scope menu. Choices that can't resolve (no trust point yet, no default branch, unknown ref) are rejected with a message; analysis never silently changes baselines.
The trust point is the commit SHA recorded when you click Mark reviewed — the last state of the code you personally trusted. With the trust-point baseline selected, "reviewed" means "reviewed everything since here", and an agent committing its work doesn't hide the drift.
A session is the current analysis result for one opened repo:
- repo name and branch
- baseline (spec and resolved label)
- changed file count
- analyzed files
- active and dismissed flags
- per-node review progress
- reviewed state
Live watcher updates replace the session as files change.
A changed file is any path git reports as different from the baseline, including files Diff Drift can't parse. This count is broader than what gets analyzed.
An analyzed file is a changed source file Diff Drift parsed and rendered as structural (AST) drift — .ts, .tsx, .js, .jsx, .mjs, .cjs, .rs, .go, .py, .pyi, .java, .cs, .kt, .kts, or .swift — plus package.json, which is rendered as a dependency diff when its dependency or script sections changed. Core language structural drift plus package.json dependency/script drift; heuristic flags are strongest for JS/TS and package drift.
A changed path that is not an analyzed file — unsupported file type (Markdown, TOML, YAML, images, etc.) or package.json with no dependency or script drift. These paths are listed by name in the sidebar so they are visible without being analyzed. Review them outside Diff Drift.
A node is a parsed source structure such as an import, function, variable declaration, return statement, guard, or expression — or, for package.json, a dependency or script entry. Node cards show whether that structure was added, modified, removed, or unchanged.
A flag is a heuristic review prompt attached to a changed node. Flags have severity, type, description, file path, node path, and dismissed state.
Flags are not verdicts. They mean "review this change."
Dismissed means the user has decided a flag is not active for this repo's current review. Dismissed flags remain visible in a separate section and can be restored.
Each changed node can be individually marked reviewed. The review pins the node's content hash: if that node's content drifts again afterwards, it automatically reads as unreviewed — that is the "new since last look" signal. Progress (reviewed/changed) shows per file and across the whole drift.
Mark reviewed records three things at once: the drift fingerprint (so any meaningful change clears the reviewed state), the trust point (the current HEAD commit), and a review mark on every changed node.
Export writes the current session as Markdown or JSON. Markdown is for people. JSON is for tooling — it carries a schemaVersion field so consumers can detect contract changes.
diff-drift check [path] runs the same analysis without the GUI and prints the session as JSON (or --md). The exit code is the highest active severity (0 none / 1 low / 2 medium / 3 high), so scripts and agent hooks can gate on it. An explicit --baseline that can't resolve exits 64 with the cause on stderr — never a silent HEAD fallback. It reads the same per-repo triage state as the app and never writes anything.