Gate the flow. Prove the work.
Agentflow
An AI coding agent says the work is done. Agentflow makes it show the receipts.
Agentflow is a small command-line tool that runs beside any coding agent, such
as Claude Code, Codex, or a local model. The agent works from a locked plan,
runs its checks through Agentflow, and records each edit against a step of that
plan. Agentflow gathers those receipts into a proof pack: plain files under
.agent/ that you, a reviewer, or CI can check without reading the chat.
It is for developers and teams who want reviewable evidence of what an agent changed, not its word for it.
- Runs locally. Python 3.11+ standard library only; no service, no account.
- Any agent that can run shell commands. It is a CLI and an MCP server (Model Context Protocol, a standard way for agents to call tools), not a framework.
- Plain local files. Plans, receipts, and proofs are JSON and Markdown you can read and diff.
Install
python3 -m pip install agentflow-proof
The package is agentflow-proof on PyPI (plain agentflow there is an
unrelated project). It installs two commands, agentflow and agentflow-mcp.
If pip reports an externally managed environment, use pipx install agentflow-proof
or a virtual environment. Linux and macOS are supported; Windows is best
effort (platform support).
Next: run the Quickstart, a first proof in an empty repository in about two minutes.
Single-file builds with checksums are on the Releases page, covered in Packaging. To work from a source checkout, see CONTRIBUTING.
How a run works
The agent usually types these, not you. This is the lifecycle of a one-step plan, with placeholders; the Quickstart has the runnable version.
agentflow init # create .agent/ with a blank plan
# fill in the plan: objective, scope, allowed files, steps, checks
agentflow lock-plan .agent/plan.lock.json # validate and lock it
agentflow init-execution # open the ledgers, the run's JSONL logs
agentflow claim-step P1 --agent "$USER" # take a step
# ...the agent edits files here...
agentflow run --step P1 --gate "<check>" -- <command> # run a check, keep the receipt
agentflow record-file-change --step P1 --path <file> # tie an edit to the step
agentflow finish-step P1 # verify the step, then complete it
agentflow finish-run # audit, verify, build the proof, verify the proof
A successful finish-run prints:
audit-drift ok
verify-run ok
build-proof ok
verify-proof ok
verify-run and audit-drift compare everything changed since the run
started, committed or not. A changed file with no receipt fails verify-run.
An unrecorded edit inside a recorded file, or a file outside the plan's scope,
fails audit-drift.
Anyone with the proof files can check them again later with
agentflow verify-proof, which compares the ledgers and receipts with the
checksums the proof recorded. The proof stays local by default;
Agent artifacts covers sharing it with reviewers and CI. The
Agent workflow guide explains each phase.
Use it with your agent
- Instructions. Tell the agent to follow the task loop. This repository's own AGENTS.md is a working example.
- MCP server.
agentflow-mcpserves the workflow as tools over stdio or loopback HTTP. Point your MCP client at it and the agent sees the tools. It does not exposerunorrecord-command; MCP server sets out the security boundary. - Stop hook. Once wired into your agent runtime, it blocks a session from finishing until the proof passes. See Stop hook.
- CI gate. Verify the proof in GitHub Actions and let CI, not the agent, set the minimum policy, how strict a run must be. See CI proof gate.
What it covers
- Locked plans and amendments: scope, allowed files, and steps are
set up front, and
amend-planrecords a change to them. - Receipts down to the diff hunk: each changed block of lines (a diff hunk) in an allowed file must trace to a step.
- Command risk screening: commands like
rm -rforcurl | share flagged, held for confirmation, or blocked before they run. - Proof packs with a static HTML report (
agentflow view-proof --html). - Single-writer leases (one agent writes to a step at a time) and proof aggregation across Git worktrees (checkouts of one repository).
- Workflow packs: reusable policy, workflow recommendations, and draft plans.
Agentflow records and checks; it is not a sandbox, and its proofs are checksum-based tamper evidence, not signatures. The Security model says what is guaranteed and what is left to you.
Documentation
Quickstart · Agent workflow · Security model · Stability and compatibility · Examples · All docs
Project status
Agentflow is past 1.0. Its commands and file formats follow a written stability policy. See the Roadmap for what comes next and the Changelog for each release.
Contributing, security, and license
Contributions are welcome; start with CONTRIBUTING. Report vulnerabilities privately as described in SECURITY.md. Agentflow is released under the MIT license.
Metadata
Release files for agentflow-proof 1.8.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 | Provenance | Actions |
|---|---|---|---|---|
| agentflow_proof-1.8.0.tar.gz | 484.8 kB | Without provenance | Details for agentflow_proof-1.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentflow_proof-1.8.0-py3-none-any.whl | Python 3 | none | any | Details for agentflow_proof-1.8.0-py3-none-any.whl |
Total release size: 687.0 kB
Release files / agentflow_proof-1.8.0.tar.gz
| Download URL | agentflow_proof-1.8.0.tar.gz |
|---|---|
| Size | 484.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e2f0a7f25aa101f10463d969f60db3f3eb1863d40e546ce72ee0f0a38bc68229
|
|
BLAKE2b-256 checksum How to use checksums |
98733b86e3c1f6edbecdc3eb657d523bb7523470a2e4c1ce0e7a7b881179ef7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / agentflow_proof-1.8.0-py3-none-any.whl
| Download URL | agentflow_proof-1.8.0-py3-none-any.whl |
|---|---|
| Size | 202.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4e7bc431b4c3624e47095753a64aa6dd980b49a37433b15c3f12a13bd38e7bd
|
|
BLAKE2b-256 checksum How to use checksums |
459475caf785d4aa65f8f77a1eb6ec080f91d266df3e3dec5e8de4b44010e9a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for agentflow-proof 1.8.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.