agent-gates

Gate your agents' work and save them round trips. A coding agent excuses a workaround in a comment, writes a commit message nobody can scan, commits unformatted code, pastes a key into a file, or pulls a GitHub action by a tag that can move, and a reviewer reading the diff tends to accept it. agent-gates installs git hooks that refuse such a commit locally, for every contributor, and GitHub workflows that refuse a bad subject, an added comment, an added secret or an unpinned action again in CI, or the hooks alone where CI minutes cost money. It judges the commit only, and leaves how an agent works, and what it records, to other tools.

• agent-gates install writes the gates into the project, which commits them, so contributors and CI are gated without installing agent-gates.
• agent-gates doctor judges their health.
• An optional Claude Code plugin formats each edit, shows the agent the comments the edit added and stops it skipping the gates; the gates hold without it.

Install

Install the agent-gates command for macOS on Apple silicon or Linux on x64 through one of these channels.

With the release's installer:

curl -fsSL https://github.com/cniska/agent-gates/releases/latest/download/install.sh | sh

With Homebrew:

brew install cniska/tap/agent-gates

With npm:

npm install -g @cniska/agent-gates

With Bun:

bun add -g @cniska/agent-gates

The curl line installs ~/.local/bin/agent-gates and, when that directory is not on your PATH, adds it to ~/.zshrc for zsh or to an existing ~/.bashrc or ~/.bash_profile for bash, and otherwise asks you to add it. Each channel updates the way it installed: brew upgrade agent-gates, npm update -g @cniska/agent-gates, bun update -g @cniska/agent-gates, or the curl line run again.

Updates

Installed through a channel, agent-gates asks that channel for its latest release at most once a day, giving up after a second. While a newer release is out, every command prints one line on stderr, leaving its stdout and exit status alone:

agent-gates 0.9.1 is out (running 0.9.0): run brew upgrade agent-gates; if you cannot, tell the user.

The line names the channel's own update command. Set AGENT_GATES_NO_UPDATE_CHECK to any value to turn the check and the line off; neither runs when CI is set, nor from a checkout or a binary placed by hand. The check keeps its state in $XDG_STATE_HOME/agent-gates/, by default ~/.local/state/agent-gates/.

Gate a project

In the project you want to gate, install each gate on its own line:

agent-gates install commit-subject
agent-gates install no-comments
agent-gates install format --command "npm run lint:fix"
agent-gates install no-secrets
agent-gates install pinned-actions
agent-gates doctor

Each install takes one gate and also updates every gate already installed. no-comments installs the gate for each language the project's tracked files hold. format needs the project's own format command.

Install gives every repository the hooks and the gates' workflows, whatever its visibility: a workflow also judges contributors who never installed the hooks. A project whose GitHub Actions minutes are billed, and where a workflow only repeats what the hooks already judged before the push, opts out. Add --workflows off to any gate that has a workflow to install the hooks alone, such as agent-gates install commit-subject --workflows off. The project records the choice, later installs keep it and remove the gates' workflows already there, and agent-gates install --workflows on brings them back (hooks without workflows).

Then, once per machine, install the Claude Code plugin:

claude plugin marketplace add cniska/agent-skills
claude plugin install cniska-gates@cniska

The plugin acts only in a checkout with the gates installed.

Gates

Each gate refuses on commit, and commit-subject, no-comments, no-secrets and pinned-actions also on push and, unless the project turns its workflows off, again in CI. format never runs in CI: it formats, so it runs where code is written, and the project's own check refuses unformatted code there. Each no-comments gate also refuses every added doc comment, suppression, formatter hint, tool setting and test expectation; only a first-line interpreter line and the comments a project lists in .no-comments-keep are kept.

Claude Code plugin

The optional plugin tells the agent at session start which gates the checkout installs and how each refuses, formats each edit with the format gate's command, shows the agent the comments the edit added, and blocks a git command that skips the gates: git commit or git push with --no-verify, git commit -n, and core.hooksPath set or unset to anything but .githooks. The block holds only for a Claude Code agent with the plugin installed.

Docs

• Gates: the files install writes, how the hooks run, and the commit-subject and format gates in detail.
• No comments: what the no-comments gates judge, the refusal, the comments a project keeps and how each is read.
• No secrets: what the no-secrets gate judges, its rules, the refusal and how a reviewed false positive is allowed.
• Pinned actions: what the pinned-actions gate judges, what passes, and the refusal.
• Commands: install and doctor, their output, and the states of a gate file.
• Claude Code plugin: what the plugin does and how to install it.
• Development: setup, checks, layout and adding a language, for working on this repo.
• Releasing: the release workflow, what a release guarantees and how to check a download, the owner's one-time setup and each release's steps.

Related

agent-gates works on its own in any agent workflow, and is one of the optional add-ons to agent-skills, engineering skills for coding agents. The other add-ons:

• agent-task: task tracking for coding agents, the tasks running, in review and waiting to run
• agent-record: a session record for coding agents, every past session queryable and joined to its commits
• agent-worktree: task worktrees for coding agents, one checkout per task, set up and torn down by the project's own commands