Workflow Studio

Local, no-code builder + observability dashboard for Claude Code's Workflow tool — the deterministic multi-agent orchestration primitive.

Watch what a multi-agent Workflow run actually did, author new workflows visually, and expose both to the Claude Code agent over MCP so you and the agent collaborate through one live surface.

Status: 0.1.0. Not yet published to PyPI — pip install / uvx workflow-studio do not work today. The install that works now is the Claude Code plugin, which carries a pre-built wheel. PyPI publication is a documented, optional next step (see below).

What it is

Workflow Studio has two halves. Observe reads Claude Code's own on-disk run artifacts (~/.claude/projects/**/subagents/workflows/wf_*) and renders each run as a graph/timeline — phases, per-agent nodes, tokens, timing, which branch was taken — with live runs and auto-refresh. Author is a canvas block builder that compiles to a runnable Workflow script and round-trips losslessly via an embedded @wf-builder sidecar. A dependency-free MCP (stdio) server exposes both to the agent, so the agent can discover what you built, read a design's declared contract, run it with its own Workflow tool, and draft designs back into your builder.

Install & run

Requires uv / uvx on your PATH. (A GUI-launched Claude Code may not have it; the MCP server then shows failed in /mcp.)

As a Claude Code plugin (recommended)

The plugin bundles a pre-built wheel, so no PyPI resolution is needed — the bundled-wheel plugin, not PyPI, is what works today. Once the repo is pushed to GitHub, from Claude Code:

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

Then /mcp lists workflow-studio (9 tools) and /workflow-studio:dashboard opens the UI.

MCP server only (no plugin)

Register the stdio server directly against a local wheel:

claude mcp add workflow-studio -s user -- uvx --from /path/to/workflow_studio-0.1.0-py3-none-any.whl workflow-studio mcp

The mcp subcommand (workflow-studio mcp) runs the hand-rolled JSON-RPC 2.0 stdio server; the bare workflow-studio command launches the web dashboard. This server does not start runs — it hands the agent a design's script, which the agent executes with its own Workflow tool.

Dashboard (standalone)

• After PyPI publish (not yet available): uvx workflow-studio
• Today, from a local wheel: uvx --from /path/to/workflow_studio-0.1.0-py3-none-any.whl workflow-studio

The dashboard binds 127.0.0.1 and opens in your browser.

Features

• Observe — every Workflow run on disk as a graph/timeline: phases, per-agent nodes, logs, tokens, timing, and the branch taken. Live runs included, with auto-refresh.
• Author — a canvas block builder across 12 block kinds (agent, fanout, loop, subwf, gate, filter, switch, pipeline, rank, input, param, start) that compiles to real Workflow primitives (agent(), phase(), parallel(), pipeline(), log()) plus a @wf-builder sidecar for lossless round-trips.
• MCP server — 9 tools: get_context, list_projects, list_runs, get_run, list_workflows, get_workflow, get_run_design (read) and save_workflow, promote_run (write).
• Honesty flags baked into the data — observed results carry taskMatched (false ⇒ metrics are heuristic, not measured) and status (a live/incomplete elapsed span is a lower bound); declared designs carry source (snapshot = exactly what ran / template = may differ) and hasSidecar with a decoded contract.
• EN / PL localization via dependency-free i18n catalogs.

Zero-dependency, local-only, no telemetry

• Pure Python standard library — zero runtime dependencies (dependencies = []), requires-python >=3.9. The pre-built React SPA ships inside the wheel.
• Runs locally only: binds 127.0.0.1, reads your local Claude Code data. No telemetry, no network calls.
• The MCP server is a hand-rolled JSON-RPC 2.0 stdio loop (no SDK), which keeps the package zero-dependency and uvx-startable with no resolution step.

Use it as a Claude Code plugin

The full plugin — marketplace manifest, /workflow-studio:dashboard command, the workflow-studio skill, and the bundled wheel — lives at github.com/hculap/workflow-studio. See that repo for setup, the shared-data-dir gotcha (WORKFLOW_STUDIO_DATA — the dashboard must read the same dir the agent's save_workflow writes to, or drafts won't appear), and version-pinning notes.

PyPI (pending)

Publication to PyPI is a documented next step, not yet done. When ready: run uv publish from the package directory, simplify the plugin's mcpServers command to {"command": "uvx", "args": ["workflow-studio", "mcp"]}, drop the vendored wheel, and re-install. Until then, the bundled wheel is the mechanism.

License

MIT © Szymon Paluch hculap@gmail.com