Mergen Quick Start

Prompts are not enforcement. Mergen is the inline gate that physically blocks hazardous AI agent actions before they reach your runtime, databases, or cloud infrastructure.

Install the mergen-server package and use the short mergen CLI; mergen-server remains a compatibility alias. IDE agents connect through a Bash/Edit hook, while terminal-only workflows use mergen run -- <command>.

Pilot success condition: Mergen is running on your machine, the local policy gate is intercepting tool calls, and the Agent Blunder Log has at least one entry.

Install

npm install -g mergen-server

Or run without installing:

npx mergen-server

Step 1: Configure and start the runtime (30 seconds)

mergen setup

For a developer workflow that does not modify or depend on an IDE:

mergen setup --terminal
mergen run -- npm test
mergen check -- terraform destroy --auto-approve

run evaluates and executes; check evaluates only. Raw commands typed directly into a shell are not intercepted unless explicitly wrapped this way.

Step 2: Add to your AI IDE

The gate only intercepts calls that pass through Mergen's installed hook. Register it:

# Guided setup: detects your IDE automatically, installs the hook
mergen setup

# Or manually per IDE
mergen setup --ide=claude-code
mergen setup --ide=cursor
mergen setup --ide=windsurf

Restart your IDE after setup.

Cursor and Windsurf are VS Code forks and can install the same Mergen panel that ships to the VS Code Marketplace (via OpenVSX, which is what non-Microsoft forks use). Search "Mergen" in the Extensions panel for live status and one-click account connect, on top of the hook installed above.

Connect an account (optional)

Every decision above (pass, block, hold) runs identically with or without an account. Connecting one only matters for org-wide usage aggregation, seats, paid-plan features (Team seats, the Sync Plane, PR comments), and managing billing/organization at mergen.app/settings.

mergen login

Opens a browser for one-click device approval, the same flow as the "Connect Account" button in the VS Code panel. Already subscribed on another machine? This links the same account to this install, it doesn't create a new one.

Step 3: Verify the gate is intercepting

Ask your AI agent to run a destructive command. The gate should block it before the handler runs:

# In your AI IDE, ask:
"Run: terraform destroy prod"

Expected response from Mergen:

🚫 Tool call blocked by Mergen local policy gate.
Tool: execute_fix
Reason: Local Gate: Destructive command pattern matched.
This action was logged to the Agent Blunder Log (GET /agent-blunders).

Check the Agent Blunder Log:

curl http://127.0.0.1:3000/agent-blunders | jq '{total: .stats.total, byType: .stats.byType}'

If you see "total": 1, the gate is working. Pilot complete.

Step 4: Configure HITL approval for schema mutations

Schema migrations are held (not blocked) until a human approves. Set a webhook URL and any migration command will suspend until you click Approve or Deny:

MERGEN_HITL_WEBHOOK_URL=https://hooks.slack.com/... mergen-server start

In team/cloud mode, also set the externally reachable URL so Slack can POST the callback:

MERGEN_PUBLIC_URL=https://mergen.your-company.com mergen-server start

Test it: ask your agent to run a migration:

"Run: prisma migrate deploy"

Mergen suspends the call and fires the Slack webhook. Your IDE waits. Click Approve and execution resumes. Click Deny and a structured error is returned.

Step 5: Connect your incident data (optional)

Once the gate is running, connect production signals to enable root cause analysis:

# Process watch: wrap any running dev server / service, zero config
mergen watch npm start

# PagerDuty: in PagerDuty, go to Service > Integrations > Webhooks
# URL: https://your-host:3000/webhooks/pagerduty
export MERGEN_PAGERDUTY_SECRET=your-pd-signing-secret

# OpenTelemetry (any language, one env var)
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:3000 node app.js

# Datadog (trace fetch + blame attribution)
export DD_API_KEY=... DD_APP_KEY=...

In your IDE:

"What caused the last incident?"
"Triage the api-service"

Step 6: Shadow mode (30-day trust track record before autopilot)

Before enabling autonomous execution, run in shadow mode. Mergen evaluates every incident, records what it would have done, and posts to Slack, without executing anything:

MERGEN_SHADOW_MODE=true \
MERGEN_SLACK_BOT_TOKEN=xoxb-... \
MERGEN_SLACK_CHANNEL=#incidents \
mergen-server start

After 30 days, pull the shadow report:

curl http://127.0.0.1:3000/shadow-report
# → totalEvaluated, wouldHaveBlocked, corpusMatches

This is the evidence package your CISO needs before you flip the autopilot switch.

Step 7: Build the Override Corpus

Every human override becomes enforcement policy. Two automatic sources:

Slack postmortems: scans your incident channel for override patterns and encodes them:

MERGEN_SLACK_OVERRIDE_LOOP=true mergen-server start

Git ADRs: reads architectural decision records and materialises operational constraints:

MERGEN_GIT_ADR_SYNC=true mergen-server start

Check what's been encoded:

curl http://127.0.0.1:3000/override-corpus | jq '.summary'

After 30–90 days the corpus contains your team's specific enforcement policy (Friday settlement windows, compliance holds, infrastructure constraints), impossible to replicate from a standing start.

Step 8: Enable autopilot (after shadow track record)

MERGEN_AUTOPILOT=true \
MERGEN_SHADOW_MODE=false \
MERGEN_PAGERDUTY_SECRET=... \
mergen-server start

PagerDuty triggers → Mergen analyzes → fixes at ≥85% confidence → validates → posts audit trail to Slack. Every action stays within the policy bounds the gate enforces.

CI/CD Safety Gate

There are two separate CI gates, gating two different things. Use either or both:

Change Authorization Gate: reviews the diff (the one that posts a PR comment)

This is what evaluates a PR against your override corpus, blast-radius, and the Change Authorization Gate's deterministic detectors (secrets, deleted tests, auth-bypass, CI-check removal, permission/config weakening) plus a task-to-diff scope check. It's the bundled composite action.yml, invoked with uses:, not a CLI subcommand. mergen ci is a server boot smoke test used elsewhere in CI/release pipelines, and does not call this gate, so it can't be substituted in for it:

# .github/workflows/mergen-aeg-gate.yml: reviews the PR diff. Distinct from the
# Command Execution Gate below, which gates a manifest of literal commands.
name: Mergen AEG Gate
on: [pull_request]
permissions:
  pull-requests: write   # required to post the PR comment and apply the review label
  statuses: write        # required for the commit status (branch protection)
jobs:
  gate:
    runs-on: ubuntu-latest
    env:
      MERGEN_SECRET: ${{ secrets.MERGEN_SECRET }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.x

      - name: Start the gate
        run: |
          npm install -g mergen-server
          # Provision the team policy if it's committed in the repo.
          if [ -f .mergen/enterprise-policy.json ]; then
            mkdir -p "$HOME/.mergen"
            cp .mergen/enterprise-policy.json "$HOME/.mergen/enterprise-policy.json"
          fi
          mergen-server start > mergen-server.log 2>&1 &
          for i in $(seq 1 30); do
            curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 && exit 0
            sleep 1
          done
          echo "::error::mergen-server failed to start"; cat mergen-server.log; exit 1

      # Pin to a release tag once one exists (@main tracks the default branch).
      - name: Gate the change
        uses: omertt27/Mergen@main
        with:
          mergen-url: http://127.0.0.1:3000
          mergen-secret: ${{ secrets.MERGEN_SECRET }}
          # Optional: enables the Change Authorization Gate's task-to-diff scope
          # check. Omit both and it's skipped; everything else still runs.
          # Falls back to `Mergen-Task:` / `Mergen-Plan:` trailer lines in the
          # PR body if you'd rather have the agent write them there.
          # task-description: ${{ github.event.pull_request.title }}
          # plan-summary: ''

AI-generated PRs that touch areas your team has historically overridden, or that a deterministic detector flags, or whose diff doesn't match the stated task, get blocked or routed to human review before merge. The action posts a structured PR comment (updated in place on every push, not reposted) with verdict, risk score, and reasons, applies a mergen/needs-human-review label when a human review is required, and sets a mergen/aeg-gate commit status you can require via branch protection ("require status checks to pass before merging"). Full input/output reference is in action.yml's own description: and inputs: blocks.

Command Execution Gate: gates a manifest of literal deploy/infra commands

A separate, narrower mechanism: runs Gate A (the same policy engine your local hook uses) against an exact list of commands you maintain (e.g. terraform apply -auto-approve or a migration script), for teams whose real risk is a specific deploy step, not the PR diff in general. Add a CI step that pipes each command through mergen-server gate-check -- <cmd> after starting the server as in the example above; a non-zero exit means BLOCK/HELD and fails the job.

Policy configuration

The local gate is configured by ~/.mergen/enterprise-policy.json, created automatically on first start. Edit it to add your own rules:

{
  "enabled": true,
  "rules": [
    {
      "id": "no_prod_deploys_friday",
      "name": "Block production deploys on Fridays",
      "action": "block",
      "reason": "No production deploys after 14:00 UTC on Fridays.",
      "conditions": {
        "commands": ["deploy", "helm upgrade", "kubectl apply"],
        "actorType": "ai",
        "daysOfWeek": [5],
        "hourWindow": [14, 24]
      }
    }
  ]
}

Changes are hot-reloaded: no server restart required.

Check integration status

mergen-server doctor

Prints a health report of every integration with exact export commands for anything missing.

Troubleshooting

Questions? Open an issue · Full docs → · Design partner program →