Checkpoint

Investigate failed Python workflows with their inputs and recorded HTTP still attached. Run a controlled input experiment, compare it with the original, and hand someone a reproduction they can execute locally.

I built Checkpoint around a small debugging problem: a supplier changes items to products, the fetch succeeds, and the next step fails. A log gives you the exception. Checkpoint keeps the input, response, attempt history and step relationships together so you can try a change without overwriting the evidence.

Try the recorded investigation · Install and run · Connect your workflow · Architecture

checkpoint.mp4

The browser demo opens with an introduction and a four-step recorded walkthrough: inspect the failure, view the replacement input, see the completed result and compare both runs. Next, previous and restart controls keep the route visible. It contains real runs of fictional examples; new execution runs on your own computer. Review export also opens the captured inspection files; saving a ZIP remains a local action.

A complete investigation

1. Record the supplier example. fetch succeeds; normalize rejects the changed response. Open the failing step to see its input and error.
2. Replay it. Python executes again, using the recorded supported HTTP response. A missing recording stops replay instead of sending a live request.
3. Branch at normalize. Rename products to items in the replacement input, then create the experiment. The successful prefix is inherited; the suffix executes again. The original stays failed and unchanged.
4. Compare the original and child. Step identities align, with the replacement, outputs, status and attempt counts available beside the JSON differences.
5. Review and export either observation. Open the actual file inventory, source, stored headers and response bodies before saving. The engine checks that the selected contents have not changed since review. An executable ZIP includes explicitly selected code, data, recorded responses, hashes and a verifier. A separate inspection mode does not execute code on import.

This is an input experiment, not a source-code fix. The example's validator still rejects the changed shape until you change the workflow itself and record a new run.

Run locally

Download the archive for your platform from Releases. Version 0.2.0 targets Windows x64 and Linux x64. Python 3.11 or later must be available; the release includes the interface, examples and SDK wheel.

Extract the archive, open a terminal in its directory, then:

# Windows PowerShell
.\checkpoint.exe serve --python python

# Linux
./checkpoint serve --python python3

Open the printed address, normally http://127.0.0.1:3038, and choose Investigate the example. The built-in examples need no account, key or external service. The engine bundles the runner; you do not need to install the SDK to try them.

Stop with Ctrl+C. Starting again with the same data directory reopens history. Use --data ./checkpoint-data to choose a directory. Defaults and recovery steps are in operations.

To define your own workflows, install the included wheel in a virtual environment and start the engine with that environment's Python. The own-workflow tutorial walks through a separate order-checking module, a selected JSON file, an intentional failure and a successful branch.

Keep your HTTPX client

In v0.2, existing client code can record through an explicit transport:

from checkpoint_sdk.httpx import CheckpointTransport

with httpx.Client(transport=CheckpointTransport(ctx), timeout=None, trust_env=False) as client:
    response = client.post(url, json=payload)
    response.raise_for_status()
    return response.json()

Install the SDK's optional httpx extra. Sync and asyncio adapters use the same recording broker and strict replay rules. The complete invoice example records an ordinary billing client, stops its local service, reproduces a changed-price-field failure, and completes a corrected input branch with a total of 6,885 cents. Both observations can be exported and reproduced elsewhere.

Export now opens a file-by-file review rather than saving immediately. You can read captured responses without decoding base64 yourself, inspect selected source/data and choose an executable or inspection-only bundle. Nothing is automatically redacted.

What is implemented

Part	Responsibility
Go engine	Sequential DAG execution, bounded concurrent runs, process supervision, supported HTTP brokerage, replay, branching, comparison and exports
Python SDK	Explicit step registration, JSON values, explicit HTTP, optional HTTPX sync/async transports and fresh worker execution
SQLite and artifacts	Transactional run/event snapshots, operation intent/result records and content-addressed evidence
React / TypeScript	Resizable path/evidence workspace, original/experiment paths, step navigation, JSON inspection, replacement planning, aligned differences, operation provenance and file-by-file export review

The map follows the declared dependencies. Select a step or use the navigation strip to inspect it; double-click a node to focus. On an input experiment, Original path reveals the parent's failed path beside the new results. Compare with original opens the actual JSON differences. A step list provides the same selection without navigating the canvas.

I chose a fresh Python process per step to make cancellation and failure boundaries explicit. That costs startup time; the measurements separate it from the equivalent direct Python workload. I also keep remote effects separate from local persistence: an interrupted request can be uncertain, and is never automatically repeated as though nothing happened.

Boundaries worth knowing

• Workflows declare 1–128 steps in dependency order. Steps execute sequentially within a run; up to four runs execute concurrently.
• Replay covers ctx.http() and clients using the Checkpoint HTTPX transports. Files, time, randomness, unconfigured HTTP clients and other Python effects remain under your code's control.
• Code and declared source/data hashes must match for replay. A branch replaces the selected step's whole JSON input and inherits the earlier successful prefix.
• Python code is trusted local code, including module import during inspection. Process supervision and loopback session checks do not make it a sandbox.
• Captured values, logs, URLs and response bodies may contain sensitive data. Review an export before sharing it. Hashes provide integrity, not anonymization.
• There is no distributed execution, automatic retries of supported HTTP effects, graph-parallel steps or arbitrary framework tracing.

Execution and replay contracts · Storage, recovery and trust · Tests and verified environments · CLI / API

Build from source

Requires Go 1.27+, Python 3.11+ and Node.js 22.12+ with npm.

npm ci --prefix web
npm run build --prefix web
go build -trimpath -o checkpoint ./cmd/checkpoint
python -m pip install ./sdk
./checkpoint serve --python python

On Windows, build checkpoint.exe and invoke .\checkpoint.exe. Build the frontend first because the Go binary embeds web/dist. The development guide covers tests, the UI development server and reproducible packages.

Created by Shayan Ali. MIT license. Adapted interface resources and dependency notices are listed in THIRD-PARTY.md.