Skip to main content

flow-atelier

Flow Atelier

Write down how a job gets done. Let AI agents do it, the same way, every time.

Flow Atelier runs recipes, called conduits, written in one short YAML file. Each step is a shell command, an AI coding agent such as Claude Code or Codex, or a question for you. Steps run in parallel when they can, loop until tests pass, and save every run to disk, so you can leave a job running overnight and read exactly what happened in the morning.

It runs on your machine and uses the agent logins you already have. No API keys are configured, stored, or proxied by Flow Atelier. Check your provider's terms before you run agents unattended: see Agent logins and provider terms.

Try it in a minute

curl -fsSL https://raw.githubusercontent.com/Andesprit/flow-atelier/main/install.sh | bash
cd your-project
atelier init           # finds the agents you have installed and writes starters
atelier serve          # in a second terminal: the live dashboard on :8000
atelier run explain    # your agents read the project and brief you
atelier run pair       # one agent drafts a change, another answers and reviews it

With Claude Code and Codex both installed, explain has them read the project in parallel and then merges their answers into one brief. Without an agent, atelier run hello --input name=world shows the basics.

pair shows agents working with each other. With both installed, Claude Code proposes a change, Codex answers Claude's questions and reviews the proposal, and Claude revises in the same conversation. It uses the conduit-wide interaction policy and a shared session. Nothing is edited; you get the final plan and diff. Windows and PyPI installs are in the guide.

What people run with it

  • Overnight goal loops. Give it a goal at night. An agent plans, another builds and fixes until the tests pass, reviewers check the result, and you read the report in the morning.
  • Conductor and worker. Codex plans and reviews while Claude Code writes the code, each with its own login, handing work back and forth.
  • Review panels. Two agents review the same change in parallel and a third merges their findings before you commit.
  • Media pipelines. Shell steps run tools such as ffmpeg, an agent makes the editing calls, and you approve before the final render.
  • Plain automation. Scheduled reports, polling with backoff, and deploys with a human approval gate. Atelier works with no AI at all.

What a conduit looks like

name: ship
description: Plan with Codex, build with Claude until tests pass, then ask me
inputs:
  goal: What to build
tasks:
  - plan:
      description: Codex writes the plan
      tool: harness:codex
      task: "Plan how to achieve this goal: {{inputs.goal}}"
      depends_on: []
  - build_until_green:
      description: build and test until green
      tool: tool:conduit
      depends_on: [plan]
      repeat: 5                          # loop up to 5 times...
      until: output.match(TESTS PASSED)  # ...until the tests pass
      on_exhaust: fail                   # still red after 5? stop here
      inputs:
        goal: "{{inputs.goal}}"
        plan: "{{plan.output}}"
        feedback: "{{loop.previous}}"
      tasks:
        - build:
            description: Claude Code makes the change
            tool: harness:claude-code
            task: "Goal: {{inputs.goal}}\nPlan: {{inputs.plan}}\nLast test run: {{inputs.feedback}}"
        - test:
            description: run the tests
            tool: tool:bash
            depends_on: [build]
            task: "make test && echo 'TESTS PASSED'"
  - approve:
      description: you decide
      tool: tool:hitl
      task: "Tests pass. Ship it?"
      depends_on: [build_until_green]
      inputs:
        answer: "Type yes to ship"

Save it as .atelier/conduits/ship/conduit.yaml and run atelier run ship --input goal="add dark mode". Swap any step's agent for one run with --agent build_until_green.build=codex.

What it looks like

The designer lays a conduit out by dependency depth, so each column is a set of steps that can run at the same time:

Designer

Runs stream to the dashboard, including the human-approval gates:

Dashboard

How it compares

Flow Atelier n8n / Zapier Prefect / Dagster / Airflow GitHub Actions
Runs where your machine, local-first hosted / self-hosted server scheduler + workers CI runners
AI steps a first-class task type, using your own agent CLI login LLM API nodes, you supply keys you write the client code you write the client code
Human-in-the-loop built in, mid-DAG, blocks the run via external forms/webhooks not really manual approval on environments
Workflow format one simple YAML file per conduit JSON built in a GUI Python YAML
Loops & retries repeat / until / while / retries on any task loop and wait nodes in the GUI Python control flow matrix builds; no retry-until
State plain files under .atelier/ a database a database opaque to you

Pick Flow Atelier when the work is a repeatable recipe you want AI agents to execute on your own machine, with you in the loop at the points that matter. Pick the others when you need multi-tenant hosting, distributed workers, or enterprise scheduling — flow-atelier deliberately does none of that.

Note on scope. flow-atelier runs shell commands and AI agents on the machine it is installed on. It is a local developer tool, not a hosted multi-user service. See Security before exposing it on a network. Agents run with full permissions by default, so they can edit files and run commands. See agent permissions to limit them.

Why processes, not agents

Flow Atelier is built on a simple premise: the world doesn't run on people, it runs on processes that people execute. Ask someone to make anything, for example: the best yogurt in the world, what a person will do is that they'll research, experiment, and produce something average. The same is true of an AI agent. But give that person a clear, step-by-step recipe — and keep refining it over time — and you can reach the best yogurt in the world. That's what Flow Atelier does. We help you build simple, repeatable instructions for getting something done the same way every time, then let anyone improve on them. It mirrors how real businesses actually work. Coca-Cola and Pepsi don't differ because their managers, lawyers, or engineers are fundamentally different people — they differ because their processes are different. Flow Atelier gives you the tool to design and refine those processes. The difference: instead of people executing them, AI agents do the work.

The words we use

A few terms show up everywhere in the docs:

  • Conduit — a recipe. An ordered set of steps written in a single YAML file.
  • Task — one step in that recipe. A task runs a shell command, asks a person a question, calls an AI tool, or runs another conduit.
  • Flow — one run of a conduit. Every run is saved to disk, so you can always go back and see exactly what happened.
  • Harness — an AI coding tool (Claude Code, Codex, opencode, Copilot, Cursor) that a task can hand work to.
  • HITL — "human in the loop": a step that pauses to ask a person a typed question, then continues with the answer.

Learn more

Contributing

For test instructions, the project layout, and internal architecture notes, see DEVELOPMENT.md. To report a security problem privately, see SECURITY.md.

Metadata

Release files for flow-atelier 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flow-atelier 0.14.0
File Size Uploaded Provenance Actions
flow_atelier-0.14.0.tar.gz 2.8 MB With provenance Details for flow_atelier-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flow-atelier 0.14.0
File Interpreter ABI Platform Actions
flow_atelier-0.14.0-py3-none-any.whl Python 3 none any Details for flow_atelier-0.14.0-py3-none-any.whl

Total release size: 4.0 MB

Release files / flow_atelier-0.14.0.tar.gz

Download URL flow_atelier-0.14.0.tar.gz
Size 2.8 MB
Tags Source
SHA-256 checksum
How to use checksums
d8a05404ce2c47aac6a36ae1fd50623dc3099fa8db6070eb8ee8167363fa16cb
BLAKE2b-256 checksum
How to use checksums
1b3f0082698afde931798c5711720e010f0d9b720ab224d069c7de4762be49d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / flow_atelier-0.14.0-py3-none-any.whl

Download URL flow_atelier-0.14.0-py3-none-any.whl
Size 1.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
21ae3c7ea4b6519e938dbc7d764f6b793be19534e477df4bd8655b157905a4ae
BLAKE2b-256 checksum
How to use checksums
e242d13447cab4291f143945f9f64a0b0c9f3fcf1563809553e5e22eb9a34e56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for flow-atelier 0.14.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for flow_atelier-0.14.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page