Input A Mermaid only
flowchart TD
request[Request] --> auth{Authorized?}
auth -->|yes| api(API)
auth -->|no| reject[Reject]Agent must reconstruct:
- which node branches
- the two possible terminal paths
- what shape and arrows do—or do not—mean
Mermaid in · graph2agent · explicit context out
Mermaid diagrams,
explained for agents.
graph2agent turns Mermaid diagrams into explicit text for coding agents. Keep the diagram for people; add deterministic context that spells out the elements, connections, branches, order, topology, and what the notation does not prove. Humans can scan the picture visually; an agent receiving only Mermaid source must reconstruct those relationships from compact syntax.
In one frozen paired benchmark, adding that text cut exact-comprehension failures from 121 to 60.
- Diagram stays for humans
- Rich text goes to agents
- Deterministic · no model call
```mermaid
flowchart TD
Request --> auth{Authorized?}
auth -->|yes| API
auth -->|no| Reject
```Agent explanation · hidden in rendered Markdown
<!-- graph2agent:begin …
Branch candidate: `Authorized?`.
`Authorized?` points to `API`, labeled “yes”.
`Authorized?` points to `Reject`, labeled “no”.
Terminal nodes: `API` and `Reject`.
Shape does not prove runtime decision semantics.
graph2agent:end -->Why agents need the text
Humans see the picture.
Agents need the structure spelled out.
Mermaid compresses many relationships into a few lines. As diagrams gain branches, loops, and participants, graph2agent expands the authored structure into explicit text while preserving the original diagram.
Input B Mermaid + graph2agent
Elements
- `Request` is a rectangle.
- `Authorized?` is a decision-shaped element.
Explicit relationships
- `Request` points to `Authorized?`.
- `Authorized?` points to `API`, labeled “yes”.
- `Authorized?` points to `Reject`, labeled “no”.
Derived topology
- Branch candidate: `Authorized?`.
- Terminal nodes: `API` and `Reject`.
Interpretation limits
- Shape does not prove runtime decision semantics.Structure and limits are explicit
Illustrative compilation example; the measured study is reported below.
+18.48pp
exact contract-comprehension lift in one frozen, paired benchmark of330 private contracts
Read the evidence boundaryOne compiler, four launch surfaces
Generate once. Keep every consumer current.
Core v0.2.1, Action v0.3.0, Homebrew, and direct Debian downloads are public. MCP v0.2.0 is prepared for npm publication; the signed APT repository is staged but not live.
- 01
Paste one, or generate them all
Install with Homebrew or a verified amd64 or arm64 Debian package. Paste one diagram for rich text on stdout, or put the repository update after your existing generators.
brew install graph2agent/tap/graph2agent
graph2agent describe --profile interpreted-v3 -
make generate - 02
Plug-and-play MCP
The prepared npm umbrella package gives an MCP-capable agent the tool without a manual native download. This command becomes live when
v0.2.0is published to npm.npx -y graph2agent-mcp@0.2.0 - 03
Block stale merges
Make a read-only
graph2agent check .job required before a pull request can merge.uses: graph2agent/github-action/.github/workflows/check-markdown.yml@7c57998614ba579be55829423eaaa1262c35eff4
with:
graph2agent-version: v0.2.1 - 04
Let the bot maintain it
Run daily, change only generated Markdown context, and reuse one focused refresh PR until it merges.
uses: graph2agent/github-action/.github/workflows/maintain-markdown.yml@7c57998614ba579be55829423eaaa1262c35eff4
with:
graph2agent-version: v0.2.1
Measured, with the caveats attached
The digest helped on the frozen task set.
The frozen paired result supports efficacy on this benchmark. It does not by itself prove broader model, task, or production generalization.
Mermaid alone
63.33%
209 / 330 exact
Mermaid + standard digest
81.82%
270 / 330 exact
Relative failure reduction
50.41%
121 failures reduced to 60; this is a relative error metric
Observed aggregate token counts. Mermaid + graph2agent relative to Mermaid-only across the same 330 paired cases.
8.17%more input tokens
14.13%fewer output tokens
46.30%fewer reasoning-output tokens
What this does not establish
Evidence is a boundary, not decoration.
- One frozen, generated contract benchmark is not every software-engineering task.
- The requested configuration was Codex CLI 0.146.1, gpt-5.6-sol, high reasoning; resolved backend identity was unavailable.
- Only the supported Mermaid subset and the frozen
standarddigest were tested in this confirmatory result. - Monetary cost was missing from native traces, so it is unavailable—not zero.
- Some Markdown ingestion pipelines strip HTML comments; end-to-end agent integrations still require validation.
Keep the diagram. Add the explanation.