KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #deepseek-harness #typescript #ai-agent #codex #developer-tools #claude-code #windows #mcp #python #desktop-app

flowpiler

★ 5 Open GitHub ↗

A visual editor for Claude Code workflows. Drag nodes onto a canvas, wire them together, and Flowpiler compiles the graph into a ready-to-run workflow.js — and parses your existing workflow.js back into a graph. Test it with mocked agents for free, then run it for real and watch every subagent light up live.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Flowpiler

**A visual editor for Claude Code workflows.** Drag nodes onto a canvas, wire them
together, and Flowpiler compiles the graph into a ready-to-run `workflow.js` — and
parses your existing `workflow.js` back into a graph. Test it with mocked agents for
free, then run it for real and watch every subagent light up live.

> Think *Pentaho Kettle, but for Claude workflows* — a node-graph front end for the
> imperative script the `Workflow` tool expects.

![Flowpiler overview](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/01-overview.png)

<p align="center"><em>Palette · canvas · inspector + live <code>workflow.js</code> — all three update together.</em></p>

![stack](https://img.shields.io/badge/stack-Vite%20%2B%20React%20%2B%20React%20Flow-6ea8fe)
![type](https://img.shields.io/badge/typed-TypeScript-3178c6)
![runs](https://img.shields.io/badge/runs-local%20claude%20--p-9b8cff)

---

## Why Flowpiler?

Claude Code **Workflows** orchestrate dozens of subagents to do things one context
can't — exhaustive code reviews, repo-wide migrations, multi-source research, audit
sweeps. They're powerful, but they ship as JavaScript:

```js
const reviews = await parallel([
  () => agent(`Review the diff for correctness bugs…`, { phase: `Review`, schema: REVIEW_BUGS_SCHEMA }),
  () => agent(`Review the diff for performance regressions…`, { phase: `Review`, schema: REVIEW_PERF_SCHEMA }),
])
const findings = reviews.filter(Boolean).flatMap(r => r.findings)
const verified = await pipeline(findings, (prev, item) => agent(`Adversarially verify…`, …))
```

And in practice **most of these scripts are AI-generated** — which means the human in
the loop spends their time *reading, trusting, and tweaking* a script they didn't
write. That's exactly the friction Flowpiler removes:

- **See it at a glance.** A wall of `parallel`/`pipeline`/`await` becomes a graph you
  can read in seconds — phases, fan-outs, verify loops, branches.
- **Edit safely.** Change a prompt, swap a model, add a verify stage — in form fields,
  not by hand-editing nested template literals. The code regenerates as you type.
- **Test for free.** Dry-run the whole thing with **mocked** agents to catch broken
  control flow, undefined variables, and unbounded loops — **before** spending a cent
  on real subagents.
- **Run for real, and watch.** Execute through your local `claude` and stream each
  node's **state · tokens · duration · full output** right onto the canvas.
- **Round-trip.** Import any `workflow.js`, edit visually, export it back.

### Where it pays off in daily ops

Codify the recurring multi-agent jobs your team does by hand into **reusable, visual,
testable** workflows — then tune them in plain language and re-run on demand:

| Maintenance task | Shape in Flowpiler |
| --- | --- |
| PR / diff review across dimensions | `parallel` finders → dedup `code` → `pipeline` adversarial verify |
| Dependency / license / security audit | `parallel` scanners → `if` (findings?) → report |
| Log & incident triage | fan-out over services → summarize → `return` ranked list |
| Docs / dead-link / TODO sweep | `pipeline` over files → fix-suggestion agent |
| Flaky-test hunt | `while` loop-until-dry → confirm → patch proposal |

Build it once, dry-run to prove the wiring, run it live when you need it, and hand the
exported `workflow.js` to teammates or a cron.

---

## Quick start

```bash
npm install
npm run dev      # → http://localhost:5180
npm run build    # type-check + production bundle into dist/
```

Open the app and hit **Load sample** to drop in the `review-changes` example shown
throughout this README, or start from the seed graph and drag nodes from the palette.

> **Run live / AI edit are dev-mode features.** They call your local `claude` through a
> Vite dev-server endpoint, reusing your existing Claude Code auth — Flowpiler never
> sees an API key. They're available under `npm run dev`, not in the static `dist/`
> build.

---

## Feature tour

### Edit nodes in the inspector — code regenerates live

Select any node to edit its fields on the right. Prompts, labels, phase, model,
worktree isolation, structured-output JSON Schema — all editable, and the
`workflow.js` panel below rewrites itself on every keystroke.

![Inspector](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/02-inspector.png)

### Dry-run with mocked agents — catch bugs for free

`▷ Test run` executes your workflow in a sandboxed worker with **mocked** agents: no
subagents are spawned, no tokens are spent. You get the exact call order, plus errors
and unbounded-loop detection — and the canvas lights up to show what ran.

![Dry-run trace](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/03-testrun.png)

After a run, the **overlay stays on the canvas**: nodes that ran glow, observable nodes
that didn't run dim, and fan-outs / loops get an `×count` badge. It clears the moment
you edit.

![Run overlay](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/04-overlay.png)

### AI-edit the graph in plain language

`✦ AI edit` — describe a change ("make the extract step a parallel fan-out over
clusters", "give every agent a budget-aware while loop", "switch the review agents to
opus") and it runs your local `claude -p`, rewrites the `workflow.js`, and re-imports it
as a fresh graph.

![AI edit](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/05-aiedit.png)

### Run for real — live per-node telemetry

`● Run live` actually executes the workflow through
`claude -p --output-format stream-json`, parsing `workflow_progress` and streaming each
node's real **state, tokens, duration, and result** onto the same overlay. Pick the
working directory the agents run in, pass optional JSON `args`, and the slide-out drawer
tracks every agent as it goes.

![Run live](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/06-runlive.png)

Each agent row (and the inspector's "last run") is **click-to-expand**: Flowpiler reads
the subagent's on-disk transcript and shows the **full** prompt and output — not just
the truncated preview the live stream carries.

### …and the rest

- **Tabs + autosave** — keep multiple workflows side by side (click to switch,
  double-click to rename, `+` for a new one); every change is persisted to
  `localStorage` and restored on reload. **Download** names the file after the tab.
- **Import** — paste or upload an existing `workflow.js`; it's parsed back into a node
  graph (anything it can't classify lands in a `code` node rather than failing).
- **Live validation** — empty meta name/prompt, invalid schema JSON, empty containers,
  unwired nodes, and phase/`meta` mismatches are flagged as you build; click an issue to
  jump to and highlight its node.

---

## Bundled samples — including MAGI, the *Evangelion* decision system

Pick one from the top-bar dropdown:

| Sample | What it shows |
| --- | --- |
| **review-changes** | the canonical fan-out → dedup → adversarial-verify review pattern |
| **MAGI · Eva three-sage** | a majority-vote decision engine (read on 👇) |

### 🟠 MAGI — “the three wise men” as a Claude workflow

![MAGI verdict](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/magi.svg)

In *Neon Genesis Evangelion*, **MAGI** is the supercomputer that runs NERV. Its creator
split her own psyche across **three units — MELCHIOR-1, BALTHASAR-2, CASPER-3** (the
scientist, the mother, the woman) — and the system decides by **majority vote** of the
three. It's basically a multi-agent system with deliberately diverse perspectives… which
is *exactly* a Claude `parallel` + majority pattern.

Flowpiler ships it as a runnable sample. Three agents judge the same proposal through
three different lenses, in parallel; a `code` node tallies the votes; a 2-of-3 majority
becomes the verdict:

![MAGI workflow in Flowpiler](https://raw.githubusercontent.com/yuchi-chang/flowpiler/main/docs/screenshots/magi-workflow.png)

```
phase("Deliberate")
const votes = await parallel([
  () => agent(`…as MELCHIOR-1 (SCIENTIST) — judge on logic & feasibility…  Proposal: ${args.proposal}`, { schema }),
  () => agent(`…as BALTHASAR-2 (MOTHER)  — judge on protection & safety…    Proposal: ${args.proposal}`, { schema }),
  () => agent(`…as CASPER-3 (WOMAN)      — judge on intuition & human impact… Proposal: ${args.proposal}`, { schema }),
])
const approvals = votes.filter(Boolean).filter(v => v.vote === "APPROVE").length
const decision  = approvals >= 2 ? "APPROVED" : "REJECTED"
phase("Resolve"); log(`MAGI verdict: ${decision} (${approvals}/3 approve)`)
return { decision, approvals, votes }
```

**Try it:** Load **MAGI** → **▷ Test run** (or **● Run live**) and pass a proposal as
`args` — either JSON `{"proposal":"ship on Friday"}` or just plain text. Watch the three
sages deliberate and the verdict come back. It's a tiny, fun template for any
“get N independent opinions, then decide” task — design reviews, go/no-go calls, risk
sign-offs.

> The graphic above is an original homage, not a screenshot from the show.

---

## Node types

| Node | Emits |
| --- | --- |
| **meta / Start** | `export const meta = { name, description, whenToUse?, phases }` |
| **agent()** | `const v = await agent(prompt, { label, phase, model, isolation, agentType, schema })` |
| **parallel()** | `const v = await parallel([() => …, …])` — branches run concurrently (barrier), or **map** mode fans one template over a collection |
| **pipeline()** | `const v = await pipeline(items, (prev, item, i) => …, …)` — items through ordered stages |
| **phase()** | `phase('title')` |
| **log()** | `log('message')` |
| **while loop** | `while (cond) { …body… }` |
| **if branch** | `if (cond) { …then… } else { …else… }` |
| **code / return** | raw JS — declarations, transforms, `return …` |

### Ordering & nesting

- **Execution order** at every level follows the connecting hops (topological), falling
  back to top-to-bottom canvas position for the start and any unconnected nodes.
- **parallel** children run concurrently — no wiring needed between them. **map** mode
  emits `parallel(items.map((item, i) => () => …))` for dynamic fan-outs.
- **pipeline / while / if** children are ordered by their internal hops.
- **Nesting is unlimited** — drop a container inside a container (e.g. a `parallel` as a
  `pipeline` stage); the drop targets the innermost box and the nested
  `parallel`/`pipeline` is emitted inline as an expression.
- **`if` has then / else** — each `if` box is split into a then column and an else
  column; drop a node into either side (or flip it in the inspector).
- **agent** prompts and labels are emitted as **template literals**, so `${item}`,
  `${prev.x}`, `${i}` interpolation works inside loops and stages.
- **Schemas** entered on agent nodes are validated as JSON and **hoisted** to named
  `*_SCHEMA` consts at the top, then referenced from the agent's opts — matching the
  convention in the Workflow examples.

---

## Architecture

```
src/
├─ components/          # all React UI
│  ├─ App.tsx           #   layout, canvas, drag-drop + re-parent, tabs, import/export, tidy
│  ├─ Palette.tsx       #   left sidebar, draggable node templates
│  ├─ Inspector.tsx     #   right sidebar, per-kind field editors
│  ├─ nodes.tsx         #   React Flow node components + nodeTypes registry
│  └─ *Dialog.tsx       #   Test / RunLive / AiEdit / Detail dialogs
├─ compiler/            # graph ↔ workflow.js
│  ├─ codegen.ts        #   graph → workflow.js (the compiler)
│  └─ parser.ts         #   workflow.js → graph (the importer)
├─ runtime/             # execution + telemetry
│  ├─ runtime.ts        #   shared run model + node attribution
│  ├─ simulate.ts/      #   dry-run: mocked-agent execution in a Web Worker
│  │  simWorker.ts
│  ├─ runLive.ts        #   live run: stream-json telemetry + on-disk transcript reads
│  └─ aiEdit.ts         #   plain-language edit via local claude -p
├─ state/               # zustand store + React contexts
│  ├─ store.ts          #   multi-tab graphs + localStorage persist
│  ├─ types.ts          #   node-data model + defaults
│  └─ *Context.ts       #   run / validation / detail contexts
├─ graphUtil.ts         # absolute positions, nesting hit-tests, resize-aware sizing
├─ validation.ts        # static checks → issues
├─ sample.ts            # bundled samples (review-changes, MAGI)
├─ main.tsx             # entry
└─ styles.css           # dark IDE theme

vite.config.ts          # dev-server endpoints: /api/edit, /api/run, /api/pickdir,
                        # /api/agent-output — all spawn your local `claude`
```

`codegen.ts` is the heart: it finds the meta node, hoists schema consts, then walks the
top-level nodes in hop order, recursing into containers. `parser.ts` is its inverse — a
bracket/string/template/regex-aware scanner that reads the JS subset Flowpiler emits.

---

## Known limitations (v1)

- `parallel` / `pipeline` thunk/stage bodies are expected to be **agent**, **code**, or
  a nested **parallel/pipeline** (things that are expressions). A `while`/`if` can't be
  inlined as a thunk body (it isn't an expression).
- The importer targets the JS subset Flowpiler emits; arbitrary hand-written control
  flow it can't classify lands in a `code` node rather than failing.
- Imported graphs get an automatic layout — readable, but you'll likely tidy positions
  by hand.
- **Run live** and **AI edit** require a local `claude` CLI on `PATH` and run only in
  dev mode. The folder picker is Windows-only (type the path manually elsewhere).

flowpiler

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README