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 --no-ide
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: 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.

CI/CD Safety Gate

Gate A (the same policy engine your local IDE hook uses) runs against an exact list of commands you maintain: a deploy step, a migration script, terraform apply -auto-approve. This gates what CI is about to run, not the PR diff.

Add a step that pipes each command through mergen-server gate-check -- <cmd>; a non-zero exit means BLOCK/HELD and fails the job.

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    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

      - name: Gate the deploy command
        run: mergen-server gate-check -- terraform apply -auto-approve

mergen ci is a server boot smoke test used elsewhere in CI/release pipelines. It does not evaluate commands, so it can't be substituted in for gate-check.

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? omer@mergen.app · FAQ →