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
| Data | Where | Enters git? |
|---|---|---|
| session id, step | 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 |
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.
1 maintainer
Metadata
1 maintainer
Release files for gitvow 0.21.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gitvow-0.21.0.tar.gz | 152.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gitvow-0.21.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 268.4 kB
Release files / gitvow-0.21.0.tar.gz
| Download URL | gitvow-0.21.0.tar.gz |
|---|---|
| Size | 152.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
50a969cbe31a3acc0ec90f210e8429908fc99d5b33c4d0f19cab70cb9ff5f872
|
|
BLAKE2b-256 checksum How to use checksums |
6b42663b179e72ad54181aef15bf1f3b02d82b4212b7f74c13db4f6ab8801b0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / gitvow-0.21.0-py3-none-any.whl
| Download URL | gitvow-0.21.0-py3-none-any.whl |
|---|---|
| Size | 116.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5fc23911043e03b590c9a8a7208b0409d7bb13d6c294efd6823f4740c1e7f145
|
|
BLAKE2b-256 checksum How to use checksums |
55610307b845808c496461408fa52d20abf0e19a88dec2c914302c7c40fa19fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
