MergeWarden

A pull request quietly edited your CLAUDE.md.

In the diff it reads as a documentation tidy-up. That file is what every coding
agent reads before it touches your repository, so the change outlives the pull
request and shows up in nothing anyone reviews afterwards.

MergeWarden leaves one comment when that happens. It closes nothing.

What that actually looks like

This is a real pull request, titled "docs: tidy up the contributor notes", whose
whole diff is one added line in CLAUDE.md.

MergeWarden: NEEDS REVIEW

Why:  This file can change how AI agents behave in future PRs. (CLAUDE.md)
Next: Review the agent instruction/tooling change before merging.

The pull request
and the run that produced it
are public, so you can check the output against the diff yourself.

It works whether or not an agent opened the pull request. That one says
Agent detected: no.

Watched by default: AGENTS.md, CLAUDE.md, GEMINI.md, QWEN.md,
.mcp.json, .cursor/, .codex/, .gemini/,
.github/copilot-instructions.md, claude_desktop_config.json.

How often is this? We scanned 2,204 merged agent-authored pull requests on
public GitHub and 3.9% of them changed a file like this. That is not a daily
event. It is the kind of thing you want to hear about the once it happens rather
than find six weeks later.

Install

One file, .github/workflows/mergewarden.yml:

name: MergeWarden

on:
  pull_request:
    types: [opened, synchronize, reopened, edited, labeled, unlabeled, ready_for_review]

permissions:
  contents: read
  pull-requests: write

jobs:
  mergewarden:
    runs-on: ubuntu-latest
    steps:
      - uses: sjh9714/[email protected]
        with:
          comment: auto

That is the whole setup. There is no checkout step, no build, no config file,
and no token to create: the Action uses the one GitHub already gives the job.
Nothing is blocked from merging until you decide otherwise.

comment: auto is the only option that does anything on a fresh install. It
means MergeWarden stays silent when there is nothing to say, and everything else
goes to the Actions job summary. When it does comment, pushing a fix rewrites
that same comment to PASSED instead of deleting it, so a stale review request
cannot outlive the problem it described.

Pull requests from forks get a read-only token from GitHub, so they are never
commented on.

For a build that cannot change under you, pin the release commit instead of the
tag. MergeWarden does not publish or recommend a mutable v0 tag.

- uses: sjh9714/mergewarden@c32fb900b65708ea7c875b8ec4244c0983343970

What else it checks

Once it is installed, these come with it. Each one is a fact about the diff, not
a judgement about the contributor.

Every finding names the rule, the file, the evidence, and an ID you can quote
when you discuss or dismiss it. The
configuration reference covers turning individual
checks up, down, or off.

What it will not do

It never closes, labels, or merges anything. There is no --close flag, and
a test in this repository asserts there never will be one. A pull request closed
by a bot in error does not get reopened by the person who gave up on it.

If what you want is for the pull requests to stop arriving, this is the wrong
tool and you should look at an auto-closing action instead. MergeWarden is for
deciding yourself, faster.

It also does not judge your code. It has no opinion on style, naming, or whether
a change deserves to be merged, and it infers nothing from how the description is
written.

On what it trusts:

• It does not execute pull-request code, and never checks the branch out.
• It reads your settings from the exact base commit of your branch, never from
  the pull request itself, so a pull request cannot rewrite the rules it is
  judged by.
• It never calls a language model, so the same pull request always produces the
  same report.
• If it cannot see everything it needs, it says so and fails rather than
  reporting a pass it cannot stand behind.

The security model has the boundaries and the known
limits.

Reading a whole queue at once

If pull requests have piled up, triage reads all the open ones and lists only
those with something you would have checked by hand.

This one needs a token, even on a public repository, because it makes one
request per pull request and GitHub allows 60 an hour without one. A
personal access token
with no scopes selected is enough, since nothing here writes.

export GH_TOKEN=github_pat_...
npx --yes [email protected] triage owner/repository

20 open pull request(s) read. 9 have something a maintainer checks by hand.

#6941  update-unmanaged-certificates       no description · template unused
#7227  add-tests                           no linked issue · oversized
#7790  feat/dedup-dynamic-upstreams        no linked issue · template unused

Nothing was closed, labelled, or commented on.

Without a token it tells you what it could not read and exits non-zero, rather
than showing you a queue it only half saw. More on triage.

Documentation

Getting started walks through the first week. The
documentation index has the rest, including the
configuration reference.

Running the agents yourself rather than reviewing their pull requests? The same
engine ships as an MCP server that checks a change
against the scope you gave it, before a pull request exists.

Contributing

pnpm install
pnpm test && pnpm typecheck && pnpm lint && pnpm build && pnpm format:check

Every rule needs a passing fixture, a failing fixture, and a snapshot of what a
person would read. The
good first issues
each name the file to change, the command to verify it, and what done looks
like. See the contribution guide.

简体中文

License

MIT