@kontourai/flow weekly downloads statistics

Kontour Flow

Proof, not promises. Flow shows why work was allowed to move forward.

Documentation · Getting Started · Use Cases · CLI Reference · kontourai.io/flow

AI agents move faster than humans can inspect. They skip steps, accept weak evidence, declare work complete after partial verification, and lose the thread after context compaction. The work *looks* done — until you ask why it was allowed to advance, and nobody can answer.

Flow is the missing record in the middle: the required path, the evidence each gate expected, the evidence that was actually collected, and the exceptions a human explicitly accepted. It does not run your agents and it does not replace CI. It explains — durably, locally, in plain files — why the work was allowed to advance.

Why teams adopt Flow

• Evidence-gated transitions. A step is not complete because an agent says so. Gates declare typed expectations, and runs advance only when evidence satisfies them — or when a human accepts an explicit, attributable exception. • Survives context loss. Every run lives in plain files under .kontourai/flow/runs//. A new agent session, a teammate, or a CI job can flow resume and continue from recorded state, not chat memory. • Deterministic route-back. Failed evidence routes work back to the right step (implementation_defect → implement, plan_gap → plan) with attempt budgets, so agents cannot loop silently forever. • Authorized retry epochs. An exhausted blocked route-back can return only to its declared route in the same run through a provider-neutral, authority-bearing flow authorize-retry request; it preserves failure history and requires fresh re-entry evidence. • Audit-ready reports. Every run regenerates a human-readable report.md and machine-readable report.json that explain what passed, what blocked, what was excepted, and what happens next. • Local-first, zero lock-in. Flow is a file-backed CLI and TypeScript library. No hosted service, no account, no telemetry. Your evidence stays in your repo.

See it

Thirty seconds, four commands — and a gate an agent cannot talk its way past:

The bundled local Flow Console (flow console) renders any run from its local files — the process graph, gate outcomes, evidence, route-backs, and the next action:

Quickstart

In a hurry? npx flow init --demo scaffolds a ready-made run named demo so flow status demo and flow console --run demo have something real to show immediately.

The Getting Started guide walks this path end to end with real output, including what evidence files look like and how a blocked gate routes work back.

Where Flow fits

Flow is the process-transparency layer of the Kontour product line: *Kontour shows the work behind AI.*

| Product | Owns |

| Survey | Producer evidence: source → extraction → candidate → review → claim | | Surface | Portable trust state: claims, evidence, policies, trust snapshots | | Flow | Process transparency: steps, gates, transitions, runs, exceptions, reports | | Veritas | Code/change transparency: repo standards, merge readiness | | Flow Agents | Agent-facing distribution: kits, runtime adapters, hooks |

Flow stands alone — you need none of the other products to use it. When they are present, Veritas can supply repo-readiness evidence to Flow gates, and Flow Agents can enforce Flow gates from inside Claude Code, Codex, Kiro, or GitHub Actions.

Real teams use Flow for agentic development gates, regulated release decisions, platform golden paths, adversarial review loops, and audit-ready change evidence. Use Cases walks through each with definitions you can copy.

How it works

1. Author a Flow Definition — JSON describing steps, gates, typed evidence expectations, and route-back policy. Validate it with flow validate-definition. 2. Start a Flow Run — flow start snapshots the definition and creates authoritative run state under .kontourai/flow/runs//. 3. Attach evidence — test output, CI results, trust reports, human attestations. Files are copied into the run; flow capture can optionally create an exact command receipt first. 4. Evaluate gates — flow evaluate passes, blocks, routes back, or waits. Accepted exceptions are first-class, recorded with reason and authority. 5. Report and resume — report.md / report.json explain the run; flow resume gives the next agent everything it needs without chat memory.

CLI

Every command accepts --cwd to scope local Flow files. Full flags, formats, and exit behavior: CLI Reference.

Library

The same primitives the CLI uses are exported from the package root, fully typed:

Public usage is limited to the package root, the flow CLI, and documented contract subpaths; dist/ subpaths are not part of the npm API. The Library guide covers run lifecycle, projections, release readiness evaluation, and config merge helpers.

Immutable gate-evaluation receipts

Committed gate appraisals have a browser-safe contract at @kontourai/flow/gate-evaluation-contract and an authorized native reader at @kontourai/flow/gate-evaluation-reader:

authorize is required and runs before Flow reads any run artifact. A denied request and an unknown receipt both return { status: "missing" }, so callers cannot use the API to enumerate run or gate ids. found exposes only the recorded reference, timestamp, original verdict, route-back/exception ids, current run and gate standing, and selected evidence ids/digests. It never returns local paths, raw bundles, arbitrary metadata, or exception authority payloads. unavailable means a fenced, malformed, or unreadable canonical run; unsupported means a legacy run without this ledger or an unknown ledger version.

The reader is zero-write and recovery-fenced. Its original verdict and selection set are immutable: replacement evidence and later project policy do not heal or rewrite an old receipt. The projection separately marks selected evidence as current, superseded, or missing, and reports only the recorded point-in-time freshness/revocation markers when available.…

Description from the npm listing.