Second commit passes because docs are now staged alongside code. The hook doesn't need to call any AI — it just checks whether the right files are included.
The self-invocation guard is critical: if the hook tried to spawn Claude Code as a subprocess while Claude Code is already running, you'd get a deadlock. By detecting the CLAUDECODE env var and skipping all engines, the hook avoids this entirely.
API Auto-Fix for Human Commits
When you commit from the terminal (no CLAUDECODE env var), the hook calls the Anthropic API directly to update your docs:
"autoFix": {
"hook": { "mode": "blocking" },
"narrative": {
"engine": "api",
"model": "claude-sonnet-4-20250514"
}
}
It reads your staged source files, reads the current ARCHITECTURE.md, sends both to the API, and writes back the updated sections. About 20 seconds and ~$0.10 per commit. The hook stages the updated docs and the commit proceeds without you doing anything.
If the API is down or your key is missing, the hook degrades to advisory mode — it prints a warning but lets the commit through. You don't get punished for infrastructure failures.
Session Context: Continuity Between Sessions
Every commit generates .agent-guard/session-context.md — a rolling summary that gives AI agents memory between sessions:
# Session Context — agent-guard
> Auto-generated by agent-guard. Do not edit manually.
> Last updated: 2026-03-29T16:46:40.973Z
## Recent Commits
| Hash | Date | Message | Categories | Docs Updated |
|------|------|---------|------------|--------------|
| f622d60 | 2026-03-29 | fix: session context on all paths | source | ARCHITECTURE.md |
| 29f8f9f | 2026-03-29 | fix: session-context staging | source | ARCHITECTURE.md |
| 174323f | 2026-03-29 | feat: auto-generate session context | source | — |
## Documentation Health
- **Hook mode:** blocking
- **Engine:** claude-code
- **Stale marker:** none
- **Categories:** env (.env), source (src/)
The standing instructions tell Claude Code to read this file before making any changes. Now when you start a new session, the agent knows what happened last time — which files changed, whether docs were updated, and whether anything is stale.
Standing Instructions That Update Themselves
agent-guard injects a documentation maintenance section into your AI config files. It writes to .cursorrules, CLAUDE.md, and any additionalAgentConfigs simultaneously. Here's what the generated table looks like:
| If You Changed… | Update This | And Run… |
|---|---|---|
| `.env` | Environment Variables section in `docs/ARCHITECTURE.md` | Run `npm run gen:env` |
| `src/*` | Architecture section in `docs/ARCHITECTURE.md` | — |
When the hook runs auto-fix, it regenerates this table from the current config categories. Add a new category for src/services/ and the standing instructions automatically include it on the next commit. No manual editing.
The Behavior Matrix
| Scenario | What Happens |
|---|---|
| Human commits, docs current | Silent pass |
| Human commits, docs stale | API auto-fix (~20s), commit proceeds |
| Human commits, API down | Degrade to advisory + warning |
| Claude Code commits, docs current | Silent pass |
| Claude Code commits, docs stale | Block + remediation instructions |
| Rebase/merge in progress | Auto-downgrade to advisory |
What It Doesn't Do
agent-guard keeps documentation in sync — it doesn't write your architecture for you. If your ARCHITECTURE.md is empty, it stays empty. The tool maintains what you've written, not what you should write.
It's designed for solo devs and small teams, not enterprise collaboration. It doesn't work outside git. It has zero dependencies — the whole thing is git hooks and API calls, not a platform. Node 20+ built-ins only.
Try It
npm install --save-dev @mossrussell/agent-guard
npx agent-guard init
MIT licensed. Zero dependencies. Node 20+.
Top comments (0)