Introduction to Marginalia
Relevant source files
The following files were used as context for generating this wiki page:
Marginalia is a local automation tool and web-based studio that assists developers in reviewing GitLab merge requests (MRs). It functions as a poller that watches for open MRs on a specific GitLab project and executes a user's own Claude Code slash commands in a headless environment. The tool manages a dedicated git worktree to run reviews or triage comments without interfering with the developer's active branch.
The system emphasizes local control and quiet operation. It collects reports generated by AI agents and presents them in a local React-based web application (the Studio). The Studio allows developers to read reviews, assess risks, and optionally post comments or apply triage fixes back to GitLab. Marginalia never posts to GitLab automatically; all external actions require explicit user confirmation.
Sources: README.md:1-12, PRODUCT.md:14-25, PRODUCT.md:38-46
System Architecture
Marginalia consists of two primary components: a Node.js poller and a local web studio. The poller interacts with the GitLab API and the Claude Code CLI. The studio provides a high-contrast interface for reading and managing the generated reports.
The diagram above shows the relationship between local components and external services, highlighting the local-only execution flow.
Sources: README.md:5-15, PRODUCT.md:14-20, package.json:10-20
Core Components and Responsibilities
The Poller
The poller script (poll.mjs) manages the lifecycle of review and triage tasks. It monitors GitLab for activity and initiates Claude Code runs when new commits are detected or new peer comments appear.
- Review Flow: For MRs authored by others, it runs the
REVIEW_COMMAND. - Triage Flow: For MRs authored by the user, it runs the
TRIAGE_COMMANDto process reviewer feedback. - State Management: It maintains
state.jsonto track the last reviewed SHA and comment timestamps.
Sources: README.md:95-105, README.md:118-125
The Studio
The Studio is a React application served locally (default port 4477). It organizes reviews based on urgency and "turn" (e.g., Needs your first review, Returned to you).
| Feature | Description |
|---|---|
| Guided Tour | Presents the review as a series of chapters with associated diffs and findings. |
| Command Palette | Accessible via ⌘K for quick navigation and search. |
| Posting UI | Allows editing and posting "Comment to post" blocks as GitLab draft notes. |
| Fixes Management | Displays triage-applied local commits and allows pushing them to origin. |
Sources: PRODUCT.md:27-36, README.md:146-160, DESIGN.md:144-150
Review Workflow and Data Contract
Marginalia uses an output contract to normalize AI-generated reports into a structured format for the Studio. While it can display any markdown, it provides a richer experience if the report follows a specific JSON or Markdown structure.
Findings Structure
A "Finding" is a discrete point of review. The Studio reads these from .marginalia-findings.json if available, or parses them from specific markdown headings.
The diagram illustrates the data structure used by the Studio to render the review interface.
Sources: README.md:29-50, skills/marginalia-review/SKILL.md:103-125, studio/public/openapi.yaml:370-405
Severity Levels
Findings are categorized by severity to help developers prioritize their reading:
- Critical: Blocks the merge; represents wrong behavior, security holes, or broken builds.
- Important: Likely bugs or violations of repo rules that should be fixed.
- Suggestion: Optional improvements.
- Info: Questions or positive feedback.
Sources: skills/marginalia-review/SKILL.md:46-55
Operating Context and Security
Marginalia runs locally to ensure data privacy and developer control.
- Authentication: It uses the developer's local
claude loginand a GitLab token withapiscope. - Worktree Isolation: The bot uses a dedicated git worktree, ensuring the developer's working directory remains untouched.
- Sandboxing: Claude Code runs are confined. The sandbox restricts filesystem writes to the worktree and review directory, limits network access to the GitLab host, and blocks access to sensitive files like SSH keys or AWS credentials.
- No Autoposting: The bot never writes to GitLab directly. The only exit for data is the
ALLOW_POSTINGorALLOW_PUSHopt-in buttons in the Studio.
Sources: README.md:65-75, README.md:105-110, README.md:225-240, PRODUCT.md:38-42
Design System: "The Reading Desk"
The Studio interface follows a "Reading Desk" design philosophy, prioritizing high density and technical clarity over decorative elements.
- Visual Style: Flat surfaces, thin borders, and graphite neutrals.
- Typography: Uses system sans fonts for interface and prose, and monospaced fonts for code and paths.
- Color as Signal: Blue is reserved strictly for selection, unread states, focus, and primary actions. Status colors (Red for Critical, Green for Approved, Amber for Important) are always paired with icons or text to meet accessibility standards.
Sources: DESIGN.md:88-100, DESIGN.md:120-135
Technical Specifications
| Parameter | Default Value | Description |
|---|---|---|
POLL_INTERVAL_MINUTES | 5 | Frequency of GitLab API polling for new activity. |
STUDIO_PORT | 4477 | The local port where the Studio web app is accessible. |
STALE_AFTER_DAYS | 14 | Ignores MRs with no activity for more than this duration. |
ALLOWED_TARGET_BRANCHES | (empty) | Optional filter to restrict reviews to specific branches (e.g., develop). |
Sources: README.md:85-95, README.md:146-150, studio/public/openapi.yaml:318-325