Skip to content
Bahman Shadmehr Independent AI Systems & Automation Engineer

Resumable AI workflows

Every run is a folder you can open, resume or fork.

Run AI workflows of plain-function steps as self-contained run folders, with resume, fork, partial runs and human gates.

Prevents: A crash on item 37 forces a rerun from item 1, a changed prompt leaves stale outputs marked done, and review notes never reach the step that needs them.

Open the source Read the docs

Why it exists

The failure appears after the happy path.

Generative pipelines are slow, costly and partly random; scripts lose state and platforms bring servers.

Scope. A library and CLI; no server, scheduler or database.

Five-minute orientation

See the smallest complete path.

pip install "git+https://github.com/honeworks/hone-flow"

Real output

What it looks like running.

Terminal: hone-flow lists two runs of a local story-room pipeline; one completed run shows 131 steps done and 682 not selected; its folder holds one folder per step.
Real terminal output from my local pipeline on 2026-09-30, rendered as an image. One personal pipeline, not a production deployment.

Architecture

The architecture is a set of promises.

The graph comes from parameter names. Each step writes outputs first and metadata last into its own folder; the manifest and spans.jsonl sit beside them. Resume and fork read the folders; a read API opens runs without the workflow's code.

  • A step folder with metadata.json is complete. Inspect test
  • Resume never mixes step versions in one run. Inspect test
  • Reused results are labelled reused. Inspect test
  • Every attempt, including failed and rejected ones, stays in the run. Inspect test

Core concepts

The few concepts you need before reading the code.

Run folder

The complete record of one run: manifest, step folders, spans and reports.

Why. State you can open and understand without the code.

Boundary. It's local or S3 storage, not a database.

Fork

A new run beside an old one that copies what didn't change and explains every rerun.

Why. Iterate on one step without paying for the rest.

Boundary. Reuse is explicit; there's no automatic cache.

Gate

A persisted pause where a person approves, edits or rejects with a note.

Why. Stop spending GPU time on outputs a person would reject.

Boundary. The producing step receives the note and its previous output.

Operations

What happens after install.

`hone-flow runs / status / show / approve / reject / edit / resume / fork / pin / cleanup`, each with --json.

Current boundary

What this project does not solve.

Alpha. No concurrent steps, no dynamic fan-out during a run, no replay inside a step, no protection for external side effects.

Near-term roadmap. Follow the design history in design/changes/.

What it implements

  • plain typed function steps
  • run folders on local disk or S3
  • commit per step
  • resume
  • fork with explained reruns
  • partial runs
  • human gates with review notes
  • notifications
  • measurements
  • read API

Engineering checklist

What the repository ships.

Quickstart
Present
Success tests
Present
Failure tests
Present
Architecture notes
Present
Security notes
Not published
Runbook
Not published
Limitations
Present
Changelog
Present

Recent changes

What changed, with the commits.

  • Claude Code workflow added: skills, hooks, settings Commit
  • Hook wiring tested; publishing denied in all its forms Commit

Go further

Need the control, not just the component?

Fit it to the system that has to survive.

The repository exposes the mechanism. Production work is defining the permissions, data, failure costs, evidence, and owners around it.

Let's build something real