Stop giving the agent a workflow. Put the agent inside the workflow.
Agent Runner is finally out in the world. You can try it here: github.com/Codagent-AI/agent-runner.
I've been promising for weeks that my agent workflow tool would drop by the end of May. Claude Code also released workflows in late May. Coincidence, or has someone from Anthropic been reading my newsletter? I guess we'll never know for sure...
So yeah, I wasn't sure how to feel at first when Claude released a feature that, at least on the surface, looks a lot like what I've spent so many late nights on. But up until this week, few besides me were even talking about agent workflows. I'd much rather have the conversation move past whether you need workflows and toward which workflow orchestrator is right for you.
In this article, I'll explain how both tools work and what problems each is best suited for.
The Surface Level Similarity
To find out what Claude Workflows actually are, I ran an experiment. I took my own simple-change workflow from Agent Runner and ported it to a Claude workflow: scout a small change, plan it, implement it with TDD, then have AI review the result.
The first thing I noticed: Claude's workflow UI is eerily similar to mine. Like, nearly identical. My jaw dropped for a moment. Here is what they look like.
Claude Workflows: the ported simple-change run, with phases on the left and step progress in the main pane.
Claude Workflows: drilling into the plan step shows the prompt, activity, outcome, model, tokens, and tool calls.
Agent Runner: the original simple-change workflow with the interactive plan step selected and its prompt/session details visible.
The anatomy is the same on both sides. A tree of phases and steps down the left. A detail pane on the right with the actual prompt that ran, the model, and the timing. A cursor on the selected step. And when a run stops, you resume it instead of starting over. Same muscle memory, drilling into a run to see what each agent actually did.
Did someone at Anthropic have Agent Runner open in a tab? Probably not. More likely it's convergent evolution: once you put the agent inside the workflow, this is roughly the view you end up drawing.
Once I started to dig deeper, the differences became apparent. My plan step stops to ask me what to build, and a Claude Workflow has nowhere to put a question like that, so it couldn't survive the port. It just vanished.
The steps don't share a session either. Each one is a fresh agent with its own context window, carrying forward only what the previous step wrote down and passed along as text. Unlike with Agent Runner, there's no way a later step can resume an earlier agent's session, full context intact.
The actual results? The Claude workflow worked. It found a real gap, wrote a test, got everything green, committed, and had reviewers try to tear it apart before signing off.
But the experiment also showed the two tools aren't doing the same job. To see why, let's look at how each one actually works under the hood.
Claude Workflows: Subagents as Code
Claude Workflows are JavaScript programs that run inside Claude Code. The script declares phases, calls agent() to start subagents, and uses normal code for the control flow: variables, conditionals, loops, parallel(), pipeline(), whatever the task needs.
That is the important move. The orchestration lives in code, while the model handles the judgment inside each step.
Here is the top of the workflow I ran:
export const meta = {
name: 'simple-change-trial',
phases: [
{ title: 'Scout', detail: 'find one small, safe candidate change' },
{ title: 'Plan', detail: 'turn the candidate into a concrete task' },
{ title: 'Implement', detail: 'implement with TDD in the worktree and commit' },
{ title: 'Validate', detail: 'independent reviewers try to refute the change' },
],
}
Those phases are also what the progress UI draws. The script gives Claude Code a real structure to display and resume.
Each unit of work is an agent() call:
phase('Scout')
const candidate = await agent(
`Read the codebase and propose ONE small, safe change. ...`,
{ label: 'scout', schema: CANDIDATE_SCHEMA },
)
At the level Claude exposes, that starts a Claude Code subagent with its own context window and tools. The exact runtime internals are Anthropic's, but the composition unit is clear: you are composing agents. The schema option forces a structured result, so the next step can consume data instead of parsing vibes from prose.
State moves through the script as variables:
const plan = await agent(
`A scout proposed this change:\n${JSON.stringify(candidate, null, 2)}\n\nProduce a minimal plan...`,
{ schema: PLAN_SCHEMA },
)
The scout returns candidate. The planner receives candidate and returns plan. Later steps receive the plan the same way. The main chat does not have to carry every intermediate result.
Claude Workflows are especially strong when you want to fan work out to multiple agents:
phase('Validate')
const reviews = await parallel(
LENSES.map((l) => () =>
agent(`ADVERSARIALLY review this change through the "${l.key}" lens. Default to skepticism...`,
{ schema: REVIEW_SCHEMA })),
)
const overall = reviews.some(r => r.verdict === 'reject') ? 'reject'
: reviews.some(r => r.verdict === 'concerns') ? 'concerns'
: 'approve'
That fired three reviewers at the same change, gathered their structured results, and let plain JavaScript tally the verdict. No prompt gymnastics. No asking one agent to remember which reviewers it launched. The workflow script owned the coordination.
There is one important boundary. The JavaScript is the conductor, but the subagents touch the repo. The script itself does not directly edit files or run shell commands. It asks subagents to do that work, then receives their results.
That makes Claude Workflows especially natural for big, headless jobs: codebase sweeps, migrations, broad research passes, and adversarial review from multiple angles. In my trial, it was very good at that shape of work.
Agent Runner: Processes as Workflow Steps
Agent Runner starts from a different primitive: a workflow step is a process.
Sometimes that process is an agent CLI, like Claude Code, Codex, or opencode. Sometimes it is a plain shell command, like make test, agent-validator, git, or a project script. Agent Runner builds the command, runs it, captures the output, and decides what step comes next.
Agent Runner ships with workflows for common developer loops, including simple-change. They are YAML files you can run as-is, copy, edit, or replace with your own.
Here is the start of the built-in simple-change workflow:
name: simple-change
description: "Quick plan + implement + validate workflow, okay for small changes"
sessions:
- name: lead-agent # a named, explicit session reused across steps
agent: planner
The workflow is authored once as YAML. It also declares a named session, lead-agent, which gives later steps a handle back to the same agent conversation.
That agent: planner line points at an agent profile in ~/.agent-runner/config.yaml:
profiles:
default:
agents:
planner:
default_mode: interactive
cli: claude
model: opus
effort: high
The first step is a normal shell command:
- id: guard-clean-tree
command: |
agent-validator detect; status=$?; if [ $status -eq 0 ]; then echo 'Unvalidated changes detected. Run agent-validator before planning.' >&2; exit 1; elif [ $status -ne 2 ]; then exit $status; fi
No model needed. Before any planning starts, Agent Runner checks whether there are unvalidated changes and stops if the worktree is not ready.
Then the workflow moves into the interactive planning step:
- id: plan
session: lead-agent
prompt: |
Help the user plan the change. First, ask the user what the change
is about. DO NOT attempt to guess. Then use the codagent:simple-plan skill.
This is the line that disappeared when I ported the workflow to Claude Workflows. In Agent Runner, the human can be a step in the route. The agent stops, asks what to build, and continues from there. Planning writes a task file, and Agent Runner captures its path into task_file so later steps can use it.
Then, implementation runs in a different agent profile:
- id: generate-code
agent: implementor
session: new
mode: autonomous
prompt: |
Implement the task described in {{task_file}}. You MUST use the codagent:implement-with-tdd skill. When you are done implementing, commit your changes following the project's commit message conventions and prepend [{{step_id}}]. Then summarize to the user what you changed.
That is the multi-agent part in action. Planning uses a Claude Code interactive session; code generation uses headless Codex. Both live in the same workflow, alongside shell commands.
Workflows can also call other workflows:
- id: run-validator
workflow: ../core/run-validator.yaml
params:
task_file: "{{task_file}}"
continue_on_failure: true
That validator step is a reusable route of its own: run checks, run review agents, fix failures, retry with bounds. continue_on_failure lets the parent workflow keep control when validation reports problems. No prompt has to remind an agent how the loop works.
That is the core difference in the building block. Claude Workflows compose subagents. Agent Runner composes commands. A command can be an agent, a validator, a build, a test, or another workflow. If it has a CLI, Agent Runner can run it as a workflow step.
The tradeoff is that Agent Runner is less focused on large parallel fan-out (right now). The payoff is that the route is durable, portable, and reusable for the daily engineering loop.
Different Tools for Different Kinds of Workflows
Here's my take: Agent Runner is better for common developer workflows because it can mix multiple agents with normal shell commands, builds, tests, and git. Claude Workflows are more flexible and powerful as a programming model because they are JavaScript, not declarative YAML.
Agent Runner is a portable route for the daily engineering loop. Claude Workflows are built for big headless sweeps inside Claude Code.
Here's a full comparison:
Dimension | Claude Workflows | Agent Runner |
|---|---|---|
Best job | Fire-and-forget batch work: repo sweeps, migrations, broad research passes, multi-angle stress tests. Great when you want many agents working in the background and code-level orchestration flexibility. | Common developer workflows: spec, build, validate, fix, review, ship. Great when the route needs agents, shell commands, validation tools, and git in one repeatable loop. |
Composition atom | In-runtime Claude Code subagent. Each | CLI process or shell command. A step can be an agent, a validator, a test command, a git command, or another workflow. |
Authorship | JavaScript generated or saved for a task. More flexible than YAML: variables, loops, conditionals, | YAML route authored once and reused. Less flexible as a programming model, but clearer for standard developer workflows that should run the same way every time. |
Human checkpoints | Headless by design. The docs recommend splitting work into separate workflows when you need a human checkpoint. | Interactive steps and signal files can make the human a step. The |
State | Pass prior outputs through JS variables. The script can hand | Capture stdout into variables and interpolate them with |
Session | Fresh subagent context per | Named sessions can be new/resume/inherit across steps and sub-workflows. A later step can reattach to the agent that wrote the plan or the code. |
Parallelism | Native | Sequential by design today. I designed parallel task execution and shelved it because most changes are relatively small and parallel support requires a local merge queue. |
Token usage | Anthropic warns workflows can consume substantially more tokens. My small trial used about 264,000 tokens to land a 51-line test. | Lower orchestration token spend for common workflows because the route is already written and shell commands can run with no model overhead. |
Shell/CI steps | Subagents can run tools, but the JS script itself has no direct shell/filesystem access. The script coordinates agents that touch the repo. | Shell commands, validators, builds, tests, git, and agents are all workflow steps. No model needed for a normal check, and no prompt needed to remember CI hygiene. |
Vendor surface | Deep Claude Code integration. Excellent if the team is already all-in on Claude Code. | Any CLI agent with an adapter. A workflow can use Claude for one step, Codex for another, and a shell command for the next. |
Paved road | Powerful primitive. Teams can save workflows, parameterize them, and build their own paved roads on top. | Batteries-included SDD/validation route. A checklist says "remember to validate." A paved road makes validation the next turn in the route. |
Workflows Work
The category is real now. A week ago, I still had to explain what I meant by an agent workflow. Now Anthropic has shipped one, people are trying it, and the conversation can move from "do I need that?" to "which workflow tool fits this job?"
That is good for the whole category. It means less time arguing that workflows belong outside the chat transcript, and more time talking about the shape of workflow you actually want. There is room for both: Claude Workflows for huge headless sweeps inside Claude Code, Agent Runner for a durable, portable route through the daily engineering loop.
Anthropic moved the loop out of the context window. Agent Runner moves it out of the vendor.
Try It Out
Agent Runner is still an early release, and I'd love feedback from people running it on real workflows. Try it here: github.com/Codagent-AI/agent-runner.
Report issues on GitHub, or message me on Discord at paulcaplan_75433.
And if you like what you see, please give the repo a star and share the newsletter with others who'd find it helpful.