Configuration

Relevant source files

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

• README.md
• studio/src/components/SettingsPage.tsx
• studio/src/lib/api.ts
• studio/public/openapi.yaml
• DESIGN.md
• PRODUCT.md

Configuration in Marginalia manages how the bot polls GitLab, how it executes review commands, and how the Studio interface displays results. The system uses a multi-layered approach involving environment variables (.env), runtime settings (settings.json), and persistent bot state (state.json).

Sources: README.md:16-25, PRODUCT.md:32-38

Configuration Hierarchy

Marginalia resolves configuration settings using a priority-based hierarchy. Runtime changes made via the Studio UI override default values defined in the environment.

1. Runtime Settings (settings.json): These are applied immediately by the bot without a restart. Users modify these through the Studio Settings page.
2. Environment Variables (.env): These define core credentials, local file paths, and default behavior for the bot.
3. Hardcoded Defaults: The system uses internal defaults if a setting is absent from both settings.json and .env.

Sources: studio/src/components/SettingsPage.tsx:43-46, README.md:144-148

The diagram shows the flow of configuration data from the user interface to the bot poller and external CLI tools.

Environment Variables (.env)

The .env file stores sensitive credentials and fixed paths. You must create this file during setup, typically by copying .env.example.

Required Variables

Variable	Description
GITLAB_PROJECT_ID	The numeric ID or URL-encoded path of the GitLab project.
GITLAB_TOKEN	A GitLab token with api scope for listing MRs.
GITLAB_USERNAME	Your GitLab username used to distinguish between your MRs and others.
REPO_LOCAL_PATH	The local path to the repository being reviewed.
REVIEW_COMMAND	The Claude slash command for reviews (e.g., /review).

Optional and Feature Gates

Variable	Default	Description
ALLOW_POSTING	false	Enables the "Add to review" buttons to post to GitLab.
ALLOW_PUSH	false	Enables the "Fixes to push" feature for triage.
POLL_INTERVAL_MINUTES	5	The default polling frequency.
CLAUDE_SANDBOX	true	Enables path and command confinement for Claude CLI.

Sources: README.md:92-105, README.md:139-143, README.md:214-230

Runtime Settings (settings.json)

Runtime settings control the bot's behavior during a session. Modifying these settings does not require restarting the poll.mjs process.

Setting Parameters

• Poll Interval: Defines how often the bot checks for updated merge requests (1 to 1440 minutes).
• Stale Threshold: Skips merge requests that have seen no activity for a set number of days (1 to 365 days).
• Target Branch Filtering: Limits reviews to specific base branches (e.g., main, develop).
• Author Exclusion: A list of GitLab usernames whose merge requests the bot will never review.

Sources: studio/src/components/SettingsPage.tsx:16-21, studio/src/lib/api.ts:241-246

API Interface

The Studio server exposes a PUT /api/settings endpoint to update these values. Setting a value to null reverts it to the .env default.

This sequence illustrates how runtime updates propagate to the background bot process.

Sources: studio/public/openapi.yaml:126-153, studio/src/lib/api.ts:249-258

Design System Configuration

Marginalia defines its visual identity through a set of tokens in DESIGN.md. These tokens configure the "Reading Desk" experience of the Studio.

Color Tokens (OKLCH)

• Signal Blue: oklch(62.3% 0.214 259.815) - Used for selection, unread dots, and focus.
• Changes Red: oklch(57.7% 0.245 27.325) - Indicates "Request Changes" or critical findings.
• Approved Green: oklch(59.6% 0.145 163.225) - Indicates "Approve" verdicts.
• Graphite Canvas: oklch(14.1% 0.005 285.823) - The primary background color in dark mode.

Typography Rules

• Interface Font: System sans stack for all UI and review text.
• Mono Font: Reserved for code snippets, file paths, and identifiers.
• Hierarchy: Sets specific sizes for Display (1.875rem), Headline (1.5rem), and Body (0.875rem).

Sources: DESIGN.md:5-40, DESIGN.md:90-112

Bot State Management

The bot maintains persistent state in state.json to avoid redundant reviews and track progress.

• Last SHA: The bot stores the last reviewed commit SHA for every MR. It only reruns a review if the head SHA changes.
• Triage State: For MRs authored by the user, the bot tracks the timestamp of the last triaged peer comment (mineComments).
• Stack Information: Tracks relationships between stacked MRs to review them from bottom to top.

Sources: README.md:126-130, README.md:162-170, README.md:188-192

Sandboxing and Tool Configuration

The bot restricts the Claude CLI environment for security.

• Path Confinement: Prevents reading sensitive directories like ~/.ssh or ~/.aws.
• Git Restrictions: Allows only specific subcommands; git push and git config are generally blocked unless ALLOW_PUSH is enabled.
• Extra Tools: Additional tools must be explicitly whitelisted in the CLAUDE_EXTRA_ALLOWED_TOOLS environment variable if they are required by custom skills.

Sources: README.md:278-285, README.md:295-300