Flow

A canvas for agents. Agents create and revise Mermaid diagrams over MCP; you watch every revision render live, comment on nodes, and export.

Requires Node 20+.

Install

Pi

pi install npm:@rawnly/flow

Claude Code

As a plugin (MCP server, feedback hooks and the skill in one step):

/plugin install flow --marketplace rawnly/flow

On older Claude Code: /plugin marketplace add rawnly/flow, then /plugin install flow@flow.

Or just the MCP server:

claude mcp add flow -- npx -y -p @rawnly/flow flow-mcp

Add --scope project to write it to the repo's .mcp.json instead of your user config. To get viewer comments back into the conversation automatically, also install the hooks (see Closing the loop without pi):

npx -y -p @rawnly/flow flow-hook --print   # paste into .claude/settings.json

Codex

codex mcp add flow -- npx -y -p @rawnly/flow flow-mcp

Or in ~/.codex/config.toml:

[mcp_servers.flow]
command = "npx"
args = ["-y", "-p", "@rawnly/flow", "flow-mcp"]

[mcp_servers.flow.env]
FLOW_DIR = ".flow"
FLOW_AGENT_NAME = "codex"

Codex has no hooks, so use the wait_for_feedback tool to receive comments (see below).

Any other MCP client

Add this to your client's config (.mcp.json, mcp.json, ...):

{
  "mcpServers": {
    "flow": {
      "command": "npx",
      "args": ["-y", "-p", "@rawnly/flow", "flow-mcp"],
      "env": {
        "FLOW_DIR": ".flow",
        "FLOW_AGENT_NAME": "claude"
      }
    }
  }
}

The first MCP process also serves the viewer at http://127.0.0.1:4729 and opens it in your browser on the first diagram.

Configuration

All optional, set as environment variables.

Tools

Tip: label nodes as id["Title<br/>subtitle"] for the two-line style. The viewer highlights what changed since the previous revision on its own.

Skill

skills/flow/SKILL.md teaches agents the workflow (feedback loop, edit conflicts, diagram style). Pi loads it with the package and the Claude Code plugin ships it. For a manual Claude Code setup, copy it to .claude/skills/flow/SKILL.md.

Viewer

Export: SVG, PNG 2×, SVG markup, or copy as a Markdown code block.

No overwrites: if the agent saves while you edit, you're warned before replacing it. If you edited since the agent last looked, its update_diagram is refused with your current source, so it builds on your edit.

Closing the loop without pi

Outside pi, nothing pushes viewer comments into the conversation, so there are two opt-in ways to get them back to the agent:

• wait_for_feedback tool (any MCP client). Blocks until the human leaves feedback (default 50s, max 600s), then returns it. The agent loops: update, wait, address, resolve_feedback, wait. Works in Codex and anything else that speaks MCP.

• Claude Code hooks (included in the plugin). flow-hook reads feedback from FLOW_DIR (default <cwd>/.flow). On PostToolUse after Claude draws, it waits like a plan review, with no time limit, until you press Send to agent (your review goes back to Claude) or Looks good (Claude carries on). It only waits once no feedback is left open, so Claude can update and resolve first. Press Esc in Claude Code to stop waiting. On UserPromptSubmit it adds the feedback to your prompt; on Stop it blocks the agent from finishing while feedback is open (once per turn, so an unresolved item can't loop forever). Print the settings to paste into .claude/settings.json:

  npx -y -p @rawnly/flow flow-hook --print

Outside a review wait, hooks can't wake an idle session: they fire when you prompt or when the agent is about to stop.

Pi extension extras

On top of the tools, the pi extension:

• Returns feedback automatically. Send to agent in the viewer delivers your review into the conversation; the agent revises the diagram and resolves it. Only diagrams the current session created or edited are delivered.
• Opens the viewer on the first diagram created. /flow [id] opens it any time.
• Shows open feedback count in the footer.
• Supports several agents per project. Writes are locked per diagram, so agents, MCP servers and the viewer never clobber each other. Feedback goes to the session that wrote the latest revision. If the session hosting the viewer exits, another takes over within seconds.

Develop

bun install
bun run build        # required once: builds the viewer into dist/
bun run seed         # synthetic demo diagrams
bun run dev:server   # API on :4729
bun run dev          # Vite viewer with /api proxied
bun test

Use your local build instead of the package:

claude mcp add flow -- node "$PWD/dist/server/mcp.js"
pi install /path/to/flow     # or: pi -e /path/to/flow/pi/extension.ts

npx -p @rawnly/flow flow-mcp fails with flow-mcp: command not found inside this repo: npx resolves the package to the local project (same name) and doesn't put a project's own bin on PATH. Run it from another directory, or use npm run mcp / npm link here.

Release: bump first (npm version patch), then npm publish; prepublishOnly builds. A version can't be republished.