Installation & Setup

Relevant source files

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

• README.md
• package.json
• PRODUCT.md
• CLAUDE.md
• studio/package.json
• studio/src/components/SettingsPage.tsx
• studio/public/openapi.yaml

Marginalia is a local automation tool that polls GitLab merge requests (MRs) and executes Claude Code slash commands to perform reviews and triage. The system consists of a Node.js poller and a React-based local web application called the studio. Setup requires configuring local environment variables, establishing a dedicated git worktree for the bot, and ensuring the claude CLI is authenticated with necessary connectors.

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

System Requirements

Before installation, verify your environment meets these criteria:

• Node.js: Version 18 or higher.
• Claude CLI: Installed on your system PATH. You must be logged in via claude login to use GitLab and Atlassian connectors.
• GitLab Token: A personal access token with the api scope for listing MRs.
• Local Repository: A local checkout of the project you intend to review, including an origin remote.
• Operating System: macOS is recommended for optional features like system notifications and the SwiftBar menu icon.

Sources: README.md:82-105, package.json:28-30

Quickstart Installation

You can set up Marginalia using the interactive setup script or manual configuration.

Automated Setup

The automated setup installs dependencies, builds the studio, and prompts for configuration values.

1. Clone the repository and navigate to the directory.
2. Run npm run setup.
3. Provide the GitLab URL, Project ID, Token, and local repository path when prompted.
4. Run npm run doctor to verify the configuration.

Sources: README.md:18-24, package.json:13

Manual Setup

1. Install dependencies: npm install.
2. Create a .env file: cp .env.example .env.
3. Configure variables in .env (see Configuration Variables).
4. Build the studio: npm run studio:build.

Sources: README.md:111-116, package.json:18

Configuration Variables

Marginalia uses environment variables defined in a .env file to manage credentials and local paths.

Variable	Description	Requirement
GITLAB_PROJECT_ID	The numeric ID of the GitLab project.	Required
GITLAB_TOKEN	Personal access token with api scope.	Required
GITLAB_USERNAME	Your GitLab username to identify authored MRs.	Required
REPO_LOCAL_PATH	Absolute path to your local project checkout.	Required
REVIEW_COMMAND	The Claude slash command for reviews (e.g., /review).	Required
TRIAGE_COMMAND	The Claude slash command for triage (e.g., /triage).	Optional
POLL_INTERVAL_MINUTES	Frequency of GitLab polling (default: 5).	Optional
ALLOW_POSTING	Enables the "Add to review" button in the studio.	Optional
ALLOW_PUSH	Enables the "Fixes to push" button for triage.	Optional

Sources: README.md:115-116, README.md:126-128, README.md:267-270, PRODUCT.md:43-45

Architecture & Data Flow

The following diagram illustrates the relationship between the poller, the dedicated worktree, and the studio interface.

Studio Setup & Execution

The studio is the web-based reader for generated reviews. It runs locally and binds to 127.0.0.1.

Commands for Studio Development

If you are modifying the studio, use these scripts:

• npm run studio:install: Installs React dependencies in the studio/ directory.
• npm run studio:build: Compiles the TypeScript/Vite application.
• npm run studio:dev: Starts the Vite development server with hot reloading.
• npm run dev: Starts both the bot poller and the studio development server concurrently.

Sources: package.json:12-21, studio/package.json:6-10

Runtime Configuration

You can adjust polling intervals and author exclusions through the Studio UI. These settings are saved to settings.json and take effect without restarting the bot.

Persistent Operation

To ensure Marginalia runs continuously in the background, use the platform-specific autostart scripts.

macOS (LaunchAgent)

1. Run npm run autostart. This creates a per-user LaunchAgent.
2. Monitor logs: tail -f ~/Library/Logs/marginalia.log.
3. To uninstall: npm run autostart -- --uninstall.

Generic (PM2)

For non-macOS systems, use a process manager like PM2:

1. npm install -g pm2
2. pm2 start poll.mjs --name marginalia
3. pm2 save

Sources: README.md:298-316

Troubleshooting Verification

If the bot fails to produce reports, use the doctor script with dry-run capabilities to debug the Claude CLI execution flow.

# General health check
npm run doctor

# Test the review chain for a specific MR without saving state
npm run doctor -- --dry-run <MR_IID>

Sources: README.md:20-22, README.md:368-375

Marginalia's setup ensures that all AI-driven review logic remains local and under developer control, with no automatic posting to GitLab unless explicitly triggered through the studio's opt-in interface.