Claude CLI Integration
Relevant source files
The following files were used as context for generating this wiki page:
Marginalia integrates with the Claude Code CLI to perform automated, headless code reviews and comment triage on GitLab Merge Requests (MRs). It acts as an orchestrator that polls GitLab for activity, prepares a dedicated git worktree, and executes user-defined Claude slash commands. The integration allows developers to use their own specialized agents and skills while Marginalia handles the infrastructure of execution and report collection.
The system relies on the user being logged into their claude account via the CLI (claude login). This enables the use of GitLab and Atlassian connectors to fetch metadata like MR descriptions and Jira tickets. Marginalia enforces a strict execution contract, ensuring the AI never posts directly to GitLab, instead delivering reports to a local studio for human verification.
Sources: README.md:1-12, PRODUCT.md:16-23
Architecture and Execution Flow
Marginalia executes the Claude CLI in a separate git worktree to avoid interfering with the developer's active branch. The poller monitors the GitLab API and triggers specific commands based on the MR author.
Execution Components
The following diagram illustrates the relationship between the Marginalia poller, the local git environment, and the Claude CLI:
The poller manages the lifecycle of the Claude process, including environment variable sanitization and output capturing.
Sources: README.md:73-86, PRODUCT.md:25-30
Command Types
| Command | Environment Variable | Target | Purpose |
|---|---|---|---|
| Review | REVIEW_COMMAND | Peer MRs | Assesses risk, verifies correctness, and generates a guided tour of changes. |
| Triage | TRIAGE_COMMAND | Own MRs | Analyzes reviewer comments, applies fixes locally, and drafts replies. |
Sources: README.md:4-10, PRODUCT.md:16-20, examples/commands/triage.md:7-11
Integration Contract
Marginalia imposes a strict contract on Claude CLI runs to ensure stability and security. It appends system prompts to every run via the --append-system-prompt flag, explicitly forbidding the AI from posting or pushing to remote repositories.
Output Protocols
The bot attempts to collect the report from the Claude execution in the following order of priority:
- A file named
.marginalia-report.mdin the worktree. - A specific stdout block formatted as
<<<REVIEW_FILE path="...">>> ... <<<END_REVIEW_FILE>>>. - The raw final message from the CLI (if it exceeds 200 characters).
Sources: README.md:28-36, examples/commands/review.md:31-31
Headless Sandbox and Security
Marginalia implements a sandbox (lib/claude-sandbox.mjs) to confine the CLI's capabilities during headless operation:
- Credential Protection: Explicitly strips
ANTHROPIC_API_KEYand other sensitive environment variables before spawning the process. - Git Restrictions: Allows only specific subcommands; forbids
git configandgit push. - File System Access: Confines Bash writes to the bot worktree and specific review directories.
- Network: Restricts network access to the specified GitLab host.
Sources: README.md:52-59, README.md:184-197
Data Processing and Findings
The integration transforms the unstructured Markdown output from Claude into a normalized JSON shape (.marginalia-findings.json). This allows the Marginalia Studio to display metadata like verdicts and risk levels consistently.
Finding Severity Levels
Findings are categorized by severity to help the user prioritize review actions:
- Critical: Security holes, broken builds, or wrong behavior. Blocks the merge.
- Important: Likely bugs or violations of repo-specific rules.
- Suggestion: Optional improvements the author may skip.
- Info: Questions or positive feedback.
Sources: skills/marginalia-review/SKILL.md:43-52, studio/public/openapi.yaml:550-555
Review Triage Logic
For MRs authored by the user, the TRIAGE_COMMAND follows a specific logic flow for handling peer feedback:
Configuration and Environment
The integration is configured primarily through a .env file and the CLI's own configuration files.
| Configuration | Description | Default / Requirement |
|---|---|---|
CLAUDE_BIN | Path to the Claude executable. | claude on PATH |
CLAUDE_EXTRA_ALLOWED_TOOLS | Whitelist for tools otherwise blocked in headless mode. | User-defined |
MR_REVIEW_BOT | Environment variable set to 1 during execution. | Always set |
CLAUDE_SANDBOX | Toggle for the internal sandbox. | true |
Sources: README.md:49-55, README.md:195-197, README.md:29-31
Summary
The Claude CLI integration in Marginalia provides a secure, automated bridge between LLM-based reasoning and the GitLab review workflow. By enforcing a "local-first" execution model with a dedicated worktree and sandbox, it allows teams to automate the tedious aspects of code review—such as risk assessment and comment triage—without sacrificing human control or repository security. The integration's success relies on the normalized findings format, which enables the local Studio to provide a high-density, actionable interface for AI-generated insights.
Sources: PRODUCT.md:22-35, README.md:1-12