openflowkit

<p align="center">
  <a href="https://app.openflowkit.com"><img src="public/Logo_openflowkit.svg" width="72" height="72" alt="OpenFlowKit logo"></a>
</p>

<h1 align="center">OpenFlowKit</h1>

<p align="center">
  <b>Architecture diagrams you draw, write as code, or hand to your agent.</b><br>
  Free, open source and local-first. Paste a GitHub repo and get its map, every arrow cited to a line of code.
</p>

<p align="center">
  <a href="https://app.openflowkit.com"><b>Open the app</b></a> &nbsp;·&nbsp;
  <a href="https://docs.openflowkit.com/">Docs</a> &nbsp;·&nbsp;
  <a href="#connect-your-agent">MCP setup</a> &nbsp;·&nbsp;
  <a href="https://github.com/openflowkit/openflowkit/discussions">Discussions</a> &nbsp;·&nbsp;
  <a href="https://github.com/openflowkit/openflowkit/issues">Issues</a>
</p>

<p align="center">
  <a href="https://github.com/openflowkit/openflowkit/actions/workflows/quality.yml"><img src="https://github.com/openflowkit/openflowkit/actions/workflows/quality.yml/badge.svg" alt="CI status"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
  <a href="https://www.npmjs.com/package/@openflowkit/openflowkit-mcp"><img src="https://img.shields.io/npm/v/@openflowkit/openflowkit-mcp?label=mcp%20server" alt="MCP server version on npm"></a>
  <a href="https://www.npmjs.com/package/openflowkit"><img src="https://img.shields.io/npm/v/openflowkit?label=cli" alt="CLI version on npm"></a>
</p>

<p align="center">
  <a href="https://www.producthunt.com/products/openflowkit"><picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-topic-badge.svg?post_id=1081019&theme=dark&period=weekly&topic_id=44">
    <img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-topic-badge.svg?post_id=1081019&theme=light&period=weekly&topic_id=44" width="200" height="43" alt="OpenFlowKit: #4 Product of the Week in Design Tools on Product Hunt">
  </picture></a>
</p>

<p align="center">
  <a href="https://app.openflowkit.com"><picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/hero-dark.gif">
    <source media="(prefers-color-scheme: light)" srcset="assets/readme/hero-light.gif">
    <img src="assets/readme/hero-light.gif" width="900" alt="An agent draws an architecture diagram on the OpenFlowKit canvas, live; the user drags a box, edits one line of text and regenerates">
  </picture></a>
</p>

## Why OpenFlowKit

### 1. Your agent draws on your canvas, live

Connect Claude Code, Cursor or any MCP client and ask for a diagram. The agent reads the page,
draws, restyles and takes a screenshot to check its own work while you watch. Every change it
makes is one undo step, like your own. [Connect your agent ↓](#connect-your-agent)

### 2. Text and canvas are the same diagram

```
flowchart right
  Client [blue] -> "API Gateway" [emerald] : HTTPS
  "API Gateway" -> Queue [queue, amber]
  Queue -> Worker
  Worker -> Store [cylinder, red, bold]
```

Open the code panel (<kbd>⌥C</kbd>), paste this into it and press <kbd>⌘↵</kbd>. Drag things
around on the canvas or edit the text; <kbd>⌘↵</kbd> regenerates the frame from the text as
one undo step. Paste Mermaid, Structurizr or D2 and it converts.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/code-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/readme/code-light.png">
    <img src="assets/readme/code-light.png" width="800" alt="The code panel beside the canvas: the same diagram as text and as shapes">
  </picture>
</p>

### 3. Paste a GitHub repo, get its map

Type `owner/repo` into the box on an empty canvas and press **Map repo**, or open
`app.openflowkit.com/#/map/github/<owner>/<repo>`
([try a sample](https://app.openflowkit.com/#/map/github/dockersamples/example-voting-app)).
Your browser reads the public repo from GitHub and draws its parts. Boxes open in place, and every
arrow lists the `file:line` behind it, linked to the code. No key and no install. For a private
repo, map a checkout: `npx openflowkit map . --html map.html`.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/map-dark.gif">
    <source media="(prefers-color-scheme: light)" srcset="assets/readme/map-light.gif">
    <img src="assets/readme/map-light.gif" width="900" alt="The map of GoogleCloudPlatform/microservices-demo: a click on checkoutservice opens it in place, showing the files inside, while the side panel lists what it talks to">
  </picture>
</p>

### 4. Export it, including the animation

PNG, SVG, PDF, JSON, or **Copy as Mermaid** for a README. Add an `animate` block to the text
above to name the steps, and the export renders animated SVG, GIF, MP4 or WebM in your browser.

```
animate build 6s loop {
  step Client
  step Client -> "API Gateway" : HTTPS
  step Queue, Worker
  step Store hold 2s
}
```

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/motion/flow-build-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/motion/flow-build-light.svg">
    <img src="assets/motion/flow-build-light.svg" width="900" alt="The diagram above building step by step, exported as an animated SVG">
  </picture>
</p>

<sub>That animation is the two snippets above, exported by the app as an animated SVG. GitHub plays it like an image.</sub>

## Ten diagram types, one language

Every type is the same short, forgiving text, with per-line errors that say how to fix them.
Each picture below is the first example on its docs page, rendered by the `openflowkit` CLI.

<table>
  <tr>
    <td width="50%"><a href="https://docs.openflowkit.com/diagram-architecture/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/architecture-dark.png"><img src="assets/readme/types/architecture-light.png" alt="Architecture diagram with Node.js and AWS Lambda icons"></picture></a><br><b>Architecture</b> · cloud icons, groups, a C4 model with views</td>
    <td width="50%"><a href="https://docs.openflowkit.com/diagram-sequence/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/sequence-dark.png"><img src="assets/readme/types/sequence-light.png" alt="Sequence diagram of a login"></picture></a><br><b>Sequence</b> · alt / opt / loop, notes, activations</td>
  </tr>
  <tr>
    <td><a href="https://docs.openflowkit.com/diagram-flowchart/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/flowchart-dark.png"><img src="assets/readme/types/flowchart-light.png" alt="Flowchart"></picture></a><br><b>Flowchart</b> · shapes, decisions, groups</td>
    <td><a href="https://docs.openflowkit.com/diagram-erd/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/erd-dark.png"><img src="assets/readme/types/erd-light.png" alt="Entity-relationship diagram"></picture></a><br><b>ERD</b> · columns, keys, crow's-foot cardinality</td>
  </tr>
  <tr>
    <td><a href="https://docs.openflowkit.com/diagram-state/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/state-dark.png"><img src="assets/readme/types/state-light.png" alt="State machine"></picture></a><br><b>State</b> · start and end, composite states</td>
    <td><a href="https://docs.openflowkit.com/diagram-class/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/class-dark.png"><img src="assets/readme/types/class-light.png" alt="Class diagram"></picture></a><br><b>Class</b> · members, stereotypes, relations</td>
  </tr>
  <tr>
    <td><a href="https://docs.openflowkit.com/diagram-mindmap/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/mindmap-dark.png"><img src="assets/readme/types/mindmap-light.png" alt="Mind map"></picture></a><br><b>Mind map</b> · indentation is the tree</td>
    <td><a href="https://docs.openflowkit.com/diagram-gitgraph/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/gitgraph-dark.png"><img src="assets/readme/types/gitgraph-light.png" alt="Git graph"></picture></a><br><b>Git graph</b> · branches, merges, tags</td>
  </tr>
  <tr>
    <td><a href="https://docs.openflowkit.com/diagram-chart/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/chart-dark.png"><img src="assets/readme/types/chart-light.png" alt="Bar chart"></picture></a><br><b>Chart</b> · data written as text, editable in a table</td>
    <td><a href="https://docs.openflowkit.com/diagram-wireframe/"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/types/wireframe-dark.png"><img src="assets/readme/types/wireframe-light.png" alt="Phone wireframe"></picture></a><br><b>Wireframe</b> · 35 controls on phone, tablet or desktop screens</td>
  </tr>
</table>

The language is versioned and written down in one file: **[src/dsl/grammar.md](src/dsl/grammar.md)**
([docs](https://docs.openflowkit.com/openflow-dsl/)). The same text powers the code panel, the
assistant, the MCP tools and the CLI.

## Quick start

**In the browser:** [app.openflowkit.com](https://app.openflowkit.com). Nothing to install, no account.

**In a terminal:** `npx openflowkit` (Node 20.11+).

**Run it locally** (Node 22.22+):

```bash
git clone https://github.com/openflowkit/openflowkit.git
cd openflowkit
npm install && npm run dev      # http://localhost:3000
```

### Connect your agent

OpenFlowKit has one set of agent tools. Pick the row for where your agent runs:

| Your agent runs… | How to connect | What it can do |
| --- | --- | --- |
| **On your computer**: Claude Code, Cursor, VS Code, Claude Desktop, Windsurf | The MCP server, below | Everything: draws on your open canvas (one undo step per change), edits `.openflow.json` files in your repo, maps a codebase, takes screenshots |
| **In