Skip to content
How flowfig works: its parts and the messages between them
  1. The agent asks for a figure.
  2. The server reads the spec.
  3. The renderer lays out the boxes and edges.
  4. The checker finds no fault.
  5. The verifier checks each link against the code.
  6. The verifier reads the linked file and symbol.
  7. The server writes one SVG. The loader can read its spec back.
  8. The agent gets the check lines back.
  9. The agent asks the server to verify the figure.
  10. The verifier reads the spec from the SVG.
  11. A linked file is gone.
  12. The check fails. The figure drifted from the code.
flowfig checked this figure against the code on 2026-11-16: 6 of 6 boxes defined; edges: 5 found, 0 not found, 0 unsure, 1 not checked Code at 011de60.

See how your code works, one step at a time.

AI writes code faster than you can read it. Your coding agent reads the code and writes a short JSON spec of one flow. flowfig checks the spec and draws it as an animated figure that you can understand in a minute.

Try it: run npx flowfig init in your repo, then ask your agent to draw how checkout works.

A made-up cake shop app in 3 stories. In your repo, each box can link to the function that does the step.

A cake order, animated in 3 stories: delivered, sold out, and too far. A dot moves from the customer to the bakery checks, then to the courier and the door.

The same spec also makes a guide for a reader who does not know the code. The guide tells one moment at a time:

The same cake order as a small town: the courier truck carries the cake box from the bakery to the customer's house. A side panel tells the moment in one sentence.

Why flowfig

  • flowfig checks it. flowfig check finds ids that point nowhere, text wider than its box, edges through boxes, overlapping labels and low contrast. The agent reads the faults and fixes the spec. flowfig verify fails CI when a linked function is gone.
  • It plays where you read code. The figure is one SVG file with no script. It plays in a README, a pull request or an issue.
  • One spec, many forms. The same spec draws a map, a list of the messages in order, swimlanes, a timeline, the parts inside a box, or a guide for a person.

Quick start

  1. Set up your repo:

    npx flowfig init
  2. Start a new agent session and ask in plain words:

    draw how checkout works in this repo
    
  3. The agent writes an SVG and ends its reply with npx flowfig open <path>. Run that command to see the figure in your browser.

To use the React player or the Node API, install the package: npm i flowfig. flowfig needs Node 18 or later. Only the React player needs React (18 or later).

Forms

An order checkout: the map of the parts, and a rail of the messages under it
Map and rail. One row for each message, with its payload.
The refund process across Customer, Support and Finance
Swimlanes. One lane for each role, steps in time order.
A Q4 roadmap with three tracks, milestones and a today line
Timeline. One track for each team, with dated bars and milestones.
An order status lifecycle with a start dot and two end rings
States. A lifecycle with a start state and end states.

The figure at the top is the map form. A box can also open to show the parts inside it, down to 3 levels. Each form is one field in the spec. See the spec.

Fail CI when a figure no longer matches the code

A box, an edge or a message can name the code that it draws:

{ "id": "verify", "label": "verifyPassword", "source": "src/auth/login.ts#verifyPassword" }

If someone renames verifyPassword, verify fails with exit code 1:

$ npx flowfig verify login.svg
error    missing-symbol     login.svg: box "verify" -> src/auth/login.ts#verifyPassword: symbol not defined
1 error, 0 warnings
login.svg: 0 of 1 boxes defined

The GitHub Action runs verify on every figure in a pull request. It comments the old and the new image for each figure that the pull request changes. See Verify in CI.

flowfig, Mermaid and a hand-drawn image

flowfig Mermaid Hand-drawn image
Made by an agent from the code Yes, with the init instructions Yes, as Mermaid text No
Linked to the code Yes, verify fails in CI No No
Checked for faults Yes, with flowfig check Syntax errors only No
Animated Yes, a dot moves on each message No No
Shows payloads and order Yes, on the map and the rail Order and text in a sequence diagram No
Plays in a GitHub README Yes, as an SVG Yes, GitHub renders it Yes, as an image
Readable back as source Yes, with --spec Yes, the source is text No
Class and ER diagrams No Yes. Mermaid wins this row. Yes

Docs

  • The spec: your first figure, the forms, boxes, groups, edges, steps and options.
  • The CLI: draw, check, open, share as a GIF, trace a function, find stale figures, one page for all figures.
  • Verify in CI: link a figure to the code, and the GitHub Action.
  • Explain a flow in a web page: the <flowfig-explain> element.
  • Integrations: coding agents, React, Node, the MCP server and Mermaid.
  • Development: build and test this repo.

License

MIT. See LICENSE.

Read the code.

Open the repository