Show HN: Reladraw – A diagram language where you decide where to place things

Show HN: Reladraw – A diagram language where you decide where to place things github.com

Contribute to reladraw/reladraw development by creating an account on GitHub.

407 points•jpwalsh234•4 days ago•119 comments•

#diagram #reladraw #decide #diagram language #place #like #agents #x27

I love making diagrams to help understand, plan, etc. However, the options are (A) auto-placement languages like Mermaid or Graphviz (which don't let me decide how the diagram looks), or (B) software like Draw.io which are powerful but are very time consuming (and inefficient for agents to manipulate).

I wanted to have the benefits of both, where you can define a diagram in a diagram language, but also retain a high degree of control over what the diagram looks like.

I also wanted this to work well for humans and agents.

On the Github link, there's a playground where you can try it out without installation. There's also instructions for a simple npm install and for installing a skill you can use with Claude or other agents.

119 comments

apinstein4 days ago

This is very needed in the AI coding age! I find diagramming is one of the best ways for high bandwidth alignment between my mental model and the agent’s. I have been working on this problem a bit as I see good visuals as a key bottleneck in faster development while maintaining a real architecture.

Will def be adding this to my list of diagramming tools the agent can use!

jpwalsh2344 days ago

It's funny, you articulated it very similar to how I feel! Seems like we need ways to maintain mental models at a high enough level of abstraction when working with agents.

There's a skill in the repo that you can install using `npx skills` to get started with. I'm sure the integration of Reladraw with agents can be made way better, though. It's just a bit... basic/rudimentary right now!

Towaway694 days ago

Won’t it be a good idea to stay at the visual level?

Instead of generating visuals from text and then back to text, just communicate visually with your agents.

Something like UML provides a certain granularity to be able to code something usefully in pure visual language. Of course there are other visual programming languages that provide more depth and would probably be better suited.

Point remains that a solution based on constantly mapping better two different representations of the same thing won’t be a long term efficient solution.

WillAdams3 days ago

For my part, I've found Literate Programming to be the best lever on this for my own work, and there has been some discussion of other folks being successful applying it to LLM work:

https://news.ycombinator.com/item?id=47300747

tamimio4 days ago

I tried most of the diagrams out there, the best thing is installing drawio skill and make it generate one for you based on your description.

loveTech3 days ago

Exactly! I'd like to give it a try as well!

atombender3 days ago

The readme says:

> Mermaid, Graphviz and D2 let you declare boxes and connections, then determine positions for you. If you have a particular picture in mind, these aren't the right tool.

D2's layout engine TALA [1] actually allows you to provide a lot of manual control. TALA used to be commercial, but is now open source.

In my own testing, TALA tends to produce much better layouts than Mermaid, including the ELK layout algorithm (which is not Mermaid's default; D2 also supports ELK).

TALA supports controlling direction per container, defining which shapes have to be near each other, and so on. I've not played with this yet, though.

[1] https://d2lang.com/tour/tala/

jpwalsh2343 days ago

Thanks for mentioning TALA. I feel like TALA does add more control than Mermaid, but in spirit sits closer to Mermaid than Reladraw. It keeps the auto layout, but with extra ways to coax the diagram into a different shape, by saying things like "keep this node pinned over here" or "keep these nodes close to one another".

For the diagrams I usually want to create, that's still not enough control to create what I envision.

recroad4 days ago

Seems a little buggy, I added this line:

edge parser -> renderer "test edge" from: left to: right

and it wasn't smart enough to make a curved arrow

jpwalsh2344 days ago

Bug is fixed in the playground. Thanks again for catching it!

It gave me some ideas to make routing better, too. For example, maybe you don't want the edge to curve above, but rather below. Or, in more complex examples, maybe you want the edge to curve above one thing and to the right of another.

(will update npm shortly too)

recroad3 days ago

This is just for me, but I don't think I want to get into the business of specifying placement in that much detail. It would too cumbersome and I'd rather focus on what I want the diagram to convey, rather than how.

jpwalsh2344 days ago

Genuine bug! Good find. I'll look into a fix.

picardo3 days ago

Love it! I created a VSCode extension to render it in markdown files and highlight its syntax: https://github.com/volkanunsal/relative-diagrams-vscode/

jpwalsh2343 days ago

Thanks for making that! Just a heads up, reladraw is changing super fast - I think the rendering/highlighting will work smoothly with syntax changes, the more annoying thing would be any JS API breaking changes.

picardo3 days ago

No problem! I hooked up dependabot to detect upstream changes, so when you bump up the version number, it should create a PR and bump the version number of the extension, and I will merge. I think the unit tests should catch any regression.

HeavyStorm4 days ago

Mermaid works great for fixed layouts like sequence diagrams and Gantts. For flowcharts, where position is king, it's bad.

I've tried using svg in my MD files but they get unwieldy quite fast. This is a great idea. My first reaction was - but what's if I need something more exact. But reflecting on it, I've realized that this relative positioning is probably enough.

jpwalsh2344 days ago

Yea, it's hard to beat absolute positioning if you want something ultra-custom, but I'm hoping for most flowcharts, mind maps, etc. the relative positioning is enough to get what you want without fiddling too much!

y-curious4 days ago

Agreed. Next diagram I make I’m taking a photo of a whiteboard and letting AI figure out relative positioning

jpwalsh2344 days ago

That sounds very cool :)

Read the full thread on Hacker News →

119 comments

Related stories