Reladraw
github.com/reladraw/reladraw- Category
- Developer Tools
- Rank
- No. 1041Tools index
Previous survey · No. 1050 ·
- Type
- TOOL
- Use case
- Design & Media
- Interfaces
- Web · Agent Skill / Plugin
- GitHub
- 1.2k stars
- Latest release
- v0.25.0
- Date
About
Reladraw is a diagram definition language that lets users specify diagrams in text while keeping manual control over layout, unlike auto-placement tools such as Mermaid or Graphviz. It is designed to work well for both humans and AI agents, and ships with an npm package, a browser playground, and an installable skill for use with Claude or other coding agents.
What it does
You write a plain text file that says where each box sits relative to the others: right of the API, below the parser, level with the database. The tool then works out only the distances, packing everything as close as your statements allow, and writes a standalone SVG picture. Groups are written as nested names, lines between boxes route around anything in their way, and a file that leaves a position ambiguous is refused with an error naming the line, rather than guessed at.
Why it's ranked here
It fills a real gap between auto-layout languages, where the engine decides the arrangement, and drag-and-drop editors, where every position is manual. The case rests on observable choices: Apache 2.0, written in TypeScript with zero runtime dependencies, and three ways in (command line, a drop-in web page element, and a bundled agent skill). The agent angle is the sharpest part: because the arrangement is stated in words, an agent that cannot see its output can still reread its own source and know where things landed. The project is early, with the syntax openly declared unstable.
What's good
Layout is computed, not searched: placements become minimum distances solved in one deterministic pass, so the same source gives the same picture, and a set of placements that contradict each other is reported back in the author's own words. Error messages are written to teach, quoting the corrected statement when someone types a keyword from another diagram language. Several diagrams inlined on one page get their own internal names, so arrowheads and masks do not leak between them. The bundled agent instructions are candid that rereading the source confirms intent but not whether text overflowed or lines crossed.
Tradeoffs
The README calls it early stage and says the syntax will change, and the syntax reference records renamed and removed keywords between versions, so files written today may need edits later. Pull requests are not accepted; contributions go through issues only. Custom icons loaded from a file work only from the command line, not in the browser. The bundled agent skill is a snapshot, so it has to be reinstalled by hand after each release. Every box needs a stated position except one, which is more writing than auto-layout tools ask for.
How to use it well
Reach for it when you already have a specific picture in mind, such as an architecture or deployment diagram you would otherwise drag together by hand, and want it in version control as text. It suits agent workflows: install the skill, let the agent write and render, and treat errors as the feedback loop. For large or dense diagrams, still open the rendered picture, since the tool does not yet report overlaps or crossings. It is not for data charts, and if you are happy for an engine to choose the layout, an auto-layout language is less work.
Technical notes+
The pipeline is parse, resolve, render, chained by compile in src/index.ts, which on error calls blame from src/parser.ts to re-run the source with a multi-line statement truncated line by line and name the line that introduces the fault. src/constrain.ts turns placements into inequalities of the form pos[to] >= pos[from] + weight and solves them with tightest, a longest-path Bellman-Ford; a value still moving after one pass per node is walked back through cameFrom to the loop of contradicting placements. reachability (a Floyd-Warshall closure) decides which separations the file implies and which it leaves unordered. src/resolve.ts runs three passes (containment tree, bottom-up sizing, placement solve with separations re-solved until none remain) and throws when an icon names a file without a readIconFile callback, which src/cli.ts supplies relative to the diagram file. src/render.ts defaults to monospaceMeasurer for text extents and ownIds prefixes every id with an FNV-style hash of the SVG. package.json declares only devDependencies, a bin entry, and node >=18. .claude/skills/reladraw/SKILL.md is the agent skill; examples/arch.reladraw is the worked reference diagram cited by SYNTAX.md.
Observed
- License
- Apache-2.0 (LICENSE, package.json)
- Language
- TypeScript, ESM package (package.json)
- Runtime dependencies
- None; package.json lists only devDependencies
- Install surface
- npm package with a reladraw CLI binary; Node 18 or later required (package.json)
- Interfaces
- CLI, library export of compile/parse/resolve/render (src/index.ts), and a browser custom element (README.md)
- Agent integration
- Bundled agent skill in .claude/skills/reladraw/SKILL.md, installed via npx skills add
- Output format
- Standalone SVG, written to a file or standard output (src/cli.ts)
- Syntax stability
- README.md states the language is not stable and the syntax will change
- Contribution policy
- Pull requests not accepted; issues only (README.md)
- Icon files
- Readable only by the command-line tool; browser use requires pasted SVG (src/resolve.ts)
Read from README.md, package.json, LICENSE, SYNTAX.md, src/cli.ts, src/index.ts, src/parser.ts, src/constrain.ts, src/render.ts, src/resolve.ts, examples/arch.reladraw, .claude/skills/reladraw/SKILL.md.
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.