System Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• PRODUCT.md
• DESIGN.md
• studio/public/openapi.yaml
• skills/marginalia-review/SKILL.md
• package.json

Marginalia is a local automation tool that monitors GitLab merge requests (MRs) and executes user-defined Claude Code slash commands to perform reviews and triage feedback. The system operates entirely on the developer's local machine, ensuring that no sensitive data or tokens are shared with external hosting services.

The architecture consists of two primary components: a Node.js poller that handles background tasks and a React-based web studio for reading reports and interacting with GitLab. It uses a dedicated git worktree to run reviews, which prevents the bot from interfering with the developer's active working branch.

Sources: README.md:1-15, PRODUCT.md:15-25

Component Architecture

The system divides responsibilities between background execution and a local user interface.

The Poller (Backend)

The poller serves as the core engine. It watches GitLab projects, manages the local git worktree, and executes the Claude Code CLI. It maintains local state in JSON files to track reviewed SHAs and triage progress.

The Studio (Frontend)

The studio is a local web application built with React, Vite, and Tailwind CSS. It provides a "reading desk" environment where developers can review machine-generated findings, edit proposed comments, and optionally post them back to GitLab.

The following diagram illustrates the relationship between the local environment, the Claude Code CLI, and GitLab.

Data Flow and Execution

Marginalia implements two distinct flows based on the author of the merge request.

Review Flow (Others' MRs)

When the poller detects an MR authored by a teammate, it triggers the REVIEW_COMMAND. The bot checks out the branch in the dedicated worktree and runs Claude Code to generate a review report.

Triage Flow (Own MRs)

When the poller detects new peer comments on the user's own MR, it triggers the TRIAGE_COMMAND. This command analyzes the comments and may apply local fixes to the bot worktree, which the user can later push from the studio.

Step	Action	Actor
1	Poll GitLab API for open MRs	Poller
2	Compare head SHA with state.json	Poller
3	Checkout branch in BOT_WORKTREE_DIR	Poller
4	Execute Claude Code CLI command	Poller
5	Parse output into .findings.json	Poller
6	Notify user of ready review	Poller

Sources: README.md:85-135, PRODUCT.md:30-45

Studio API and State Management

The studio communicates with a local server (studio/server.mjs) that acts as a proxy for the GitLab API and a reader for local filesystem data.

API Endpoints

The studio API facilitates reading reviews, managing drafts, and updating configuration.

Local Filesystem State

The system relies on several JSON files to maintain persistence without a database:

• state.json: Tracks the last reviewed SHA and triage timestamps.
• status.json: Contains the live progress of the poller (e.g., "polling", "reviewing").
• settings.json: Stores runtime overrides for poll intervals and filters.
• posted.json: Records which findings have already been sent to GitLab.

Sources: README.md:140-160, studio/public/openapi.yaml:380-450

Integration with Claude Code

Marginalia acts as a headless wrapper for Claude Code. It appends specific instructions to each run to ensure the AI follows a strict output contract.

Output Contract

Commands must deliver reports in one of the following formats:

1. A .marginalia-report.md file in the worktree.
2. A markdown block wrapped in <<<REVIEW_FILE>>> markers in stdout.
3. A .marginalia-findings.json file for structured data (recommended).

{
  "verdict": "REQUEST_CHANGES",
  "summary": "One or two sentences.",
  "findings": [
    {
      "id": "finding-1",
      "severity": "critical",
      "title": "Security vulnerability",
      "path": "src/auth.ts",
      "line": 42,
      "body": "Detailed explanation.",
      "comment": "Comment to post to GitLab."
    }
  ]
}

Sources: README.md:35-70, skills/marginalia-review/SKILL.md:130-155

Security and Containment

The architecture prioritizes developer security through local execution and sandboxing.

• Local Execution: No code or tokens leave the machine except via explicit GitLab API calls.
• Sandboxing: The bot builds a configuration that confines bash execution to the worktree and limits network access to the GitLab host.
• Explicit Controls: The bot never posts to GitLab automatically. Users must manually review and click "Submit review" in the studio.
• Environment Isolation: The bot strips ANTHROPIC_API_KEY from the environment to prevent accidental API-key billing, relying on the claude login session instead.

Sources: README.md:210-240, PRODUCT.md:25-35

Conclusion

Marginalia's architecture creates a robust, local-first environment for AI-assisted code reviews. By separating the background polling logic from the high-density reading interface of the studio, it allows developers to integrate machine findings into their workflow without losing control or compromising security. The system's reliance on standard Git mechanisms like worktrees and standard files like JSON ensures it remains lightweight and compatible with existing development environments.