Checkpointflow: A Deterministic and Recoverable Workflow Engine Designed for AI Agents and Operations Personnel

Checkpointflow is an open-source deterministic recoverable workflow engine designed for AI agents and ops personnel. It uses YAML to define portable workflows, supporting validation, stable CLI execution, explicit pause/resume, and persistent state management. It addresses key pain points in traditional agent workflows: state dependency on chat history, implicit pause/resume, hard-to-validate outputs, and cross-agent/operator handover issues. Key features include explicit event waiting (via await_event), JSON Schema validation for inputs/outputs/events, and a stable runtime contract. It applies to scenarios like Codex, Claude Code, CI jobs, etc.

Traditional agent workflows face several challenges:

1. State hidden in chat threads: Critical execution state only exists in conversation history—losing the session or switching tools breaks the workflow.
2. Implicit pause/resume: Mechanisms lack explicit modeling, relying on implicit conversation continuation which is hard to predict and debug.
3. Hard-to-validate outputs: Structured validation of intermediate outputs before next steps is difficult.
4. Cross-agent/operator handover difficulties: Another agent or human can't reliably continue unfinished work. Checkpointflow solves these by making workflow contracts explicit, turning them into versioned, verifiable, portable state machine docs.

Core design principles:

• Explicit over implicit: Waiting states modeled via await_event instead of hidden chat state.
• Validation first: Inputs, outputs, recovery events validated via JSON Schema.
• Stable contract: stdout returns machine-readable JSON envelopes for agent parsing.
• Persistent state: Default stored in ~/.checkpointflow/ for cross-session recovery.
• Location-agnostic: Workflow files can be stored anywhere (repo, temp dir) decoupled from runtime storage.
• Narrow runtime contract: Simplified, predictable interface for agents/tools. Key step types: Core (cli, await_event, end) and control flow (api, switch, foreach, parallel, workflow). State management separates workflow files from runtime state (stored in ~/.checkpointflow/runs.db and ~/.checkpointflow/runs/<run_id>/).

Installation: Use uv tool: uv tool install checkpointflow (verify with cpf --help). For Python projects: uv add checkpointflow. Workflow Example: YAML definition for publishing Confluence page updates (includes cli steps, await_event for approval, conditional transitions). Execution Flow:

1. Validate: cpf validate -f workflow.yaml.
2. Run: cpf run -f workflow.yaml --input @input.json.
3. Resume: When waiting (exit code40), use cpf resume --run-id <id> --event <name> --input @response.json. Exit Codes: Standardized (0=success,10=validation error,20=runtime error,40=waiting, etc.).

Tool Comparison:

Tool	Checkpointflow Differences
Bash scripts	No pause/resume, no validation, no structured handover
GitHub Actions/CI	No explicit human approval, no cross-session recovery
Temporal/Cadence	Lighter runtime, lower learning curve, no heavy infra reqs
Conversational agents	Explicit state, auditable, reliable handover
Real-World Scenarios:

• Infrastructure change management: Plan → approve → apply → validate.
• Content publishing: Draft → review → publish/reject.
• Data pipelines: Extract → transform → quality check → load.
• AI agent collaboration: Agent A analysis → Agent B input → Agent C action.

Checkpointflow evolves workflow automation from implicit state to explicit contracts, session-bound to persistent recovery, single-driver to multi-agent collaboration. It provides a deterministic, verifiable, recoverable execution environment for AI agent era automation. For devs: Simplifies human-involved automation. For ops: Reliable change management/approval. For AI agents: Standardized interaction protocol and state management. As AI agents become more important in software dev and ops, Checkpointflow will play a key role in advancing human-AI collaborative workflows.