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 workspace snapshot relative to HEAD, including non-ignored untracked files, as a file and change tree. After a working-tree review is active, Difox watches workspace file changes and automatically refreshes the review to rematch review work and preserve review state when a text hunk or hunkless file-level change can still be identified confidently. Difox: Refresh Working Tree Review remains available as an explicit manual refresh.

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.

After a branch review is active, Difox watches Git metadata changes and automatically refreshes the same stored branch review target after common amend, rebase, or commit updates. Use Difox: Refresh Review from the review panel when you want an explicit refresh; 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. If the stored branch target cannot be resolved safely, such as a detached HEAD review or a missing branch ref, automatic refresh is skipped and reported in the Status view instead of silently rewriting the active review onto another checked-out branch.

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 and command palette, plus lightweight CodeLens entries for per-hunk review and comment actions. These actions let you mark the current text hunk reviewed, add a hunk comment, copy the current cursor location, or move to the next unresolved hunk in the current diff file without returning to the review panel. State-changing hunk actions are resolved from the active Difox diff tab and cursor position, so ordinary editors and unrelated VS Code diffs do not become writable Difox review targets. Difox: Copy Current Location copies compact hunk context when the cursor is inside a known hunk, and falls back to a plain file, line, and source context for unchanged lines in a Difox diff or workspace source editor without changing review state.

Inside the VS Code comment editor, Difox: Copy Comment copies the current draft comment with compact file, clicked-line source, range, and hunk context, then closes the draft without saving it as Difox feedback.

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, automatic-refresh diagnostics, and active review filters 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. Directory and file rows keep native VS Code folder/file icons, including file-type icons, and show review state through scoped status decorations: U for unreviewed work, R for reviewed work, and ! for stale or diagnostic states. Decoration color, badge placement, and final label tint follow VS Code theme and workbench rendering, while descriptions and tooltips explain the state. Hunk rows keep the explicit review-status icon and checkbox language, use compact changed-line range labels, and keep 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 Difox: Review Filters... to scan all changes, test changes only, or non-test changes only, and to show or hide reviewed work. These filters are transient panel visibility state: they do not change persisted review state or reorder the remaining visible items. Unreviewed or stale hunkless file changes stay visible when their file scope matches because they still represent file-level review work; once reviewed, they hide with the rest of reviewed work when reviewed changes are hidden. Cursor sync respects the active filters and does not automatically unhide a filtered row 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: Review Filters...: choose all, test-only, or non-test-only review scanning and show or hide reviewed changes in the review panel.
• Difox: Toggle Reviewed Changes: directly 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: Copy Current Location: copy compact file, line, and source context for the cursor location in a Difox-opened native diff or workspace source file, including hunk context when the cursor line belongs to a review hunk.
• 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: Copy Comment: copy the current draft comment with compact location context and clicked-line source, then close the draft without saving feedback.
• 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.

Manual and automatic 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.