gitvow
Provenance and a policy gate for AI-agent coding sessions, stored in the git you already have.
Who made this change, what were they trying to do, and was it allowed? For code written with AI agents, git alone cannot answer. gitvow makes it answer.
- Commits made during an agent session carry the session id and a step number as trailers.
- Each such commit gets a session note: the agent's stated plan, the tools it used, the files it touched, how much of the commit it wrote. Redacted, stored as a git note, never in the tree.
- Every tool call passes a gate first: destructive commands are refused, risky ones require asking you, edits to gate-bearing files need a human. The rules are a JSON file you own. Missing policy fails closed.
- A ledger of the whole session stays in your home directory. Nothing leaves the machine unless you push it.
Standard-library Python and git. No runtime dependencies, no network calls, no telemetry.
Quick start
pip install gitvow
gitvow install --user
gitvow selftest
Work in Claude Code as usual. When the agent commits:
$ git log -1 --format=%B
Fix week-start cache key
Gitvow-Session: 8f3d5c71-574a-4eec-8903-9425e3a8335b
Gitvow-Step: 4
$ gitvow show HEAD
...
gitvow-session
{
"step": 4,
"tools_used": ["Bash", "Edit", "Read"],
"last_stated_plan": "Change the cache key to include week start so per-org settings do not collide...",
"files_in_commit": ["query-engine/.../QueryCacheHelper.java | 4 +++-"],
"files_written_by_agent_this_session": ["query-engine/.../QueryCacheHelper.java"],
"attribution": {"files_in_commit": 1, "touched_by_agent": 1}
}
Try the gate by hand:
gitvow check -- git push --force # DENY: force push
gitvow check -- kubectl apply -f x.yaml # CONFIRM: cluster apply
gitvow check --path core/authz_rules.go # CONFIRM: edits an authorization or gate file
Remove everything:
gitvow uninstall --user
Documentation
The docs site is the source of truth: https://wirevow.dev/gitvow (built from docs/).
How it works
Claude Code ──hook──▶ gitvow hook PreToolUse ──▶ policy ──▶ allow / confirm / deny (exit 0 / 2 / 2)
──hook──▶ gitvow hook PostToolUse ─▶ on `git commit`: read transcript → redact → git notes add
Claude Code ──hook──▶ gitvow hook UserPromptSubmit ▶ first line of the first message → redact → the session's intent
git commit ──prepare-commit-msg──▶ Gitvow-Session / Gitvow-Step / Gitvow-Intent trailers (from .git/gitvow-session.json)
Claude Code ──hook──▶ gitvow hook Stop ─────────▶ ~/.gitvow/ledger/<session>.json
| Data | Where | Enters git? |
|---|
| session id, step, intent (one redacted line in the person's words) | commit trailers | yes |
| session note (structure, redacted plan, attribution) | refs/notes/sessions | as a note; local until pushed |
| ledger, hook log, session state | ~/.gitvow/, <repo>/.git/ | no |
| transcript | untouched | never; gitvow sessions export, typed by a person, can hand it complete to a store your organisation runs |
Status
0.1.0. Used in a small internal trial; the roadmap lists what comes next and what is deliberately not planned. Claude Code is the only agent supported today; the hook payload is documented so adapters are straightforward.
Contributing and security
See CONTRIBUTING.md and SECURITY.md. Reproductions of redaction gaps must use synthetic secrets.
Apache-2.0.
