Merge Gate: a Claude Code merge gate that holds gh pr merge until CI passes
Holds gh pr merge until CI is green and one Codex review has run. PR status line above the prompt, plus /gate.
Permissions
- Reads filesCan read files and list directories on your machine ($.fs.read / list / stat / exists).
- Runs commandsCan run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
- Intercepts tool callsSees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- Adds commands/toolsRegisters new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
- Stores dataKeeps data between sessions in the plugin's private store ($.store.*).
- tested with
- v2.1.310
- last tested
- requires
- Claude Code ≥ 2.1.287
- surfaces
- above-prompt
- source
- Hamza Zafar (hamzafer) (MIT)
Install inside Claude Code:
/plugin install merge-gate --marketplace hamzafer/claude-code-modsWhat does this mod do?
Merge Gate is a community mod by Hamza Zafar (hamzafer), part of his claude-code-mods collection. It is a Claude Code merge gate: when Claude tries to run gh pr merge, the mod first checks that the pull request's CI checks have passed and that one Codex code review has been run for it. If either is missing, the merge is held until you decide.
It adds three things:
- A hold on
gh pr merge. Failing or running CI, or no Codex review, produces a "Merge Gate" question with the optionsHoldandMerge anyway. - A PR line above the prompt, for example
⛙ PR #42 CI ✓ 7 · Codex 1/1 · PR title. CI is red when something fails, yellow while checks run, green otherwise. - A
/gatecommand that prints the PR's CI counts, Codex status and whether it is ready to merge./gate rerunretries the failed GitHub Actions jobs.
It is the author's own workflow, listed in his repo under "My setup (fork and adapt)", so some rules are opinionated. See the Customize section.
Install
The install block above adds the author's marketplace and installs the plugin from it. The mod needs the gh CLI signed in to GitHub for the PR line and the CI check. It needs the codex CLI for the review rule. Restart Claude Code or run /reload-plugins after installing.
$ install merge-gate
Requires Claude Code ≥ 2.1.287
Installs from the author's own marketplace: hamzafer/claude-code-mods
1.One line, inside Claude Code
/plugin install merge-gate --marketplace hamzafer/claude-code-modsPaste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.
2.From your shell
claude plugin marketplace add hamzafer/claude-code-mods claude plugin install merge-gate@claude-code-modsThen run /reload-plugins in any session that is already open.
3.Try it without installing
git clone https://github.com/hamzafer/claude-code-mods claude --plugin-dir ./claude-code-mods/mods/merge-gateLoads the mod for one session only. Nothing is added to your settings.
How it works
The plugin is one function-hooks module, hooks/register.tsx, plus a small helper for stacking bands above the prompt. A tool.call hook on the Bash tool strips quoted text, heredoc bodies and comments from the command, then tests it against three patterns: codex exec, codex review and gh pr merge. For a merge it calls gh pr view and gh pr checks, reads a per-PR Codex counter from the plugin store, and asks if anything is missing:
const missing = [
checks.fail > 0 && `CI has ${checks.fail} failing (${checks.failing.join(', ')})`,
checks.pending > 0 && `CI has ${checks.pending} still running`,
codex === 0 && 'Codex has not reviewed it',
].filter((x): x is string => typeof x === 'string')
if (missing.length === 0) return run()The status band is refreshed in the background at session start, after every main-agent turn and after a Codex review starts. The counter is keyed by the main checkout of the repo and the PR number, so worktrees of one repo share it. It counts a review when it starts, so a review that fails on quota still uses the one pass.
Customize it
There are no settings. The rules live in hooks/register.tsx, so change them in a fork and run it with --plugin-dir:
LUNA(gpt-5.6-luna) is the only model the gate accepts forcodex review. Replace it with the model you use.- The check
done >= 1allows one Codex pass per PR. Raise it for more. codex execis always denied; remove that branch if you want it.
The band position follows a shared order file, bands.json in claude-code-mods/ inside your Claude config folder, if you use the author's other band mods. Without that file the band sits above whatever else is drawn there.
Permissions & safety
We read every file the plugin can load before running it: plugin.json, hooks/hooks.json, register.tsx, bands.ts, the type declarations and the test file (about 400 lines of TypeScript, no bundled or minified code, no binaries, no package.json). We also searched for hidden Unicode and found none. Here is what we found:
- Gates Bash calls. The
tool.callhook can denycodex exec(always),codex review(unless it uses the luna model, the Ollama check passes and no review was counted yet) andgh pr merge(when CI or Codex is missing and you pick Hold). Everything else passes through. This matches the README. The hook has no.catch, whichclaude plugin validatenotes. - Runs commands (
$.process.run):gh pr view,gh pr checks,git rev-parse --git-common-dir,git branch --show-current, and for/gate rerunalsogh run listandgh run rerun <id> --failed. All are argv arrays, not shell strings.gh run rerunchanges state on GitHub, but only when you type/gate rerun. - Reads files outside the project:
~/.codex/config.toml, to refuse a review when the Ollama app has pointed Codex at a local model, and the band order file under your Claude config folder. It also readsHOMEandCLAUDE_CONFIG_DIR. Nothing is written to disk by the plugin besides its own store (the Codex counters) and shared state. - No network, daemons or telemetry in the plugin code. Network traffic is
ghtalking to GitHub with your own login. No secrets are read. - Text aimed at the model. Deny messages are shown to Claude, for example "Stop and ask the user to switch the toggle off. Do not edit the config." They only explain the rule and steer Claude toward the user. The mod does not rewrite prompts or inject context.
- Opinionated rules. The hard-coded
gpt-5.6-lunamodel and the one-review limit are the author's own. Without Codex you will always be asked before a merge. - License: MIT, with a LICENSE file in the repository root.
claude plugin validate passed with one warning: no plugin icon. The author's tests ran with claude plugin test: 16 pass, 0 fail. We did not run the mod against a real GitHub repository. To turn it off, run /plugin disable merge-gate.
- Reads files
- Can read files and list directories on your machine ($.fs.read / list / stat / exists).
- Runs commands
- Can run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
- Intercepts tool calls
- Sees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Changes the UI
- Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- Adds commands/tools
- Registers new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
- Stores data
- Keeps data between sessions in the plugin's private store ($.store.*).
Compatibility & troubleshooting
We loaded the plugin on Claude Code 2.1.310. It uses function hooks, so it needs a build that supports them. If something looks wrong:
- No PR line. The band appears only when
gh pr viewfinds an open PR for the current branch. Checkgh auth statusand that you are on the PR's branch. - Merge goes through with no question. If
ghcannot find the PR (not signed in, no network, a closed PR), the gate lets the command run. codex reviewis denied. Add-c 'model="gpt-5.6-luna"'to the command, or change the model in a fork. A second review of the same PR is denied by design. If the Ollama toggle in the Codex config is on, switch it off./gateis missing. A command name that Claude Code already has is refused, and the plugin starts anyway. Run/reload-plugins.
To check it works, open a branch with a PR, restart Claude Code and look for the ⛙ PR # line above the prompt, then run /gate.
FAQ
- What does the Claude Code merge gate actually block?
- It watches Bash tool calls. When Claude runs gh pr merge, the mod looks up the PR with gh, counts its CI checks and checks whether a Codex review was counted for it. If a check is failing or still running, or Codex has not reviewed the PR, it asks you "Hold" or "Merge anyway". Hold (or no answer) denies the command. If gh cannot find an open PR, the merge goes through untouched.
- Do I need Codex installed?
- Only if you want the merge to pass without a prompt. The gate counts a review only when Claude ran codex review through the Bash tool, so without Codex you will see "Codex 0/1" and get the Hold or Merge anyway question each time. The marketplace entry lists gh and codex as needs.
- Why is codex review refused unless I pass gpt-5.6-luna?
- That is the author's own rule, hard-coded in hooks/register.tsx. A codex review command must set model="gpt-5.6-luna" with -c, and a second review of the same PR is denied. The README says to change the model to yours, so edit the LUNA constant in a fork if you use another one.
- Does Merge Gate send anything over the network?
- The plugin code makes no network calls of its own and has no telemetry. It runs the gh CLI, which talks to GitHub with your existing gh login, and it never sees or stores your token. Any Codex traffic comes from the codex command Claude runs, not from the mod.
- Can Claude get around the gate?
- The gate matches the command text with regular expressions that handle wrappers, quoting, heredocs and a leading cd. It is a guard against mistakes, not a security boundary. A merge done through the GitHub web UI, another tool or an unusual shell construction is not seen, and you can always pick Merge anyway.
# Related mods
cc-pr-tracker
One line per GitHub PR above the Claude Code prompt: merge state, review, required checks, and alerts on change.
- above-prompt
- toast
- Reads files
- Runs commands
- Intercepts tool calls
- Reads your prompts
- Changes the UI
- Adds commands/tools
- Stores data
tested with v2.1.296
FeaturedBlast Radius
Holds rm -r, force pushes and database migrations in Claude Code and shows what they would change before they run.
- pane
- above-prompt
- Runs commands
- Intercepts tool calls
- Changes the UI
tested with v2.1.291
FeaturedBlock Dangerous Commands
Refuses rm -rf /, force-push to main, DROP TABLE, curl | sh and other destructive Bash commands before they run.
- toast
- Intercepts tool calls
- Changes the UI
tested with v2.1.310
More in Git & GitHub, Safety guards.