Quickstart

Set up your repo:

npx flowfig init

Then start a new agent session. In Claude Code, run:

/figure how does login work

With any agent, ask in plain words:

draw a diagram of how login works in this repo
use flowfig to draw the checkout flow as a sequence
draw the refund process with a lane for each team

The agent writes an SVG and ends its reply with npx flowfig open <path>. Run that command to see the animation in your browser.

init sets up 7 agents: Claude Code, Cursor, GitHub Copilot, Codex and other AGENTS.md agents, Gemini CLI, Windsurf and Kiro.

The files init writes

npx flowfig init writes flowfig instructions for the coding agents of a repo. The instructions tell the agent how to write a spec, check the spec, and render the SVG.

npx flowfig init            # the current directory
npx flowfig init path/to/repo

On a terminal, init shows a picker. The picker selects the agents that the repo already uses. If it finds none, it selects AGENTS.md. Type the numbers to toggle agents, press Enter to write, or type q to quit.

Id	Agent	File	How
claude	Claude Code	.claude/skills/figure/SKILL.md	whole file (a skill)
agents	AGENTS.md	AGENTS.md	section (for Codex, Amp, Jules, …)
cursor	Cursor	.cursor/rules/flowfig.mdc	whole file
copilot	GitHub Copilot	.github/copilot-instructions.md	section
gemini	Gemini CLI	GEMINI.md	section
windsurf	Windsurf	.windsurf/rules/flowfig.md	whole file
kiro	Kiro	.kiro/steering/flowfig.md	whole file

Flag	Effect
--agents <ids>	Write for these agents, for example --agents claude,cursor.
--all-agents	Write for all 7 agents.
-y, --yes	Write for the agents that the repo uses, with no picker.
--global	Write the Claude skill and the MCP entry to your home folder.
--dry-run	Print what init would write, and write nothing.
--no-mcp	Do not register the MCP server.
--list-agents	Print the agent ids.

With no terminal and no -y, --agents or --all-agents, init prints the agent ids and exits with code 2.

A section sits between <!-- flowfig:start --> and <!-- flowfig:end -->. A second run replaces that section and keeps the rest of the file. A second run also replaces a whole file that init wrote. If a whole file exists and did not come from init, init skips the file. init also skips a section file that has a start marker and no end marker.

npx flowfig docs prints the core guide as Markdown. npx flowfig docs <topic> prints one topic: lanes, timeline, rail, marks or verify.

One command

npx flowfig draw "how does login work"

draw runs Claude Code on the repo with the flowfig guide. It gives Claude Code the tools Read, Glob and Grep, and npx flowfig. draw disallows the tools Edit, MultiEdit and NotebookEdit. Claude Code writes the figure. Then draw checks the figure with check --strict and verify. draw prints the result, the reply of the agent and the cost of the run.

draw needs Claude Code on the machine and a login. draw does not run on Windows yet. --out sets the path, --model sets the model, --max-turns sets the turn cap (default 40), --json prints the result for scripts, and --open opens the figure.