Automated Code Review
Relevant source files
The following files were used as context for generating this wiki page:
Automated Code Review in Marginalia is a process where a local poller watches GitLab merge requests (MRs) and executes user-defined Claude Code slash commands to analyze changes. The system functions as a headless runner that collects reports and presents them in a local web-based studio for human verification. It prioritizes local execution and user control, ensuring no automated comments are posted to GitLab without explicit confirmation.
Sources: README.md:1-12, PRODUCT.md:15-22
Architecture and Data Flow
The system operates through three primary components: the poller, the Claude Code CLI, and the Studio. The poller monitors the GitLab API for new commits or comments. When it detects changes, it triggers a background run using a dedicated git worktree to avoid interfering with the developer's active branch.
Review Execution Flow
The following diagram illustrates the sequence of events from detecting a new commit to presenting the review in the Studio:
Review Standards and Risk Assessment
Marginalia follows a specific "Senior Engineer" persona for reviews, focusing on codebase-specific conventions rather than generic style. The review process is divided into distinct phases to ensure accuracy and relevance.
Core Review Principles
- Contextual Knowledge: The reviewer must read the repository's own standards (e.g.,
CLAUDE.md,CONTRIBUTING) and examine neighboring files to understand local patterns before reading the diff. - Verification: Reviewers are instructed to run tests, type checks, and linters on the changed code. Findings must be backed by evidence rather than suspicion.
- Risk Levels: Every review must categorize the risk of the change to determine the necessary depth of verification.
| Risk Level | Criteria |
|---|---|
| Low | Contained changes, well-covered by tests, non-sensitive areas (docs, copy). |
| Medium | Changes behavior in shared code or has meaningful logic with thin tests. |
| High | Touches auth, payments, data migrations, public contracts, or concurrency. |
Sources: skills/marginalia-review/SKILL.md:10-38
Findings and Report Structure
The system normalizes all output into a specific JSON structure termed a "Review Shape." This allows the Studio to provide a consistent interface regardless of which specific command or agent generated the review.
Finding Severities
Findings are categorized by their impact on the merge request:
- Critical: Wrong behavior, security holes, or broken builds. These block the merge.
- Important: Likely bugs or breaches of repository rules.
- Suggestion: Improvements the author may choose to skip.
- Info: Questions or positive feedback.
Sources: skills/marginalia-review/SKILL.md:43-52, studio/public/openapi.yaml:495-505
The Guided Tour
To facilitate quick understanding, reviews are organized into an "overview" and a "tour." The overview provides a "before and after" summary of system behavior. The tour groups files into logical "chapters" based on shared ideas rather than file paths.
Studio Integration and Posting
The Studio acts as a local reader (http://localhost:4477) that presents findings as postable cards. It uses an opt-in model for communication with GitLab.
Posting Logic
If ALLOW_POSTING=true is set in the environment, the Studio displays "Add to review" buttons on findings.
- Draft Creation: Clicking the button creates a private GitLab draft note.
- Bulk Submission: Multiple drafts are published simultaneously using the
draft_notes/bulk_publishAPI to minimize notification noise. - Verdicts: The user can submit the review with a status of
APPROVEorREQUEST_CHANGES.
Sources: README.md:205-220, studio/public/openapi.yaml:155-180, studio/src/lib/api.ts:250-265
Triage for Authors
When a developer reviews their own MRs, the system runs a TRIAGE_COMMAND. This command analyzes peer comments and:
- Applies relevant fixes directly in the local bot worktree.
- Drafts replies for non-relevant or incorrect comments.
- Commits fixes locally to a
marginalia/<branch-slug>branch for the user to push.
Sources: README.md:155-185, examples/commands/triage.md
Conclusion
Automated Code Review in Marginalia transforms raw LLM analysis into a structured, human-in-the-loop workflow. By executing reviews locally and enforcing a strict "verify, don't guess" policy, the system acts as a high-fidelity filter that helps developers understand complex changes and provide high-quality feedback quickly.