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

• Quick start
• Concepts: Sessions, steps and notes · The gate · What stays out of git
• Guides: Install per user or per repo · Write a policy · Read a commit's session · Run a trial · Redaction
• Reference: CLI · Hook payloads · Note schema · Policy schema
• Security · Roadmap · FAQ

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
git commit ──prepare-commit-msg──▶ Gitvow-Session / Gitvow-Step trailers   (from .git/gitvow-session.json)
Claude Code ──hook──▶ gitvow hook Stop ─────────▶ ~/.gitvow/ledger/<session>.json

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.