DEV Community: Szymon Paluch

Workflow Studio: observe and design Claude Code workflows

Szymon Paluch — Fri, 24 Jul 2026 12:56:41 +0000

Claude Code's Workflow tool fans out subagents in parallel and leaves the result on disk as raw logs. I built a local dashboard that reads those artifacts and renders the run, plus a block canvas that compiles back to a runnable script. Here is what it does, what it deliberately does not do, and how to install it.

The short version: Workflow Studio is a local companion for Claude Code's built-in Workflow tool. It has two halves — Observe, a dashboard that reads Claude Code's own on-disk run artifacts and draws each multi-agent run as a phase graph and a wall-clock timeline, and Author, a 12-block canvas that compiles to a real, runnable Workflow script. Both are exposed to the agent through an MCP server with nine tools. It runs on 127.0.0.1, it is MIT-licensed, and you install it with one paste. The current release is v0.2.0.

The problem: a multi-agent run is a black box

Claude Code's Workflow tool is its deterministic multi-agent primitive: you write a small JS script that fans agents out in parallel, pipes a list through stages, gates on a value, loops until a condition holds. It works. The problem starts the moment the run finishes.

A finished run leaves real artifacts on disk. Under ~/.claude/projects/<project>/<session>/subagents/workflows/wf_*/ you get a journal.jsonl, a per-agent transcript for every subagent, and a small metadata file each. That is a lot of ground truth. Nothing renders it. So you scroll. You cannot see the phases at a glance, how wide the fan-out actually went, how many tokens each agent burned, how long each one took, or which branch a gate picked when it mattered.

That is the same shape of failure I wrote about in silent failures in agentic systems: nothing crashes, so nothing tells you that eleven of your twelve verifiers returned an empty result. And it compounds on the authoring side — the only way to build one of these is to hand-write the script, and the only channel between the script you wrote and the agent that runs it is a .js file dropped on disk.

What Workflow Studio is

A locally-run companion layer, not a runtime. It ships no agents of its own and defines no execution engine; it sits on top of the one you already have. Two surfaces plus a channel:

Observe — a dashboard that passively reads Claude Code's run artifacts and renders each run as a phase/agent graph and a timeline.
Author — a no-code block canvas that compiles down to a real Workflow script.
MCP — a stdio server with nine tools, so the same Claude Code agent that runs your workflows can also read your designs, inspect the observations, and write new designs back into your builder.


12	Block kinds
9	MCP tools
127.0.0.1	Default bind
MIT	License

One thing to be clear about up front, because it shapes everything else: Workflow Studio cannot start a run. Not over MCP, not from the builder. It reads what Claude Code already produced and it hands the agent a script the agent runs with its own Workflow tool. That is a design decision, not a gap, and I explain why in the authoring section.

Observe: see what actually ran

The dashboard turns a run into a graph you can read. Phases, the fan-out, tokens per agent, the branch taken, each agent's output. Click a node and the inspector shows what that agent was given and what it returned — its prompt, its thinking, its tool calls, its output, its model, its state and how long it took, and its spawn depth.

Observe · a real deep-research run of mine — 111 agents across Scope → Search → Fetch → Verify → Synthesize, 3.7M tokens, about 22 minutes. One run on one machine, not a benchmark.

The timeline view answers the other question the graph does not: what overlapped with what. A fan-out that looks like one wide row in the graph is usually a staircase in wall-clock time, and seeing that is how you find out that your second fan-out was waiting on a single straggler from the first.

Observe · the wall-clock timeline — the Review fan-out runs first, then Verify staggers in as each agent lands.

Honest by construction. The numbers come from two different places and the dashboard says which. When Claude Code's own progress overlay is still on disk, labels, phases, states and token counts are read straight from it and the run is authoritative. When that overlay has already been garbage-collected, phases and labels are derived heuristically from the journal, and the run is flagged as such — tokens or timings that could not be measured are marked, never invented. A run still in flight is labelled live and its elapsed times are lower bounds. You are never shown a number that looks measured but isn't.

Observing is also where the next workflow usually starts. When a run turns out well, you promote it to a reusable workflow in one click — the graph you were just reading opens in the builder as a starting point, so a good pipeline becomes a template instead of something you reconstruct from memory next month.

Two practical notes. The dashboard refreshes by polling with a short cache, not by pushing — it catches up within a couple of seconds, it is not a socket. And it reads across all your projects and sessions, so old runs stay browsable long after the session that produced them is gone.

Author: build the recipe, not the boilerplate

The other half is a canvas. You drop blocks, wire the ports, and Workflow Studio compiles the graph to a real Claude Code Workflow script — the native calls (agent(), phase(), parallel(), pipeline(), log()) plus a sidecar comment holding the design. The round-trip is lossless: a compiled script reopens as the exact graph you drew, so you can edit it on the canvas, in the editor, or both, without either side losing work.

Author · the block builder — typed blocks compile to a runnable script.

There are twelve block kinds. Each one declares the shape of its output, which is what lets a downstream block branch or map on a real field instead of on a string you hope is there:

Block	What it does
`start`	The entry anchor. Two or more children run in parallel.
`agent`	One agent with a prompt.
`fan-out`	N agents running the same prompt in parallel.
`pipeline`	Each list item flows through the stages independently.
`loop`	Refine a result in place over N rounds, or until a condition holds.
`gate`	Run a branch only if a declared field meets a condition.
`switch`	Branch on a declared enum value — a k-way router.
`filter`	Keep only list items matching a field. No agent involved.
`rank`	Sort a list by a field and keep the top N. No agent involved.
`sub-workflow`	A nested workflow reused as a single block.
`input`	A fixed list of items — a source for fan-out, pipeline or rank.
`param`	A named value you can @-mention inside prompts.

You never start from an empty canvas. Every new workflow begins from one of seven built-in patterns that already exercise the dynamic primitives: Basic (agent plus in-place iteration), Classify and act (a classifier enum routing to one of several branches), Fan-out and synthesis, Adversarial verification (independent verifiers trying to refute the worker's result), Generate and filter, Tournament, and Loop until done. Pick one, then edit it.

The Run button does not run anything. The builder has a Run action, and it does not execute your workflow. It opens a dialog that says so in plain words and hands you a phrase to paste into Claude Code, then watches for the run to show up in Observe. The reason is boring and load-bearing: a server-side shell-out would turn a loopback dashboard into an unauthenticated local exec surface. I rejected that in design review and I would reject it again. Execution stays where the permissions live — in your Claude Code session.

Install it in one paste

You need uv / uvx on your PATH and Python 3.9 or newer. Nothing else — the dashboard ships pre-built inside the package, so there is no Node step.

You are probably already sitting in a coding agent. Hand it this and walk away:

Read https://github.com/hculap/workflow-studio/blob/main/AGENT_INSTALL.md
and set up Workflow Studio for me — run the steps, verify it,
and tell me whether to restart Claude Code.

Prefer to do it yourself? These two are slash commands you type in a Claude Code session — an agent cannot run them for you:

/plugin marketplace add hculap/workflow-studio
/plugin install workflow-studio@workflow-studio

On Claude Code 2.1 and newer there are shell equivalents (claude plugin marketplace add …, claude plugin install …), which is what the agent path uses. Either way, restart Claude Code afterwards — the MCP tools and the /workflow-studio:dashboard command only load on the next session. Verify with claude mcp list; you want to see the server as connected. If it shows as failed, it is almost always uvx missing from the PATH a GUI-launched Claude Code inherited.

You can also skip the plugin entirely:

# dashboard on http://127.0.0.1:8787/ (opens a browser)
uvx workflow-studio

# MCP server on stdio — register it by hand
claude mcp add workflow-studio -s user -- uvx workflow-studio mcp

One caveat worth knowing: uvx pulls the package from PyPI and the plugin pins no version, so you pick up new releases silently.

Where it fits next to LangGraph, CrewAI and n8n

Workflow Studio is not competing with those. They are a different layer of the stack. LangGraph, CrewAI, AutoGen, the OpenAI Agents SDK, n8n and Flowise each hand you a runtime to adopt, and each is portable across model providers — which is a genuine strength Workflow Studio does not have and is not trying to have. Workflow Studio assumes you already run Claude Code, and gives you a way to see what a run did and to author the next one visually.

Tool	What it is	Authoring	Observes real runs	Local · no account
Workflow Studio	Observe + author layer for Claude Code's Workflow tool. Not a runtime.	No-code canvas (12 blocks) compiling to a real Workflow script	Yes — reads Claude Code's on-disk artifacts, no SDK, heuristics flagged	Yes — loopback, no account, no telemetry
LangGraph + Studio	Provider-agnostic framework for stateful graph agents (Py/JS)	Code-first — you write the graph; Studio visualizes and debugs it	Yes, and strongly — step and time-travel debugging, deep tracing via LangSmith	Partial — library runs local; Studio wants a (free) LangSmith account
CrewAI / AutoGen	Code-first multi-agent frameworks	Code (Python / YAML); AutoGen Studio adds a capable no-code GUI	Yes or partial — you instrument the runtime (AutoGen via OpenTelemetry)	Partial — libraries local; CrewAI observability hosted-first
OpenAI Agents SDK	Lightweight code-first framework	Code only (Python / TS)	Yes — built-in tracing, on by default	Partial — traces default to a hosted dashboard; no bundled local UI
n8n / Flowise	Visual low-code platforms that are themselves the runtime	Visual no-code / low-code canvas	Yes — but of runs inside their own platform, not Claude Code runs	Yes — self-hostable, usually via Docker

That table reflects each tool's own positioning as of mid-2026, and licenses and project status change. Every one of them is capable in its niche — several have a more full-featured canvas or stronger tracing than a v0.2.0 side project, and all of them are portable across model providers, which Workflow Studio is not. The axis here is fit, not ranking. If you are not on Claude Code, none of this is for you.

FAQ

Does Workflow Studio run my workflows?
No. It cannot start a run, from the builder or over MCP. It compiles a script and hands it to your Claude Code agent, which runs it with its own Workflow tool. A server-side shell-out would turn a loopback dashboard into an unauthenticated local execution surface, so execution stays inside your Claude Code session where the permission model lives.

What do I need to install it?
uv / uvx on your PATH and Python 3.9 or newer. Nothing else — the dashboard ships pre-built inside the package, so there is no Node step. Install it as a Claude Code plugin from the GitHub marketplace, or run it standalone with uvx workflow-studio.

Does any of my data leave the machine?
The application makes no outbound calls and collects no telemetry. It reads local run artifacts and binds to 127.0.0.1 by default. Two caveats: uvx downloads the package from PyPI on first run and on version bumps, and the local server has no authentication, so keep it on loopback unless you add your own auth in front of it.

Are the dashboard's token and timing numbers real?
When Claude Code's progress overlay is still on disk, yes — they are read straight from it. When that overlay has been garbage-collected, phases and labels are derived heuristically from the run journal and the run is flagged as such. A run still in flight is labelled live and its elapsed times are lower bounds. Nothing estimated is presented as measured.

Is it an alternative to LangGraph, CrewAI or n8n?
No — it's a different layer. Those are runtimes you adopt, and they are portable across model providers. Workflow Studio ships no runtime and defines no agents; it sits on top of Claude Code's Workflow tool, which it assumes you already use. If you are not on Claude Code, it has nothing to offer you.

Is Workflow Studio open source?
It is MIT-licensed, with one nuance worth knowing: the GitHub repository is the Claude Code plugin marketplace — manifests, a skill, a command and documentation. The application source is distributed in the PyPI sdist rather than published as a browsable repository, so to read the code you unpack the package.

Links

Landing page with interactive demos: https://szymonpaluch.com/workflow-studio/
Plugin on GitHub (MIT): https://github.com/hculap/workflow-studio
PyPI: https://pypi.org/project/workflow-studio/

If you try it, tell me what your run graph looked like — I want to know how wide people are actually fanning out.

12 Rules for Building AI Agents That Survive Production

Szymon Paluch — Fri, 17 Jul 2026 12:30:14 +0000

I sat the Claude Certified Architect exam expecting questions about model parameters, context limits, and API flags. I got something else. The exam barely tests trivia. It tests judgment: given a broken agent and four plausible fixes, which one actually addresses the root cause?

The interesting part was how few ideas the whole thing rests on. The same handful of rules kept deciding the "right" answer, and they are the same rules that decide whether an agent holds up once real users touch it. Below are the twelve I kept running into, plus the four traps that look like solutions and are not.

This is my own study material, derived from publicly available exam guidance. It reflects how I build, not an official Anthropic position.

The twelve rules

Enforce determinism in code, not in prompts
If a rule has to fire every single time, it is not a job for a prompt. A prompt is a suggestion the model usually follows. "Usually" is not a guarantee. When you need a guarantee, put it in a hook, a gate, or an allowlist. Code enforces. Prose requests.
Pick the cheapest fix that hits the root cause
Before you build a subsystem, try the levers that cost minutes: a sharper tool description, an explicit acceptance criterion, a config change. Most "we need to build X" moments dissolve once you test the cheap fix first. Reach for the classifier only after the one-line change fails.
Bad tool selection? Start with the descriptions
When an agent keeps picking the wrong tool, the description is almost always the culprit, not the model. Tool descriptions are the primary signal the model uses to choose. Rewrite them to say exactly when to use the tool and when not to, before you go anywhere near few-shot examples.
Over-engineering is almost always the wrong answer
Narrowing scope and improving the prompt beat a new subsystem far more often than engineers expect. Every subsystem you add is one more thing to debug, monitor, and keep in sync. Complexity is a cost you pay forever, not once.
A bigger context window does not fix attention
Stuffing more into the window does not make the model pay better attention to what matters. It often does the opposite. Decomposition and structure fix attention: smaller tasks, cleaner inputs, explicit boundaries. "Just use the model with the larger context" is a non-answer.
Model confidence and tone are not signals
A confident-sounding answer is not a correct one. Self-assessed confidence is poorly calibrated, and on the hard cases the model is often most sure precisely when it is wrong. Never gate a decision on how certain the model claims to be. Verify with something external.
An independent instance beats self-review
A model grading its own work is biased toward its own work. A fresh instance, with no memory of having produced the output, catches far more errors. If you want a real review step, spin up a separate reviewer, do not ask the author to check itself.
Least privilege for tools
Give each agent role only the tools it needs, roughly four to five. This is not only a security point. More tools measurably degrade selection quality: the model gets worse at choosing when the menu is longer. Fewer, sharper tools beat a giant toolbox.
Structure beats free text, everywhere
Structured errors, structured outputs, structured handoffs between agents, all with explicit provenance. Free-text prose between components is where information quietly rots. When agent A hands to agent B, pass a schema, not a paragraph.
Do not suppress errors, and do not panic
Handle transient failures locally: retry the flaky network call, back off, move on. For everything else, escalate with context so the coordinator can decide. The two failure modes to avoid are swallowing the error silently and blowing up the whole run over something recoverable.
Match the API to your latency requirement
The Batch API costs about half as much but can take up to 24 hours. That is great for an overnight job and useless for anything a human is waiting on. Pick synchronous calls for human-blocking tasks and batch for the rest. Cost and latency are a trade you make on purpose.
A retry fixes format, not missing data
Retrying a call can correct a malformed structure. It cannot conjure information that was never in the source. If the data is not there, running it again just wastes tokens and time. Know which problem you have before you hit retry.

The four traps
These are the answers that feel smart in the moment and cost you later. Every one of them showed up as a tempting-but-wrong option.

"Just write in the prompt that it is mandatory." Shows up exactly when you need determinism, which is the one thing a prompt cannot give you. See rule 1.
"Add few-shot examples." Genuinely useful for ambiguous judgment calls. Useless for hard rules, where it creates the illusion of a guarantee without the guarantee.
"Build a classifier." A heavy solution reached for before anyone tested the cheap levers. Sometimes correct, usually premature. See rule 2.
"Make one tool that does everything." Merging tools feels like simplification. It makes selection worse, because now the model has to guess intent inside a single overloaded tool. See rule 8.
It collapses into three ideas
Strip away the specifics and the twelve rules are really three:

What must always work goes in code, not in a request. Determinism is an architecture decision, not a wording decision.
Match the complexity of the fix to the size of the problem. Cheap lever first, subsystem last.
Pass structure, not prose. Between components, schemas beat sentences.
None of this is exotic. It is the difference between an agent that demos well and one that is still running in three months. The exam rewards it because production rewards it.

Szymon Paluch. I work with teams on agentic system strategy, taking Claude Code and agents from demo to production.

12 rules for building AI agents | Szymon Paluch

The full cheat-sheet from prepping for the Claude Certified Architect exam: 12 rules, 7 recurring traps, the specifics of all 5 domains, and a facts table. The rules that decide whether an agent survives production.

szymonpaluch.com