Hooks: before each action, and when the agent finishes
groundrule hooks adds two small hooks to your agent’s project settings. The before-tool hook runs before every tool call and decides it against your action policies: a command, an edit, a read, a fetch or an MCP call is allowed, needs the developer’s confirmation, or is refused with the reason. The stop hook runs every time the agent is about to finish a task: the same check as CI on the agent’s uncommitted changes, and if a blocking finding is left, the agent is told what to fix and carries on. Agent instruction files ask the agent to run the check and the MCP check tool lets it; the hooks make sure it happens.
Add the hooks
Section titled “Add the hooks”Run this in the repository:
npx @groundrule/cli hooksYou should see a line per agent, for example:
✓ Claude Code checks its work when it finishes: .claude/settings.json
Commit this file so everyone's agent runs the check. Remove with `groundrule hooks --remove`.Commit the files, so every developer’s agent runs the check.
By default the command sets up Claude Code, plus Codex and Cursor when the repository already has a .codex or .cursor folder, and Copilot when it has .github/hooks, .github/copilot-instructions.md or .github/instructions. Choose agents with --agents, for example --agents claude-code,copilot.
| Agent | File | Before an action | When the check fails |
|---|---|---|---|
| Claude Code | .claude/settings.json |
Allow, ask or deny, with the reason. The rules for a file ride along before an edit; see Rules before an edit. | The agent is stopped from finishing and told what to fix. |
| Codex | .codex/hooks.json |
Allow or deny. Codex can’t ask, so ask is delivered as deny with the reason. Codex asks each developer to trust the hooks once, with /hooks. |
The same. |
| Cursor | .cursor/hooks.json |
Shell commands, MCP calls and file reads (ask on a read is deny). Cursor has no decision before an edit. |
What to fix is sent to the agent as a follow-up message. |
| GitHub Copilot (CLI and cloud agent) | .github/hooks/groundrule.json |
Allow, ask or deny. The cloud agent treats ask as deny. |
The agent takes another turn with what to fix. |
Without an action policy the before-tool hook answers nothing, so a repository that only uses standards is unchanged. What each agent supports, kind by kind, is in Action policies.
Everything else in those files is kept; the Copilot file is Groundrule’s own, and --remove deletes it. Copilot’s hooks run in the Copilot CLI and the cloud agent (not in VS Code). If you restrict the cloud agent’s firewall, allow registry.npmjs.org, since the hook runs npx. Running the command again changes nothing: “… already has the Groundrule hook”.
Or install the Claude Code plugin
Section titled “Or install the Claude Code plugin”groundrule hooks commits the hooks to the repository, so everyone on the team gets them. A developer who wants them in every repository they open, without changing any of them, can install the Groundrule plugin instead. Inside Claude Code:
/plugin marketplace add Metricall-AI-Lab/groundrule-oss/plugin install groundrule@groundruleThe plugin brings the same two hooks, the MCP server and a skill, and runs the CLI at an exact pinned version. In a repository without .groundrule/ it does nothing. Use the plugin or groundrule hooks in a repository, not both, or the check runs twice.
Anthropic’s plugin directory lists a smaller Groundrule bundle with the skill and two commands, /groundrule:setup and /groundrule:check, and no hooks: the directory accepts hooks and local MCP servers only from organizations it has verified. With that bundle, /groundrule:setup offers to run groundrule hooks for you.
What the agent is told
Section titled “What the agent is told”When the check fails, the agent gets the same report as the MCP check tool: only findings its change introduced, blocking first, each with where and how to fix it.
Groundrule check failed on uncommitted changes: 1 blocking finding. Fix it before you finish, then check again.- SEC-003 No access tokens in code (blocker) at src/config.ts:4: Access token or key found in code. Fix: Revoke the token now, then read it from the environment or your secret manager.For the reasoning and examples behind a rule, run `npx @groundrule/cli explain <ID>`.When the check passes, or only warnings are left, the hook says nothing and the agent finishes.
Before an action
Section titled “Before an action”Before every tool call, the before-tool hook (CLI 0.24.0 and later) matches what the agent is about to do against the action policies in effect and answers in the agent’s own permission flow. An agent that is about to force-push reads:
Groundrule: this action is not allowed here. Do it another way, or ask the developer.- ACT-001 Never force-push (blocker): Never force-push; ask the developer, or push to a new branch.If the policy is wrong for this repository, say so; a time-boxed exception is written by the team in .groundrule/exceptions.yaml. Never work around it.The policies, the matching rules, the stages and the exceptions are described in Action policies. Nothing can hold up a tool call: the hook decides in milliseconds, runs the CLI version it pinned at install from npx’s cache (warmed by groundrule hooks), has 30 seconds in case that cache is cold, and any problem means no decision. Run groundrule hooks again after upgrading the CLI to move the pin.
Rules before an edit
Section titled “Rules before an edit”For Claude Code, the same hook also adds the rules that name the file about to be edited to the tool call, as extra context (since CLI 0.17.0, then as a separate Edit|Write|MultiEdit hook; running groundrule hooks again replaces it with the before-tool hook). It is the same answer the MCP tool rules_for gives:
Groundrule rules for src/payments/refund.ts (follow these; 41 repository-wide rules are in the agent file):- PAY-001 (blocker · enforce · checked automatically) Amounts in minor units: Payment code keeps amounts as integers in minor units; never floats. Fix: Use the Money type from src/payments/money.ts.- Only rules with a path scope are listed (
scope.pathsorscope.exclude, matched against the file, with language scopes matched by the file’s extension). Rules that apply everywhere are inCLAUDE.mdalready, so they are counted, not repeated. - Once per file per session. The hook remembers, in your temporary folder, which files this session was told about, so a file edited ten times is explained once. Another session hears it again.
- Nothing when no scoped rule applies, and nothing can hold up an edit: the hook has five seconds, never blocks, and any problem means silence.
- It reads the same rulebook as
check; nothing is sent anywhere.
Cursor, Codex and Copilot don’t offer a place to add context before an edit, so their before-tool hook decides actions only; their agents can call rules_for through the MCP server instead.
What the hook never does
Section titled “What the hook never does”- It asks once per turn. If the agent is already continuing because of the hook, it lets the agent finish, so an agent that can’t fix something isn’t kept going forever. Cursor gets one follow-up per turn.
- It never fails the agent. Without a Groundrule configuration, or when git can’t compare, it prints the reason to the agent’s hook log and the agent finishes normally.
- It never sends code. The check runs on your computer. In a connected repository it reads your workspace’s rulebook, the same way
checkdoes, and afterwards reports the counts per rule to the workspace; see What the workspace learns. An offline repository sends nothing.
What the workspace learns
Section titled “What the workspace learns”In a repository with platform: in .groundrule/config.yaml, when the computer is signed in (groundrule login, or GROUNDRULE_TOKEN), the stop hook and the MCP check tool send one small report to the workspace after the agent has its answer (CLI 0.16.0 and later). The before-tool hook sends a similar one for each ask or deny: the kind of action, the decision and the policy IDs, never the command or the path; see what the workspace learns about actions.
| In the report | Never in the report |
|---|---|
The agent (claude-code, cursor, codex, copilot, or the MCP client’s name) and whether it came from the hook or the MCP tool |
File paths, line numbers, snippets, diffs |
| Which rules found something and how many times, and whether each was blocking | The agent’s prompt or output, what you typed |
How many files and rules were checked, the mode (changes or all) and base, and the time it took |
Your name or email (the token says who uploaded, as for scans) |
| Whether the agent was stopped | The session id: only its SHA-256 hash is sent, so one turn’s repeats count once |
It is sent with a two-second timeout and every failure is ignored, so it can’t slow the agent or change the check’s result. The workspace uses it for Where violations are stopped on the Dashboard and the compliance report. To turn it off for a repository, add reports: none under platform:; groundrule doctor says which applies:
platform: org: acme reports: noneWhat the agent couldn’t fix is still caught in CI, and by the Groundrule check on the pull request.
Remove the hooks
Section titled “Remove the hooks”npx @groundrule/cli hooks --removeOnly Groundrule’s hooks are removed; your other hooks and settings stay.
Troubleshooting
Section titled “Troubleshooting”| What you see | What to do |
|---|---|
| “✕ .claude/settings.json isn’t valid JSON, so it was left alone. Fix it, then run this again.” | Fix the file (a trailing comma is the usual cause), then run hooks again. |
| The agent finishes without checking | Check the hook is in the file and committed. In Codex, trust it with /hooks. The hook runs npx, so Node.js 22 or later must be on the agent’s PATH. |
| The hook log says “This repository has no Groundrule configuration” | Run npx @groundrule/cli init in the repository, or npx @groundrule/cli doctor to see what’s wrong. |
| The agent was told about a finding it didn’t cause | The hook checks all uncommitted changes, including yours. Commit or stash your own work first. |