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.9.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.9.0
File Size Uploaded Provenance Actions
agentflow_proof-1.9.0.tar.gz 497.8 kB Without provenance Details for agentflow_proof-1.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 702.8 kB

Release files / agentflow_proof-1.9.0.tar.gz

Download URL agentflow_proof-1.9.0.tar.gz
Size 497.8 kB
Tags Source
SHA-256 checksum
How to use checksums
cd94498b223ccad93df300d91a314aa9f52ab7f448b75e5d67ec14aa4c949a71
BLAKE2b-256 checksum
How to use checksums
e38094db6f54130bfc2f7f8d5859650f497f60503283a63e4ac8473d2bc3b7c3
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.9.0-py3-none-any.whl

Download URL agentflow_proof-1.9.0-py3-none-any.whl
Size 205.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
17233d8c8d7f98180cea481a7e9592a0cc16af699660e1f3823a0fdf5c7be3b6
BLAKE2b-256 checksum
How to use checksums
d73fbbbfb44b775329ec393826167c90edde96f1b70829f6b89f0ae67d3d0108
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.9.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