Background Execution
Relevant source files
The following files were used as context for generating this wiki page:
Background execution in Marginalia refers to the automated polling and processing system that watches GitLab merge requests (MRs) and triggers headless Claude Code commands. This system runs locally on the user's machine, independent of the developer's primary working branch, to provide continuous review and triage automation. Sources: README.md:1-15, PRODUCT.md:15-25
The core of this system is a Node.js poller that manages git worktrees, executes slash commands, and serializes reports for consumption by the local studio. It ensures that reviews are generated automatically as new code is pushed, without requiring manual intervention from the developer. Sources: README.md:120-130, PRODUCT.md:27-35
Polling Mechanism
The background system operates on a configurable interval to synchronize local state with the GitLab repository. It specifically targets open MRs and filters them based on author, activity, and target branches. Sources: README.md:132-150
Poll Lifecycle
The poller follows a sequential lifecycle to prevent overlapping executions. The next poll is scheduled only after the previous one finishes. Sources: README.md:365-370
The diagram shows the iterative polling loop and the decision gate for triggering new reviews.
Sources: README.md:132-160, poll.mjs
State Tracking
To avoid redundant processing, the system maintains a state.json file at the project root. It tracks the last reviewed SHA for MRs authored by others and the last peer-comment timestamp for the user's own MRs. Sources: README.md:195-200, README.md:238-242
Headless Command Execution
When changes are detected, the poller spawns the claude CLI in a dedicated git worktree. This prevents the bot from interfering with the user's active development branch. Sources: README.md:6-12, PRODUCT.md:27-30
Execution Environment
The system configures a specific environment for the headless runs:
- Worktree: Created at
BOT_WORKTREE_DIRusing a detached head or specific branch strategy. Sources: README.md:152-162 - Sandboxing: Confines Bash execution, restricts network access to the GitLab host, and denies access to sensitive local files like
~/.ssh. Sources: README.md:386-395 - Authentication: Uses the user's local
claude loginand a GitLab token withapiscope. Sources: README.md:100-115
Command Types
The system alternates between two primary background tasks based on the MR author. Sources: README.md:164-210
| Command Type | Trigger Condition | Source File Variable | Description |
|---|---|---|---|
| Review | MR authored by others | REVIEW_COMMAND | Assesses risk and verifies correctness of new code. |
| Triage | New peer comment on user's MR | TRIAGE_COMMAND | Analyzes feedback and applies local fixes. |
Sources: README.md:52-60, README.md:164-180, README.md:212-220
Bot Status and Persistence
The background process communicates its live status to the local studio via status.json. This file acts as a bridge, allowing the web UI to display progress without direct process inter-communication. Sources: README.md:342-350, studio/public/openapi.yaml:570-580
Status Data Model
The BotStatus structure tracks the active phase and progress of background tasks. Sources: studio/src/lib/api.ts:122-132
| Field | Type | Description |
|---|---|---|
pid | Number | The process ID of the Node.js poller. |
phase | Enum | Current state: idle, polling, reviewing, error, or stopped. |
current | Object | Metadata about the MR currently being processed (IID, title, start time). |
nextPollAt | DateTime | Timestamp for the next scheduled background check. |
Sources: studio/public/openapi.yaml:575-595, studio/src/lib/api.ts:122-130
Automation and Management
The system supports various methods for maintaining continuous execution across machine restarts. Sources: README.md:305-325
- macOS LaunchAgent: Configured via
npm run autostart. It preserves the user'sPATHto ensure CLI tools likeclauderemain accessible. Sources: README.md:307-315 - PM2: A recommended alternative for general process management and log rotation. Sources: README.md:326-335
- SwiftBar Integration: Provides a macOS menu bar icon that reflects the live status from
status.json. Sources: README.md:342-360
The sequence illustrates the flow from process initiation to report generation.
Sources: README.md:132-150, README.md:165-175
Conclusion
Background execution provides the foundation for Marginalia's "Reading Desk" philosophy by ensuring that technical reviews and triage reports are ready before the developer even opens the studio. By isolating execution in a dedicated worktree and sandboxing the Claude CLI, the system maintains security and development flow while providing automated insights into the codebase. Sources: PRODUCT.md:40-50, README.md:386-400