{"slug": "show-hn-graph2agent-mermaid-diagrams-explained-for-agents", "title": "Show HN: Graph2agent; Mermaid diagrams, explained for agents", "summary": "Graph2agent, a new open-source tool, converts Mermaid diagrams into rich text for AI agents, reducing errors by 50% across diagram classes and 80% for sequence diagrams, while cutting reasoning tokens by nearly 50%. Built by a developer to help agents read diagrams, it can be used via MCP or in pre-commit jobs.", "body_md": "During the implementation of a huge high performance service. In order to keep context small (mainly for humans) I kept the specs into mermaid diagrams. When communicating with humans; diagrams were easy to follow and to remember. But when I asked the agent to implement what's in the diagram, most of the times it failed.\n\nSo I came into conclusion that agents are good into writing mermaid diagrams but they are not good into reading them.\n\nI built graph2agent in order to deterministically (without inference :) ) convert mermaid diagrams into digestible rich text for agents. examples: [https://github.com/graph2agent/examples/blob/main/examples/m...](https://github.com/graph2agent/examples/blob/main/examples/markdown/five-families.md?plain=1)\n\nThis gave us 50% error reduction for any class of diagrams and 80% error reduction for sequence diagrams specifically. Also Input tokens increased on avg by 8% (which is expected) but Reasoning tokens dropped by almost 50%.\n\nYou can use it either with MCP so agents can call it with any mermaid diagram, and also can put it in pre-commit jobs and run it on every PR so all diagrams are agent ready!\n\nI hope you like it! Let me know your thoughts!\n\nComments URL: [https://news.ycombinator.com/item?id=49250014](https://news.ycombinator.com/item?id=49250014)\n\nPoints: 1\n\n# Comments: 0", "url": "https://wpnews.pro/news/show-hn-graph2agent-mermaid-diagrams-explained-for-agents", "canonical_source": "https://graph2agent.github.io/", "published_at": "2026-08-10 21:29:40+00:00", "updated_at": "2026-08-10 21:41:34.719812+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Graph2agent", "Mermaid", "MCP"], "alternates": {"html": "https://wpnews.pro/news/show-hn-graph2agent-mermaid-diagrams-explained-for-agents", "markdown": "https://wpnews.pro/news/show-hn-graph2agent-mermaid-diagrams-explained-for-agents.md", "text": "https://wpnews.pro/news/show-hn-graph2agent-mermaid-diagrams-explained-for-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-graph2agent-mermaid-diagrams-explained-for-agents.jsonld"}}