| name | agentguard |
| description | Standards-enforcing validation gates for git commits. Catches what linters miss. |
| version | 3.3.0 |
| tags | validation, git-hooks, agent, code-review, husky, lefthook |
agentguard
Standards-enforcing validation gates for AI agents. Scans your codebase, learns your patterns, and blocks commits until validation passes.
Not a replacement for lint/build/test. Those are deterministic โ run them in CI. agentguard catches everything else: the patterns linters miss, the standards PR reviewers enforce manually.
Installation
skills.sh (Claude Code, Codex, Cursor):
npx skills add chidev/agentguard
ClawdHub (OpenClaw):
npx clawhub@latest install agentguard
Then invoke:
"Use agentguard to add standards-enforcing validation gates to this repo"
Workflow
Step 1: Scan
Read the project to understand what exists before configuring anything.
- package.json โ Read
scripts (build, lint, test, typecheck), devDependencies, detect package manager (npm/pnpm/bun via lockfile)
- Existing hooks โ Check
.husky/, lefthook.yml, .git/hooks/* for active hook systems
- Configuration โ Check for
.agentguard.json (already configured? skip to Step 4)
- Standards โ Read
CLAUDE.md, AGENTS.md for existing agent instructions and project standards
- PR history โ Run
gh pr list --limit 5 --json title,url and check recent review comments for recurring feedback patterns
Step 2: Present Findings
Show the user what was discovered:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AGENT-LEASE DISCOVERY โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ Project: {name} Package Manager: {pm} โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ EXISTING HOOKS โ
โ {list hooks found, or "None detected"} โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ DETERMINISTIC CHECKS (from package.json scripts) โ
โ {list: lint, build, test, typecheck โ mark found/missing} โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ NON-DETERMINISTIC PATTERNS โ
โ {from PR comments: "update changelog", "add tests", etc} โ
โ {from CLAUDE.md: project standards found} โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Ask the user:
- Which standards should agentguard enforce?
- Which deterministic checks to include as runners?
- Hook system preference? (use existing if found, husky by default, lefthook as option)
Step 3: Configure
- Run
npx agentguard init โ installs hooks (detects husky automatically, falls back to .git/hooks/)
- Edit
.agentguard.json with runners based on user input:
- Add deterministic runners (lint, build, test) with their actual commands from
package.json
- Add pattern runners (LLM review) if requested
- Create
.agentguard/commit.md โ template with standards the user chose, injected into LLM review prompts via {{standards}}
- Create
.agentguard/push.md โ template for push-phase review standards (if push runners configured)
Step 4: Show Dashboard
Display what was configured:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AGENT-LEASE CONFIGURED โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ Hook System: {husky | lefthook | .git/hooks} โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ COMMIT PHASE โ
โ [deterministic] lint {command} โ
โ [deterministic] typecheck {command} โ
โ [pattern] review claude -p '...' โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ PUSH PHASE โ
โ [deterministic] test {command} โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ Templates: .agentguard/commit.md, .agentguard/push.md โ
โ Config: .agentguard.json โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
CLI Reference
| Command | Description |
|---|
agentguard init | Install hooks + config + templates (detects husky) |
agentguard commit | DENY: show gate template, create lock, exit 1 |
agentguard commit --audit-proof='...' | RELEASE: accept proof, release lock, exit 0 |
agentguard push | DENY: show gate template, create lock, exit 1 |
agentguard push --audit-proof='...' | RELEASE: accept proof, release lock, exit 0 |
agentguard status | Check current lock state |
agentguard clear | Remove all locks for this project |
agentguard release --audit-proof | Legacy: run all runners internally and release |
For AI Agents
When an agent attempts git commit:
- Hook calls
npx agentguard commit โ DENY: shows gate template with โ --no-verify is FORBIDDEN header
- Template shows configured runners and callback format
- Agent runs each runner, captures output
- Agent submits proof:
npx agentguard commit --audit-proof='## Validation Report\nRunner: lint\nStatus: PASS\nOutput: clean\n\nSummary: All passed.'
- Lock releases, agent runs
git commit again โ hook calls agentguard commit โ sees proof โ exit 0 โ commit succeeds
The key: agents cannot skip validation. The lock persists until proof is submitted.
Template Variables
Available in runner command strings:
| Variable | Value |
|---|
{{diff}} | Staged changes (commit phase) or origin/main...HEAD diff (push phase) |
{{files}} | List of changed file paths |
{{project}} | Project name from .agentguard.json |
{{branch}} | Current git branch |
{{hash}} | Current commit hash |
Adding Runners
Runners are defined in .agentguard.json under "runners":
Deterministic (binary pass/fail):
{ "name": "lint", "command": "pnpm run lint", "on": "commit" }
{ "name": "test", "command": "pnpm test", "on": "push" }
Pattern (LLM review):
{
"name": "haiku-review",
"command": "claude -p 'Review against standards:\n{{diff}}'",
"on": "commit",
"llm": true
}
Each runner needs name, command, and on (which phase: "commit" or "push").
