Difox

Difox is a local VS Code extension for reviewing Git changes produced by a local Agent. It keeps review progress in local extension state, lets a developer mark review changes as reviewed or unreviewed, and restores inline review comments from persisted state.

Review Workflows

Working-tree review

Use Difox: Start Working Tree Review to review the current working-tree diff as a file and change tree. Use Difox: Refresh Working Tree Review after later edits to rematch review work and preserve review state when a text hunk or hunkless file-level change can still be identified confidently.

Working-tree review is best for checking the latest local patch before it is committed.

Branch commit review

Use Difox: Start Branch Review from the review panel or command palette, then enter a base ref such as main. Difox resolves the merge-base between that base ref and HEAD, lists commits that are unique to the current branch, and renders them in the review panel as:

branch
commit
file
change

Each commit is reviewed as its own logical commit session. Text-hunk actions and comments are routed by the owning session plus hunk key, so two commits can contain similar hunks without sharing review state.

Use Difox: Open Commit Review from a commit node to make that logical commit the active inline-comment target. Native editor comments are accepted only when Difox can resolve one active commit session; otherwise Difox refuses to guess.

Use Difox: Refresh Review from the review panel after amending or rebasing commits. When branch review is active, this title action refreshes the active branch review. Difox: Refresh Branch Review remains available as the explicit branch-only command. Difox treats commit SHA as current revision metadata, not as durable review identity. Refresh remaps logical commits only by exact SHA, a unique commit-message Change-Id trailer, or a unique stable patch-id. It does not migrate review identity by subject, author, order, touched files, or line numbers alone. If a commit cannot be matched confidently, the old logical commit is kept as missing or ambiguous and the rewritten commit appears as new unreviewed work instead of carrying reviewed state to the wrong commit.

Starting Difox: Start Working Tree Review while branch review is active asks for confirmation before switching the active review surface away from the branch review.

Native diff navigation

Selecting a file or text hunk in the review panel opens a VS Code native diff editor. Selecting a hunk reveals its location and marks the current hunk range with a whole-line editor highlight on the changed side, and on the original side when the hunk also has old-file lines.

Native diff editors opened by Difox keep the review panel and selected-hunk marker aligned while you read through the diff. When the cursor moves inside a known hunk range, the matching hunk row is revealed and selected in the review panel, and the native diff range marker moves to that hunk without moving focus away from the editor. This cursor sync applies to both working-tree and branch commit diffs because they use the same VS Code native diff viewer; it does not apply to ordinary editors or arbitrary VS Code diffs, and the cursor, tree selection, or range marker is not persisted as review state.

Difox-opened native diff editors also expose current-change actions in the editor title, the command palette, and lightweight CodeLens entries near hunk ranges. These actions let you mark the current text hunk reviewed, add a hunk comment, or move to the next unresolved hunk in the current diff file without returning to the review panel. They are resolved from the active Difox diff tab and cursor position, so ordinary editors and unrelated VS Code diffs do not become Difox review targets.

Review feedback export

Use Difox: Export Review Feedback to open an untitled Markdown document with unresolved review feedback for the active review target. Working-tree review exports the current working-tree session. Branch review exports only the active logical commit session selected with Difox: Open Commit Review.

The export includes open comments, file and hunk context, ranges, and diff snippets for Agent follow-up. Stale feedback is listed separately because it needs human confirmation before editing. Resolved comments and uncommented unreviewed hunks are not exported as action items.

Difox panel scanning

Difox contributes its own VS Code view container instead of living inside Explorer. The container is the scan-first action surface for local review and contains a compact status view above the review tree. Users can move the contributed container or views to VS Code's Secondary Sidebar if that fits their layout, but Difox does not force a default Secondary Sidebar placement.

The status view summarizes the active review target, progress, feedback, diagnostics, and focus mode without replacing the review tree. The review tree remains the hierarchy for changed files and review changes. Changed files are grouped into directory rows so larger changesets scan like the workspace file tree. Directory chains with only one child directory are compacted into a single row, such as src/features/review, so deep paths do not add empty clicks. Hunkless file rows use a checkbox to mark file-level work reviewed or unreviewed; files that contain hunks keep review controls on their child hunk rows instead of becoming batch file checkboxes. File and directory rows use status marker icons and colors so unreviewed file-level work stays visible while scanning collapsed folders. Hunk rows use compact changed-line range labels while keeping the raw unified-diff header in tooltips. Review status remains the primary visual signal, and comment counts supplement that status instead of replacing it.

Parent rows summarize the remaining work with aggregate reviewed, unreviewed, stale, and comment counts. Use the hide-reviewed focus mode to temporarily remove reviewed changes and empty parent rows from the panel without changing persisted review state or reordering the remaining visible items. Unreviewed or stale hunkless file changes stay visible because they still represent file-level review work; once reviewed, they hide with the rest of reviewed work. Cursor sync respects this focus mode: a hidden reviewed hunk is not automatically unhidden just because the native diff cursor is inside it.

Commands

• Difox: Start Working Tree Review: start or refresh a working-tree review. If branch review is active, Difox asks before switching the active review surface.
• Difox: Refresh Working Tree Review: refresh the working-tree review.
• Difox: Refresh Review: refresh the current review surface from the review panel title bar: active branch review when branch review is active, otherwise working-tree review.
• Difox: Clear Review: remove the active review after confirmation: branch review context and logical commit sessions when branch review is active; otherwise the working-tree review session.
• Difox: Start Branch Review: start a branch commit review from a base ref.
• Difox: Refresh Branch Review: refresh the active branch commit review.
• Difox: Toggle Reviewed Changes: hide or show reviewed changes in the review panel.
• Difox: Open Commit Review: set a commit node as the active inline-comment target.
• Difox: Open Diff: open a VS Code native diff for a Difox file or hunk.
• Difox: Mark Change Reviewed: mark a review change as reviewed.
• Difox: Mark Current Change Reviewed: mark the text hunk under the cursor in a Difox-opened native diff as reviewed.
• Difox: Add Change Comment: open the hunk location and expand a managed inline comment draft.
• Difox: Add Comment To Current Change: add a managed review comment draft for the hunk under the cursor in a Difox-opened native diff.
• Difox: Next Unresolved Change: move to the next unreviewed, stale, or open-feedback hunk in the current Difox native diff file.
• Difox: Save Comment: persist a VS Code comment reply.
• Difox: Export Review Feedback: open structured Markdown feedback for the active review target.
• Difox: Delete Comment: delete one persisted Difox review comment.
• Difox: Clear Change Feedback: delete all persisted feedback for one hunk.
• Difox: Clear Active Feedback: after confirmation, delete persisted feedback from the active working-tree review or active branch commit session.

Review State

Review state is local to the VS Code extension storage for the workspace. Working-tree reviews and branch commit reviews share the same persisted state document, but branch reviews store a repo-scoped active branch context and per-logical-commit review sessions.

The review state schema may reset during foundation changes. Unsupported old local state is cleared to an empty current document rather than migrated, because Difox review progress is local working data rather than source data.

Review state is intentionally small: reviewed means a change has passed human review, unreviewed means it has not passed review yet, and stale means previous review state is no longer trustworthy after a diff refresh. Hunkless file-level changes store review state separately from text hunk state; comments remain hunk-scoped. Comments carry the explanation for required follow-up changes; they do not create a separate hunk status.

Feedback cleanup changes only persisted comments. Deleting a comment or clearing feedback does not change review status.

Refresh behavior is intentionally conservative:

• matched hunks keep their review state
• hunkless file-level changes keep their review state only when both their file row identity and file-level change identity still match
• changed, missing, or ambiguous hunks become stale
• new hunks become unreviewed
• new hunkless file-level changes become unreviewed
• comments move only through the same preserved hunk mapping; unmapped comments become stale feedback
• branch logical commits remap only by exact SHA, unique commit-message Change-Id, or unique stable patch-id
• missing or ambiguous logical commits stay visible for diagnostics but do not expose writable hunk actions

Known Limitations

• Difox does not integrate with GitHub, GitLab, or pull request review.
• Difox does not implement a whole-branch aggregate range review; branch review is commit-first.
• Difox does not export all branch commits at once; branch export is limited to the active logical commit.
• Merge commits are indexed with first-parent commit diff behavior.
• Review state is local and not synchronized across machines or users.