What's new

Each release of flowfig, newest first. The text is the GitHub release note. Subscribe with the RSS feed.

0.8.4 (2026-10-05)

flowfig 0.8.4 gives edge labels more room. Each arrow now shows its line and arrowhead on both sides of its label.

Improvements

• Room around labels. The gap between two boxes holds the edge label and a visible line on each side of it. Before, a label could fill the whole gap and hide the arrow.
• Labels away from boxes. An edge label keeps 6 px from every box when the figure has the room.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

• Figures with edge labels get a little wider when you render them again. If a wide figure now reports small-text, shorten a label or make a box narrower.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.4.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.8.3...v0.8.4

The release on GitHub

0.8.3 (2026-10-05)

flowfig 0.8.3 links each state of a state diagram to its own enum member, and fixes two edge routes that crossed a box.

Improvements

• Enum members in source. A box source can name an enum member as Owner.name, for example src/status.ts#OrderStatus.Paid. verify checks that the member is defined in the enum. This works in TypeScript, JavaScript, Java, C#, Rust and Python (class Owner(Enum)). A name in a comment or a string does not pass.
• Edges around boxes. If you set around on an edge and that side has no free path, the edge now takes a free side. A right-angle edge that goes to the left now also avoids the boxes in its way.
• Edge lines at the border. An edge that runs along the figure border keeps its full line width.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

• No change is needed. Edges with a blocked around side can take a new route when you render the figure again.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.3.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.8.2...v0.8.3

The release on GitHub

0.8.2 (2026-10-05)

flowfig 0.8.2 changes only the package description and keywords on npm. The code is the same as in 0.8.1.

Upgrade

• No change is needed. If your GitHub workflow uses the flowfig Action, you can change it to iamalvisng/flowfig@v0.8.2.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.8.1...v0.8.2

The release on GitHub

0.8.1 (2026-10-05)

flowfig 0.8.1 makes figures easier to read, and an agent needs fewer steps to draw one.

npx flowfig spec.json docs/login.svg
# figure: 8 boxes, 0 groups, 8 edges, 2 steps, 17 messages
# client -> limiter: log in
# limiter -> redis: count tries
# ...
# docs/login.svg: 4 of 4 boxes defined; edges: 6 found, 0 not found, 1 unsure, 1 not checked

New

• One command per try. A render now prints one line per edge and per step, and the verify counts when the figure has a source or a via. You do not need a separate verify or --spec call to read the figure back. --no-verify skips the verify part. flowfig verify stays for CI.
• Code on hover. If a box, an edge or a hop has a source, the SVG and the <Flow /> player show it on hover. The label can be plain words, and the code name stays one hover away.
• Check rule plain-text (warning). It reports a label that looks like code (findUserByEmail, validate_rows, run()), a label that is a database or cache command (SELECT, SET sess:1 EX 3600), a say line or a caption over 20 words, and filler words such as “seamless” or “robust”. An HTTP request line such as GET /user passes. If the word is a product name, keep it.
• Short guide. flowfig docs prints a core guide of about half the old length. flowfig docs <topic> prints one topic: lanes, timeline, rail, marks or verify. The MCP docs tool takes the same topic.

Improvements

• Edges go around boxes. If a straight edge would cross a box, the edge goes around it with an arc or a right-angle path.
• Labels find free space. An edge label moves along its edge to a spot clear of boxes and other labels.
• Gaps fit the labels. The space between boxes grows to hold the edge labels between them. A gap that you set is now the smallest gap, not a fixed one.
• Long box labels wrap to two lines before the text gets smaller.
• verify gives fewer wrong “not found” results. If the caller calls a function that it receives, such as Express next(), the edge is “unsure” with the reason. If the caller is a variable such as const router = Router(), the check also reads the statements on it, such as router.post(...), in TypeScript, JavaScript and Python.
• flowfig diff now reports a change to via, a hop’s source or via, a removed repeat of the same hop, and a step caption change.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

• Figures can change their layout when you render them again: edges route around boxes, and gaps grow to fit labels. Render your figures again and look at them.
• If your figures use code names as labels, the new plain-text warning reports them. Put the code name in source and write the label in plain words. Under --strict the warning is an error.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.1.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.8.0...v0.8.1

The release on GitHub

0.8.0 (2026-10-05)

flowfig verify now checks the arrows, not only the names. It tells you which edges of a figure the code really makes, so a reviewer can see which parts to trust.

npx flowfig verify docs/login.svg

New

• Edge check. verify gives each edge one result:
  • found: the caller code calls or references the callee, through an import, the same file or a typed receiver.
  • not found: the code does not make that call. verify prints a warning, and --strict makes it an error.
  • unsure: verify cannot decide, for example when a receiver has no declared type. It lists the edge with the reason and never fails CI.
  • not checked: the edge has no code to check, or the file is in a language that verify does not read.
• Languages. Edge checks work in TypeScript, JavaScript, Python, Go, Java, C# and Rust.
• Methods. A source can name a method: src/auth/session.ts#Session.refresh.
• via for edges across a process. Set via to the route, queue, topic, table, file or key that both sides use, for example "via": "order-paid". For a via edge, “found” means that the caller code and the callee file both use that name. It does not prove that a handler serves it.
• Counts everywhere. The CLI, the MCP verify tool and the GitHub Action comment show the box and edge counts. verify --json adds a coverage list with the counts and the unsure edges.
• Agent guide. The instructions that flowfig init installs teach agents to set edge sources and via, and to fix each edge that verify does not find.

Improvements

• Box check. In a code file, a box symbol must be defined, not only mentioned. A name in a comment or a string no longer passes.
• flowfig/verify exports verifyReport, which returns the findings and the counts. verify keeps its signature.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine, and needs a little-endian CPU (x64 or ARM).

Upgrade

• A box source whose symbol the file only mentions, and does not define, now fails verify with symbol not defined. Point the source at the file that defines the symbol, or use path#Owner.name for a method.
• Edges that verify cannot find give warnings, not errors, unless you use --strict. Run npx flowfig verify <figure> once after the upgrade and fix the edges it reports.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.0.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.7.0...v0.8.0

The release on GitHub

0.7.0 (2026-10-04)

Faster GIF export, smaller SVG files, and faster renders of large figures. The figures look the same.

npx flowfig gif docs/checkout.svg

Improvements

• Faster GIF export. flowfig gif captures frames in up to 4 browser tabs at once and encodes them faster. On a test machine, the GIF of a 16-second figure takes about 16 seconds, down from about 35. The GIF bytes stay the same.
• Smaller SVG files. The SVG keeps one keyframe for each run of equal values. A typical figure is 15 to 40 percent smaller, and a large figure can be 20 times smaller. The animation is frame-for-frame the same.
• Faster renders. Large figures and wrapped swimlanes render 2 to 3 times faster. flowfig renders a figure once per call, also through the MCP render tool.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine, and needs a little-endian CPU (x64 or ARM).

Upgrade

No breaking change. Render your figures again to get the smaller SVG files.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.6.0...v0.7.0

The release on GitHub

0.6.0 (2026-10-04)

Cleaner timelines and swimlanes, stricter checks, and Windows support for open and gif.

npx flowfig init   # get the new agent instructions

Improvements

• Timeline. The animation starts at the first item, so the first frame of a GIF and of a README shows the playhead in place. The today line and the playhead run behind the bars and do not cross the bar text. A dependency line goes around the bars it does not connect.
• Swimlanes. An edge label stays inside one lane, not on the border between two lanes. A decision at the end of a wrapped block keeps its stub label inside its lane and inside the figure.
• Windows. The tests now run on Windows in CI, including gif with Chrome. flowfig gif stops all browser helper processes on Windows and removes its temp folder. flowfig init prints paths with / on every system.
• Agent instructions. A pasted Mermaid design keeps its arrow types: a plain arrow stays a plain message, even for a queue. In a process document, the agent draws each path to its end, with one step per path. When a text does not fit its box, the agent widens the box or moves the detail, and does not cut a fact.

Fixes

• On Windows, flowfig verify accepted a source path outside the repo. It now reports it.

Checks

These checks are new, so a figure that passed check --strict in 0.5.0 can now report a fault:

• label-overlap also reports an edge label across a lane border.
• edge-crosses-box also reports a timeline dependency line through a bar.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine.

Upgrade

Render your figures again with 0.6.0 and run check --strict. Run npx flowfig init again in your repo to get the new agent instructions.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.5.0...v0.6.0

The release on GitHub

0.5.0 (2026-10-03)

Long swimlane processes now fit in one figure, and decision boxes keep their text inside the diamond.

npx flowfig init   # get the new agent instructions

New

• Swimlanes wrap. When the steps of a lanes: true figure do not fit the page width, flowfig wraps the time columns into blocks, one under the other. Each block shows only the lanes that have a step in it. An edge between two blocks becomes two short labeled stubs, for example “→ Inspect” and “from Ship item”. A process of 7 or more steps now stays readable in one figure.
• lane-end-block check. check warns when an edge in a wrapped figure ends at a lane that no nearby block shows.
• stub-crosses-edge check. check warns when a stub line crosses another edge. --strict makes it an error.

Improvements

• A decision box (shape: 'decision') wraps its sub line inside the diamond outline and grows taller when it needs more room. check now tests the text against the diamond shape.
• --width now also sets where the lanes wrap, in the CLI and in the MCP render tool.
• Agents keep a long process in one figure. For a process document, agents now also show every deadline, every message to a person, every choice and every wait for a reply.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

No breaking change. A lanes figure that fits the width renders as before. Run npx flowfig init again in your repo to get the new agent instructions.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.4.0...v0.5.0

The release on GitHub

0.4.0 (2026-10-03)

Swimlanes, a timeline form, start and end marks, and two new commands: open shows a figure in your browser, and gif makes an animated GIF that you can share anywhere.

npx flowfig open docs/checkout.svg   # show the figure in your default browser
npx flowfig gif docs/checkout.svg    # write docs/checkout.gif

New

• Swimlanes. Set lanes: true and give each box an at lane and time column. Each role gets its own band with a label. Use it for a process that several teams share.
• Timeline form. Set timeline: true to draw a roadmap with dated bars, milestones, dependency lines, a today line and a moving playhead. check reports dates out of order.
• Start and end marks. A lifecycle box can show a start dot or an end ring.
• flowfig open <figure.svg>. Opens the figure in your default browser. Add --open to a render or to draw to do the same after the figure is written.
• flowfig gif <figure.svg> [out.gif]. Writes an animated GIF for Slack, Notion, slides, or any place that does not play SVG animation. Options: --step <n> for one step, --dark, --fps, --scale, and --mp4 to also write an MP4.

Improvements

• After npx flowfig init, agents use flowfig when you ask for a diagram and name no other tool. In Claude Code, you can also run /figure <question>.
• Agent replies end with the npx flowfig open command for the new figure.
• flowfig init has a new screen: pick your agents with the arrow keys and the space bar.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine. Set CHROME_PATH to choose one.
• flowfig gif --mp4 also needs ffmpeg on your PATH.

Upgrade

No breaking change. Run npx flowfig init again in your repo to get the new agent instructions.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.3.0...v0.4.0

The release on GitHub

0.3.0 (2026-09-30)

One command from a question to a figure, captions you can read, a box that lights up when the packet arrives, and colors for the outcome.

npx flowfig draw "how does login work"

New

• flowfig draw "<question>". Runs Claude Code on your repo to draw the figure, then checks it with check --strict and verify. It prints the result, the agent’s reply and the cost. Needs Claude Code on the machine.
• tone on a hop and on a box. green for success, orange for a warning or a miss, red for an error, gray for idle, purple for async. The packet, the edge, the arrowhead and the box take the color.
• Links to documents. source can point to a Markdown heading, for example docs/sop/refunds.md#step-3-approve-the-refund, so a process figure stays in step with its SOP.

Improvements

• Readable timing. Each step holds long enough to read its caption. An explicit ms on a step still wins.
• Arrival look. The box that a packet reaches gets a border, a tint and a glow, then fades. Boxes the step visited keep a light trail.
• Agents now color the outcome with tone and mark every queue send and unawaited call as async.

Fixes

• A short hop in a long animation no longer jumps.
• White text on the orange tone now has enough contrast, and check tests text on every tone.
• Fixes in the GitHub Action’s install step.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig draw needs Claude Code. It does not run on Windows yet.

Upgrade

No breaking change. Figures get the new timing and look the next time you render them.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.2.0...v0.3.0

The release on GitHub

0.2.0 (2026-09-30)

Figures that link to the code they draw, a GitHub Action that checks them on every pull request, and an MCP server for agents with no shell.

npx flowfig verify docs/*.svg   # fails when a linked file or symbol is gone

New

• Code links. A box, an edge or a hop takes "source": "src/auth/login.ts#verifyPassword". The link is stored in the SVG with the spec.
• flowfig verify. Checks every link and reports missing-file, missing-symbol and no-source. Options: --root, --strict, --json.
• flowfig diff old.svg new.svg. Shows what changed between two figures: boxes, edges, steps, messages, groups and the rail. --md for a PR comment, --json for a script.
• GitHub Action. uses: iamalvisng/flowfig@v0.2.0 runs verify on every figure in a PR. For each changed SVG, it comments the old and new image with the diff, and it names each figure whose linked code the PR changes.
• flowfig mcp. An MCP server over stdio with the tools docs, check, render, verify and diff.
• flowfig init registers the MCP server for Claude Code, Cursor, GitHub Copilot, Gemini CLI and Kiro. It adds one entry and never replaces an entry that you changed. --no-mcp skips it.
• New entry point flowfig/verify for Node. flowfig and flowfig/svg still load in a browser.

Improvements

• Agents now add code links to their figures and run verify before they reply.

Fixes

• flowfig --help, -h and help print the usage.
• A rail with many messages over several steps no longer reports a false label-overlap.
• A clean render prints 0 errors, 0 warnings.
• flowfig --spec on a missing file prints a message, not a stack trace.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

No breaking change. Figures without links pass verify with a no-source warning.

Full Changelog: https://github.com/iamalvisng/flowfig/compare/v0.1.0...v0.2.0

The release on GitHub

0.1.0 (2026-09-29)

The first public release. Your coding agent draws animated diagrams of your code, and flowfig checks them.

npx flowfig init

Then ask your agent: “draw a diagram of how login works in this repo”.

New

• Three forms. A map of boxes and edges, a map with a lifeline rail for sequences (rail: true), and the rail alone (rail: "only").
• One animated SVG with no script. It works in a GitHub README, PR or issue, in light and dark mode. Each SVG carries its own spec, and npx flowfig --spec <file> reads it back.
• flowfig check. Finds ids that point nowhere, text wider than its box, edges through boxes, overlapping labels, hidden edges, text too small at the README width, and low contrast. --strict and --json for CI and agents.
• flowfig init. Sets up Claude Code, Cursor, GitHub Copilot, Codex and other AGENTS.md agents, Gemini CLI, Windsurf and Kiro to draw with flowfig.
• flowfig docs. Prints the guide for agents.
• React player. <Flow /> with tabs, pause, speed, hover and full screen.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• No runtime dependencies.

MIT license.

The release on GitHub