| 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").
