Code Review & Diff Viewer
Relevant source files
The following files were used as context for generating this wiki page:
The Code Review & Diff Viewer system in Archductor provides a integrated environment for inspecting code changes, managing review comments, and tracking Pull Request (PR) readiness. It bridges the gap between local Git worktrees and GitHub-hosted review threads, allowing users to interact with code changes directly within the workspace context.
This system serves as a control plane where developers and AI agents can collaborate. It supports viewing unified diffs, tracking local todos, adding line-specific review comments, and resolving GitHub review threads. Furthermore, it enables "staging" review context—such as failing checks or unresolved comments—directly into agent sessions to facilitate automated fixes.
Sources: progress.md, crates/gtk-app/src/workspace_command_center.rs:1416-1460
Architecture and Components
The review system is organized into several functional panels within the Workspace Command Center, supported by a core service layer.
Git Review Service
The GitReviewService acts as the primary API for review-related operations, abstracting the underlying WorkspaceStore. It handles the retrieval of PR state, management of local review comments, and the creation of checkpoints.
Key functions include:
pull_request_readiness: Fetches the aggregated status of checks, reviews, and deployments.add_review_comment: Persists a new comment linked to a specific file and line.resolve_review_comment: Marks a local comment as resolved.checkpoint_create: Records a point-in-time snapshot of the workspace.
Sources: crates/core/src/git_review_service.rs:11-66
Diff Visualization
Changes are visualized through unified diffs and a file tree. The system distinguishes between staged, unstaged, and untracked changes, applying specific syntax highlighting (tags) to the text buffer to identify additions, deletions, and hunks.
The diagram shows how diff data from the store is processed and visually categorized using color-coded tags in the GTK text buffer.
Sources: crates/gtk-app/src/workspace_command_center.rs:1360-1414, crates/gtk-app/src/workspace_command_center.rs:1462-1510
Review Management and Threads
Reviewing code involves both local metadata and upstream GitHub data.
Local Review Comments
Users can add comments to specific files and line numbers. These are stored in the local SQLite database and can be "staged" to an AI agent. Staging converts the collection of open comments into a structured prompt, instructing the agent to address the identified issues.
GitHub Review Threads
For workspaces associated with a GitHub PR, the system fetches active review threads. It supports:
- Resolution: Marking a GitHub thread as resolved via GraphQL mutations (triggered through the CLI/archcar).
- Synchronization: Aggregating upstream comments with local review state.
| Feature | Description | File Scope |
|---|---|---|
| Add Comment | Creates a ReviewComment with file path and optional line. | git_review_service.rs |
| Resolve Thread | Reopens or resolves a GitHub thread by ID. | workspace_command_center.rs |
| Stage Prompt | Generates an agent prompt from all open comments. | workspace_command_center.rs |
Sources: crates/gtk-app/src/workspace_command_center.rs:1880-1940, crates/core/src/git_review_service.rs:37-47
PR Readiness and Checks
The "Checks" tab provides a comprehensive rollup of the PR's status. It promotes critical information into an "attention" section to highlight blockers.
Readiness Logic
A PR is considered "ready to merge" only if:
- The GitHub review decision is
APPROVED. - All status checks have passed (no failing or pending checks).
- All deployments are successful.
- There are zero open local todos or review comments.
- There are no conflicting sibling workspaces.
Sources: crates/gtk-app/src/workspace_command_center.rs:1754-1772
Data Flow for PR Summary
The sequence illustrates the aggregation of data from multiple GitHub APIs to form a complete readiness picture.
Sources: crates/gtk-app/src/workspace_command_center.rs:1603-1640, progress.md
Agent Integration (Context Staging)
A unique feature of the viewer is the ability to feed the review state back into the development loop.
Structured Event Parsing
When an AI agent like Codex makes changes, the TUI output is parsed into CodexInlineEvent structures. This includes FileChange events that summarize additions and deletions, which are then rendered as interactive chips in the chat transcript.
pub struct CodexFileChange {
pub action: CodexFileChangeAction,
pub path: String,
pub additions: Option<u32>,
pub deletions: Option<u32>,
pub lines: Vec<CodexFileChangeLine>,
}
Sources: crates/core/src/codex_tui.rs:34-41
Staging Prompts
The system provides buttons to "Queue Prompt" from various review contexts:
- Failing Checks: Stages a prompt containing the logs/details of failing PR checks.
- Review Summary: Stages a high-level summary of the PR's current status.
- Open Comments: Stages a list of all unresolved review items.
Sources: crates/gtk-app/src/workspace_command_center.rs:1810-1850, crates/gtk-app/src/session_surface.rs:1040-1065
Conclusion
The Code Review & Diff Viewer is a central hub for quality control in the Archductor workflow. By combining deep Git integration with GitHub API data and AI agent connectivity, it allows for a seamless transition from identifying issues during review to executing fixes within the same unified interface. This integration ensures that the "Definition of Done" is strictly enforced before code is merged.
Sources: progress.md, crates/gtk-app/src/workspace_command_center.rs:1754-1772