Metadata-Version: 2.4
Name: workflow-studio
Version: 0.2.0
Summary: Local no-code builder + observability dashboard for Claude Code Workflow multi-agent runs
Project-URL: Homepage, https://github.com/hculap/workflow-studio
Project-URL: Repository, https://github.com/hculap/workflow-studio
Project-URL: Issues, https://github.com/hculap/workflow-studio/issues
Author-email: Szymon Paluch <hculap@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude,claude-code,dashboard,mcp,observability,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/) 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](https://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>
