I started with a simple assumption: if one coding agent was useful, several
coding agents working in parallel would be even better.
Like most, I figured out that works until a point where you are just copying and pasting outputs between sessions, and sessions would get worse on delivering as time and context grew.
Codex, Claude Code, and GitHub Copilot could each write, research, review, or test a bounded piece of work. The problem was everything between those pieces.
Agents duplicated effort, missed repository-specific instructions, reviewed stale changes, and returned individually plausible results that did not form a coherent whole.
I had created more execution capacity, but I had also made myself the
scheduler, message bus, status dashboard, and integration queue.
That problem eventually became Agentflow: an open-source, provider-neutral CLI for coordinating coding agents around an approved goal.
The problem was coordination, not intelligence
The first failure mode was easy to spot. If I divided one content creation task among several writers, every individual edit could look reasonable while the complete experience lost its voice, transitions, or teaching sequence.
My issue was the lack of true shared state between agents and models that I was running.
A long-running piece of work was spread across:
- the controller's chat history;
- Markdown plans and handoff files;
- agent sessions and terminal panes;
- Git branches and worktrees;
- pull requests and CI; and
- whatever I could remember when an agent stopped or a chat disconnected.
None of those was a reliable workflow graph. A terminal output could tell me that an agent had exited, but not that its result was accepted. A claimed task did not prove that a worker was alive. A passing test did not prove that every acceptance condition had evidence.
The natural response is often to write a larger prompt, which was never going to solve the issue. It made the controller more expensive and turned its context window into an increasingly fragile database.
The solution I chose
I decided to separate coordination from execution.
Agentflow uses Beads as durable task state: goals, dependencies, claims, decisions, review stages, and acceptance evidence. Agentflow adds the control plane around that graph:
- one approved root goal;
- one persistent, resumable controller lease;
- exact, atomic task claims;
- bounded provider-neutral handoffs;
- model, skill, base-commit, scope, and budget preflight;
- structured worker results and review dispositions;
- deterministic waiting for CI or other external state; and
- explicit completion or human-action-required outcomes.
The coding agents remain disposable execution contexts. Git and GitHub remain the integration boundary. Repository instructions and domain skills remain the source of truth for the work itself.
human-approved goal
|
v
Agentflow controller <----> Beads task and evidence graph
|
v
typed preflight and bounded handoff
|
+----> Codex
+----> Claude Code
+----> GitHub Copilot CLI
|
v
isolated worktree or bounded directory
|
v
structured result -> review -> validation -> integration
Agentflow is not trying to become another coding agent, and it does not replace project expertise. It decides what is ready, who may
own it, what evidence must come back, and whether the overall workflow may advance.
Originally I wondered if just having beads was enough, but unfortunately I needed that external harness outside of all the model specific tooling, that could become a co-ordinator. Plus some other features.
Why not just use agent teams or more terminal tabs?
Native subagents are useful, and observable terminal sessions are useful. I use both, but found neither is durable project state.
Agentflow can launch observable external sessions through Herdr, or work with native provider capabilities, but a session is only an execution lane. The controller still has to validate the launch, reconcile the result, disposition review findings, and decide whether the root goal is complete.
This also means a dropped IDE connection, a sleeping laptop, or a provider error does not require a new plan. A fresh chat can reattach to the same root, inspect the durable state, reconcile completed work, and continue without replaying the old transcript.
I had a ChatGPT outage during a particular long session, a lot of things in the session folder were just left in a weird state that was a nightmare to get the existing session to recover from. Again, with agentflow and beads, I'd hope to avoid those issues in the future.
What Agentflow became
The project grew from a set of personal prompts and scripts into a public CLI with:
- Git-backed and Gitless workflows;
- adapters for Codex, Claude Code, and GitHub Copilot CLI;
- configurable local or project skills;
- persistent controller recovery and context rotation;
- optional Herdr session tracking;
- pull-based workers and staged review;
- acceptance-to-evidence matrices;
- exact-base worktrees and safe integration checks;
- deterministic CI watchers;
- local usage and provenance indexes that do not copy full transcripts;
- fail-closed model and asset policy; and
- a conditional prose-quality lane for reader-facing content.
The prose lane came from another practical lesson. A model can write correct documentation while still producing far too much of it. I'm looking at you Claude Opus 5 who likes to spout absolute word-salad into anything it produces.
Agentflow can first run free deterministic checks, then—only when the workflow opts in—route one bounded editing pass through a configured model. The original writer does not get an unlimited rewrite loop.
The result is not “press a button and trust a swarm.” It is a way to let several agents contribute without giving any worker authority over the whole outcome.
Install the public preview
Agentflow is available from
GitHub.
At the time of writing, 0.0.4 is a public preview intended for development and testing—not unattended privileged automation.
Let's be honest, I'll never claim production-ready for something I built on the back of a late night idea, and nobody is paying me to support. =D
You need Python 3.10 or later, Beads 1.1 or later, Git for Git-backed projects, and at least one supported coding-agent CLI. Herdr and the GitHub CLI are optional.
Install the versioned preview with uv or pipx:
uv tool install "git+https://github.com/saintdle/agentflow.git@v0.0.4"
# Alternatively:
pipx install "git+https://github.com/saintdle/agentflow.git@v0.0.4"
Verify it, then preview and install its provider-neutral workflow assets:
agentflow --version
agentflow doctor
agentflow install --dry-run
agentflow install
Agentflow preserves existing provider files for review instead of silently
replacing them.
A quick terminal workflow
In an existing Git repository:
cd /path/to/project
agentflow init . --beads
agentflow beads status .
agentflow doctor
Initialization creates missing workflow adapters, keeps runtime state out of Git (by configuring a .gitignore), and leaves existing agent instructions and hooks in place.
Once you have created and approved a Beads root and its task graph, start the persistent controller from the terminal:
agentflow controller start \
--root "$PWD" \
--workflow-root <approved-root-id> \
--controller agentflow-controller
Without --once, the controller continues through ready work, result
collection, review, remediation, validation, and local integration until it reaches GOAL_COMPLETE, USER_ACTION_REQUIRED, a durable task block, or its deadline.
The repository includes a complete
first-workflow tutorial
showing how to create the root and task, attach acceptance evidence, inspect a halt, and complete the workflow.
Use it from a Codex or Claude chat
You do not have to operate the lower-level commands yourself. And this is how I consume agentflow most days.
Open the target project in your IDE, start an agent-mode Codex/ChatGPT or Claude session with
terminal access, and ask it to prepare the workflow:
Use the installed shape-goal, to-tickets, and orchestrate-agents skills with Agentflow for this workspace.
Goal: [describe the outcome]
Inputs: [files, issues, feedback, or specifications]
Constraints: [write boundaries, allowed tests, model/provider choices, and any
push, merge, deployment, hosted test, or external action requiring approval]
Inspect the repository and its relevant instructions and domain skills. Create
one measurable goal contract and a dependency-aware Beads graph with exact
ownership, model routes, budgets, review lanes, acceptance evidence, and halt
conditions. Persist the proposal, but do not claim tasks, launch workers, edit
implementation files, push, merge, or mutate hosted state. Explain the plan in
ordinary language and finish with one exact approval message.
To be honest I've had much success with being less verbose than this such as the below in codex chat session:
I want you to research all the VMware topics at veducate.co.uk and compare to recent posts on reddit.com/r/vmware, tell me which new blog posts would be useful for veducate.
Use $orchestrate-agents for this research work, save output in $directory
The response will provide you the opportunity to review the proposed goal and boundaries. If they are correct, approve the root
in the same chat or a fresh controller chat:
Approved. Use Agentflow root [root-id] in the workspace currently open in the
IDE. Treat its persisted contract, graph, permissions, model routes, evidence
lanes, and halt conditions as authoritative.
Acquire or reattach the single root-controller lease and run the persistent
controller without --once. Continue through ready implementation, result
collection, independent review, accepted remediation, deterministic validation,
integration, and local delivery. Stop only at GOAL_COMPLETE,
USER_ACTION_REQUIRED, a durable task block that needs my decision, or the
persisted deadline. Do not push, merge, deploy, run hosted tests, or mutate
hosted state unless the contract explicitly authorizes it. Never make me relay
routine worker output between chats.
That last sentence addresses the original problem directly. The human approves
the goal and consequential actions; the controller handles routine coordination.
Or again, you could work in a simplier format
goal approved
The full
chat-first guide
also includes prompts for reconnect-safe resume, read-only status, context
rotation, and a separately authorized pull-request delivery step.
Bring your own skills
Agentflow's bundled skills deal with workflow rather than your product domain.
You can register a repository skill or an explicit local skill source without repackaging the CLI:
agentflow skills add ./skills/my-domain-skill
agentflow skills sync
agentflow skills list
agentflow skills doctor
This was an important design correction for me. The general orchestration skill implemented by Agentflow should never outrank the repository's own technical or editorial knowledge.
Agentflow routes the correct domain skill into the bounded task and pins what the worker actually received.
The longer build story
I documented the design as it evolved on vEducate:
- Building a Coding-Agent Scheduler with Codex, Claude Code and GitHub Copilot covers the original coordination problem, early controller design, work allocation, review, CI, and integration.
- How to Build a Durable Coding-Agent Scheduler with Beads covers the move from Markdown and chat state to a durable dependency graph, pull-based work, resumability, deterministic waiting, and stronger evidence boundaries.
Agentflow is the culmination of those experiments: the reusable CLI, skills, policy, tests, documentation, and release process extracted from the workflow I had been using locally.
It is still early software. The repository is explicit about its AI-assisted authorship and its development/testing status (Yes I used agentflow to help develop itself further).
If you try it, review the plan, permissions, diffs, and evidence just as carefully as you would review the work of any other automation.
The project, installation guide, examples, and issue tracker are all available
at github.com/saintdle/agentflow.
Top comments (0)