Skip to main content

agentflow

Gate the flow. Prove the work.

agentflow — proof

CI PyPI License: MIT Python 3.11+

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-mcp serves the workflow as tools over stdio or loopback HTTP. Point your MCP client at it and the agent sees the tools. It does not expose run or record-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

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.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentflow-proof 1.7.0
File Size Uploaded Provenance Actions
agentflow_proof-1.7.0.tar.gz 480.6 kB Without provenance Details for agentflow_proof-1.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentflow-proof 1.7.0
File Interpreter ABI Platform Actions
agentflow_proof-1.7.0-py3-none-any.whl Python 3 none any Details for agentflow_proof-1.7.0-py3-none-any.whl

Total release size: 681.7 kB

Release files / agentflow_proof-1.7.0.tar.gz

Download URL agentflow_proof-1.7.0.tar.gz
Size 480.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ee9362f0d4a0ddcc29304ad694ad29bd5052fbff77fed396cb36013cb1118a8d
BLAKE2b-256 checksum
How to use checksums
8bae814d185e75ebbd0ec6474b1e440d773dbd7bd06ccc492b085473d38ed630
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.7.0-py3-none-any.whl

Download URL agentflow_proof-1.7.0-py3-none-any.whl
Size 201.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9292776ab7c4699b1285ecfbc9df0d2fa039c4b277a374a5756e147fe1832fba
BLAKE2b-256 checksum
How to use checksums
11a9ea2743c3976c04d83a06b5c783fec4c4a3dae6b61dbee8cc3e7573861ee9
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.7.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page