Gate the flow. Prove the work.
Agentflow
Agentflow is a lightweight, model-agnostic workflow runner that makes agentic software work auditable. It records the plan, execution steps, validations, reviews, file-change evidence, drift checks, and final proof as local files, so a run can be inspected, resumed, and verified outside any LLM chat.
The current implementation is intentionally lightweight:
- no runtime dependencies
- local file artifacts under
.agent/ - JSON schemas and templates for the workflow and execution contracts
- a Python CLI for planning, runtime checks, execution receipts, drift audit, proof-pack generation, and verification
The active task .agent/ directory is local-only by default. See
docs/agent-artifacts.md for when to keep it ignored,
upload proof as CI artifacts, attach proof to PRs, or commit a deliberate proof
bundle.
Supported interfaces and compatibility promises are defined in
docs/stability.md.
Quick Start
Agentflow is published on PyPI as the agentflow-proof distribution (the bare
agentflow name is held by an unrelated, inactive project; a transfer request
is pending). It keeps the agentflow imports and the agentflow and
agentflow-mcp commands:
python3 -m pip install agentflow-proof
From v0.4.0 on, prebuilt single-file artifacts (agentflow.pyz,
agentflow-mcp.pyz) are also published on the
GitHub Releases page; for
development you install from this source repository.
Prerequisite: Python 3.11 or newer (see requires-python in
pyproject.toml). Agentflow has no runtime dependencies — only the standard
library.
Platform support
Linux and macOS are supported and tested in release-blocking CI on Python 3.11,
3.12, and 3.13. Windows is best effort: the Python CLI may work, but Windows
has no release-blocking CI leg and no compatibility guarantee until this support
tier changes. The POSIX sh stop hook (hooks/stop-gate.sh) and shell-dependent
examples are POSIX-only; use a POSIX shell on Windows or do not use those parts.
A future supported Windows tier requires Windows CI plus adapted or replaced
POSIX-only hooks and tests.
Install from source
Use an editable install when you want command-line access to the local checkout.
Replace /path/to/agentflow with this repository's absolute path.
The uv tool and pipx options make agentflow available outside the repo
when their bin directory is on PATH. The pip option makes it available while
that Python environment is active.
uv tool install --editable /path/to/agentflow
pipx install --editable /path/to/agentflow
For a virtual environment or the current Python environment:
python3 -m pip install -e .
To test a locally built wheel without publishing it:
python3 -m pip install dist/agentflow_proof-*.whl
If the permanent PyPI name becomes available later, only project.name changes;
imports and the agentflow and agentflow-mcp command names stay the same.
Smoke tests
After any editable install that exposes the console script:
agentflow --version
agentflow --help
For no-install usage from the repository root:
PYTHONPATH=src python3 -m agentflow --version
PYTHONPATH=src python3 -m agentflow --help
For no-install usage from another directory:
PYTHONPATH=/path/to/agentflow/src python3 -m agentflow --version
PYTHONPATH=/path/to/agentflow/src python3 -m agentflow --help
Single-file build (zipapp)
Build self-contained single-file artifacts (requires only a system Python 3.11+ to run):
python3 scripts/build_zipapp.py
./dist/agentflow.pyz --version
python3 dist/agentflow-mcp.pyz --transport stdio
To use a published build instead of building locally, download agentflow.pyz,
agentflow-mcp.pyz, agentflow_proof-*.whl,
agentflow_proof-*.tar.gz, and SHA256SUMS from the
Releases page, verify the
checksums, and run:
sha256sum -c SHA256SUMS
python3 agentflow.pyz --version
See docs/packaging.md for details, limitations, and the release checklist.
Basic workflow
After installing Agentflow, initialize a repository and inspect the generated plan before locking or executing it:
agentflow init
agentflow status
agentflow validate-plan .agent/plan.lock.json
agentflow audit-drift
agentflow runtime-status --json
agentflow build-proof --strict
agentflow verify-proof
For no-install usage, replace agentflow with
PYTHONPATH=src python3 -m agentflow from the repository root.
Agent task loop
Codex, Claude Code, and other agents should use the same Agentflow task loop:
agentflow init
# Populate .agent/plan.lock.json with the required plan contract:
# objective, scope, invariants, allowed_files, validation_gates, rollback_plan,
# and real steps. Include task files and .agent/ in allowed_files; then lock it.
agentflow lock-plan .agent/plan.lock.json
agentflow init-execution
STEP_ID=P1
VALIDATION_GATE="<matching step.validation entry>"
agentflow claim-step "$STEP_ID" --agent "$USER"
agentflow run --step "$STEP_ID" --gate "$VALIDATION_GATE" -- <validation-or-work-command>
agentflow record-file-change --step "$STEP_ID" --path <changed-path>
agentflow verify-step "$STEP_ID"
agentflow complete-step "$STEP_ID"
agentflow verify-run
agentflow audit-drift
agentflow build-proof
agentflow verify-proof
The loop keeps each task tied to a plan step. init creates the planning
artifacts. Populate the full .agent/plan.lock.json contract before claiming
work; init starts with placeholder fields and an empty steps list.
STEP_ID=P1 assumes the locked plan contains a step with id P1.
VALIDATION_GATE should match the step's legacy validation entry unless the
step uses structured command gates. Include .agent/ in allowed_files when
the task uses Agentflow artifacts in the same worktree; audit-drift compares
all changed files from git status. init-execution creates execution ledgers,
claim-step assigns a step attempt, run records command receipts,
record-file-change maps edits to the step, verify-step and complete-step
close the step, and
verify-run, audit-drift, build-proof, and verify-proof prove the whole
run. Run audit-drift before build-proof so .agent/proof-pack.md includes
the current drift result from .agent/drift-report.json. To attach a follow-up
edit to an already-completed step (for example a review-feedback fix), use
amend-step — it opens an auditable new attempt linked to the prior completed
attempt rather than silently reusing it.
Adapter-backed workflows can provide the same plan contract as structured JSON
without hand-editing .agent/plan.lock.json:
agentflow lock-plan --stdin --json < plan.json
agentflow lock-plan --from-json plan.json --json
Both commands validate the supplied JSON through the normal plan validator, set
locked and locked_at, and write the canonical artifact to
.agent/plan.lock.json by default. Invalid input exits nonzero and emits a
machine-readable payload with status: "invalid" and stable diagnostic entries
under errors. The existing file-based form remains unchanged:
agentflow lock-plan .agent/plan.lock.json locks that file in place.
Adaptive workflows can also record the selected workflow policy as a durable contract:
agentflow workflow-contract --from-json workflow-contract.json
agentflow workflow-contract --validate
This writes .agent/workflow.contract.json after stdlib validation. The
artifact records the selected workflow pack/profile, rationale, required
capabilities, review depth, validation policy, and proof policy. When present,
build-proof includes a concise workflow summary and hashes the contract, so
verify-proof detects stale or tampered workflow metadata.
The adaptive workflow track can go from a task brief to a draft plan
deterministically. recommend-workflow maps a machine-authored task brief to a
workflow posture, and draft-plan compiles that brief plus a workflow pack into
an unlocked, validate-plan-valid .agent/plan.lock.json draft:
agentflow recommend-workflow --brief examples/briefs/small-bugfix.brief.json
agentflow draft-plan --brief examples/briefs/medium-feature.brief.json \
--workflow examples/packs/agentflow-draft-demo \
--objective "Add an events projection cache" --write
draft-plan treats the recommendation as a lower-bound posture, selects the
least-strict pack profile that satisfies it, and hydrates that profile's plan
template with the brief (objective, unioned gates, allowed_files including
.agent/, stricter risk). It never locks a plan and fails closed on vague
briefs, missing candidate files, or unsatisfiable postures. See
docs/draft-plan.md and
docs/recommend-workflow.md.
Agentflow v0.2 adds optional runtime metadata, runtime snapshots, structured
proof metadata at .agent/proof-pack.json, and verify-proof hash checks.
Runtime status is safe by default: configured commands are not spawned unless
runtime-status --probe is used.
agentflow view-proof --html renders the proof pack and execution ledgers
into a self-contained static HTML report (default
.agent/proof-report.html) for human review and sharing: no JavaScript, no
external references, all recorded content escaped, with links to receipt
stdout/stderr files where available. The report is a review aid only;
verify-proof remains the authoritative check.
Agentflow v0.3 Portable Runtime Contract
Agentflow v0.3 adds an optional execution layer under .agent/:
agentflow init-execution
agentflow doctor
agentflow next-step --json
STEP_ID=P1
VALIDATION_GATE="python3 -m unittest discover -s tests"
agentflow claim-step "$STEP_ID" --agent "$USER"
agentflow run --step "$STEP_ID" --gate "$VALIDATION_GATE" -- python3 -m unittest discover -s tests
agentflow record-file-change --step "$STEP_ID" --path src/agentflow/example.py
agentflow verify-step "$STEP_ID"
agentflow complete-step "$STEP_ID"
agentflow verify-run
agentflow audit-drift
agentflow build-proof
agentflow verify-proof
Execution ledgers are additive. Existing v0.2 proof artifacts remain valid when no execution contract exists.
Agent Artifact Policy
Root .agent/ is task-local by default. Commit or publish it only when the
workflow explicitly calls for a reviewed proof bundle. The policy in
docs/agent-artifacts.md explains:
- local-only, CI-uploaded, PR-attached, and committed proof workflows
- which
.agent/files are useful proof versus sensitive command output - when plans should include
.agent/inallowed_files - how adapter-backed workflows such as Golem should retain and publish proof
MCP Server
Agentflow ships a dependency-free MCP server that exposes the core workflow
commands as MCP tools, so any MCP-capable front-end discovers them
automatically. It speaks JSON-RPC 2.0 over stdio (Claude Code, Codex CLI) and
Streamable HTTP (local LLMs such as Ollama/Open WebUI and llama.cpp). The server
is a thin wrapper that runs agentflow.cli.main in-process — no business logic
is duplicated and no new runtime dependency is added.
# stdio (Claude Code reads .mcp.json, Codex reads .codex/config.toml)
PYTHONPATH=src python3 -m agentflow.mcp_server
# Streamable HTTP for local LLM front-ends
PYTHONPATH=src python3 -m agentflow.mcp_server --transport http --port 8765
Exposed tools: status, doctor, next_step, next_action, claim_step,
amend_step, reclaim_step, block_step, renew_lease, record_review,
complete_step, verify_step, finish_step, verify_run, finish_run,
audit_drift, build_proof, verify_proof. The arbitrary-command tools
(run, record-command) are intentionally not exposed, and fail-step is a
deliberately CLI-only break-glass operator action.
See docs/mcp.md for transports, configs, and the security
boundary.
Stop Hook (Enforcement Gate)
Where the MCP server gives an agent voluntary access to the tools, the stop
hook (hooks/stop-gate.sh) is the enforcement twin: it blocks a session from
finishing until the proof chain passes (verify-run -> build-proof ->
verify-proof). It is runtime-agnostic — a POSIX sh script with no
third-party dependencies that signals through a universal exit-code contract
(0 = proof satisfied or repo ungoverned, non-zero = block).
# Bare invocation (CI, git pre-commit, OpenHands, Codex):
sh hooks/stop-gate.sh
The hook is Agentflow-specific: with no locked .agent/plan.lock.json it exits
0 and never runs the CLI, so it is safe to install in any repo. Example
runtime configs ship for Claude Code (.claude/settings.json, with a
|| exit 2 adapter since Claude Code blocks only on exit 2) and OpenHands
(.openhands/hooks.json). None auto-activate — copy the
snippet to turn the gate on. See docs/stop-hook.md for
per-runtime wiring, idempotency, and the loop-safety notes.
Command Risk Screening
Before agentflow run executes a command, a deterministic, no-network, no-LLM
analyzer classifies it (low/medium/high) and records the result on the
command receipt. A command_policy.risk_policy of warn, require-confirmation
(the new-contract default), or block decides whether a high-risk command —
rm -rf, chmod 777, credential reads, sudo, curl | sh, writes outside
scope, blocked-path references — is blocked before it runs. This is deterministic
risk screening, not a security sandbox. See
docs/command-risk.md for the category catalog, the
--confirm-risk / AGENTFLOW_CONFIRM_RISK override, and detection limits.
Hunk-Level Attribution
When record-file-change records an edit, Agentflow captures a per-hunk
fingerprint of the diff against HEAD (sha256 of the changed lines, with
span-independent identity so unrelated line-number shifts do not invalidate it).
audit-drift and verify-run then flag any current diff hunk inside an allowed
file that matches no recorded receipt hunk as an unmapped_hunk. This
distinguishes the edits a step actually attested from stray or unrelated edits
in the same allowed file. The proof_policy.hunk_attribution knob
(enforce / observe / off) governs severity; the default is enforce when
an execution contract exists and off otherwise. Receipts store only hashes,
spans, and counts — never raw changed-line text. The workflow contract and
receipt behavior are documented in
docs/agent-workflow.md.
Single-Writer Leases
The execution contract can enforce single-writer ownership of a plan step so
that only the agent holding a live lease may write to or close an attempt. It is
opt-in via concurrency.lease_policy (advisory by default, so existing plans
are unchanged); set it to enforce to gate claims, writes, and lifecycle
transitions on agent identity and a wall-clock lease. reclaim-step recovers a
crashed owner after its lease expires, renew-lease extends an owner's own
lease, and fail-step is the break-glass. Pass --agent on write and lifecycle
commands (or set AGENTFLOW_AGENT_ID). multi_writer remains rejected;
cross-worktree aggregation now ships separately via aggregate-ledgers
(#30), which merges
one-writer-per-worktree runs into a single canonical proof. See
docs/single-writer-leases.md for the contract
fields, the full enforce loop, and the migration note.
GitHub Actions Proof Gate
This repository includes a dependency-free GitHub Actions gate in
.github/workflows/ci.yml. The workflow runs the unit test suite from the source
checkout, stages a configured proof root into a temporary git repository, then
runs:
PYTHONPATH=src python3 -m agentflow verify-run --no-record --root "$PROOF_ROOT"
PYTHONPATH=src python3 -m agentflow verify-proof --root "$PROOF_ROOT"
verify-run --no-record is for CI and other read-only checks: it validates the
execution ledger without appending a new entry to .agent/verification-runs.jsonl,
so verify-proof can still validate the committed proof hashes afterward.
How strict a run is comes from .agent/execution.contract.json, which the agent
doing the work can edit. On its own, verify-proof accepts a proof built under
hunk_attribution: off or review_gate: ignore. To let CI set the minimum
instead, pass --require KEY=MIN, once per key:
PYTHONPATH=src python3 -m agentflow verify-proof --root "$PROOF_ROOT" \
--require hunk_attribution=enforce --require review_gate=block
A setting below its floor fails with policy_below_floor, and so does a proof
with no execution contract. Keep the floor in CI configuration the agent cannot
change. agentflow verify-proof --help and the CHANGELOG list the keys. A
floor on risk_policy, lease_policy or hunk_attribution also requires every
run record, and a drift report from audit-drift, to name the contract the
proof hashes, so raising those settings after the work fails it. Receipt
requirements can still be tightened after a step completes without failing the
matching floor, and a proof can even verify with a failed gate under the
tighter receipt policy (see docs/security-model.md).
The workflow uses AGENTFLOW_PROOF_ROOT to select the committed proof bundle.
This repository points it at tests/fixtures/proof-bundle so CI can regression
test the verifier itself without committing task-local root .agent/ artifacts.
Repositories that commit the active task proof bundle should set
AGENTFLOW_PROOF_ROOT to .. On pull requests, the workflow uses the PR base
commit as the temporary git baseline before overlaying the current proof root, so
verify-run still sees source edits that lack file receipts. Set
AGENTFLOW_PROOF_BASE_REF explicitly when the baseline should be a different
commit:
env:
AGENTFLOW_PROOF_ROOT: .
AGENTFLOW_PROOF_BASE_REF: ${{ github.event.pull_request.base.sha }}
Expected failure behavior:
- missing
.agent/proof-pack.json: CI fails before verification starts - stale proof metadata, hash mismatches, or modified receipt output files:
verify-proofexits non-zero - incomplete execution ledgers, drift failures, or unmapped changed files:
verify-runexits non-zero
Project Status
Agentflow is past 1.0, and its artifact schemas are frozen under the policy in
docs/stability.md. What is available today and what comes
next are tracked in the roadmap. Each
release, with its notes, is on the
Releases page and in
CHANGELOG.md.
Documentation
- Agent workflow — plan, execute, verify, and prove a run
- Artifact policy — decide what stays local and what is safe to publish
- Security model — trust boundaries, guarantees, and operator responsibilities
- Command risk screening — deterministic command classification and limits
- MCP server — stdio and local HTTP transports
- Workflow packs — reusable workflow policy and planning profiles
- Executable examples — CI proof, MCP, workflow-pack, and aggregation walkthroughs
- Packaging and releases — build and verify single-file artifacts
- Roadmap — current status and near-term priorities
Contributing and Security
Contributions are welcome. See CONTRIBUTING.md for the local development and pull-request workflow. Please report vulnerabilities privately as described in SECURITY.md.
Branding
The agentflow brand kit lives in docs/branding/; open
brand-guide.html for the full guide.
The mark is a gate / ledger: plan-step rails passing through a validation
gate — pending (gray) in, verified (teal) out — reusing the vertical bar in the
agent│flow wordmark. Teal #00D4AA is the primary accent; mint #86EFAC is
reserved for PASS/success states.
| asset | file |
|---|---|
| primary mark | agentflow-mark.svg |
| favicon (≤16px) | favicon.svg |
| lockups | dark · light |
| status badge | agentflow-badge.svg |
| social card | agentflow-social.svg |
Core Rule
No fact without evidence.
No edit without a plan step.
No plan change without an amendment.
No completion without verification.
No context unless it pays rent.
License
Agentflow is available under the MIT License.
Metadata
Release files for agentflow-proof 1.5.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.5.0.tar.gz | 440.3 kB | Without provenance | Details for agentflow_proof-1.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentflow_proof-1.5.0-py3-none-any.whl | Python 3 | none | any | Details for agentflow_proof-1.5.0-py3-none-any.whl |
Total release size: 629.9 kB
Release files / agentflow_proof-1.5.0.tar.gz
| Download URL | agentflow_proof-1.5.0.tar.gz |
|---|---|
| Size | 440.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b813c1de96dbd2a22659b28ffb746cc2ea843ec92c1089eab3bda6f199a81eb
|
|
BLAKE2b-256 checksum How to use checksums |
e27a0c9157b2b3a81e6f961ab8123b82e843c9f4556714310c23f505f8099e37
|
| 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.5.0-py3-none-any.whl
| Download URL | agentflow_proof-1.5.0-py3-none-any.whl |
|---|---|
| Size | 189.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
53b41a3cdc6fc43201f527d35b60904d8590fe49a69de0f0139a93bf46e8049f
|
|
BLAKE2b-256 checksum How to use checksums |
8e50fa0adaae956cf89c3cc0def44f5e9cedd24ebcf00b4f731023aaac42196e
|
| 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.5.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.