mindmaply

Mindmaply for AI agents

Diagramming tools expect a human with a mouse. Mindmaply expects text. The same source always produces the same diagram, so an agent can write a mind map the way it writes code: generate, validate, render, hand over a link.

Why an agent can actually use this

• Deterministic. No canvas, no dragging, no layout choices. Layout, spacing, and colour are decided by the renderer.
• Verifiable. mindmaply validate exits 1 and prints line N: message for every bad line, so a model can fix its own output in a loop instead of guessing.
• Offline. Rendering and validation need no network. Only share links and PNGs do.
• Structured output. The API returns a parsed model graph of nodes and edges alongside the SVG, so the next step in a pipeline reads data rather than pixels.

1. Install the Agent Skill

The richest option. It teaches your assistant the grammar, the quality bar for a good map, and the whole render, validate, and share workflow. One command installs it into every compatible agent it finds on your machine:

npx skills add productscalexyz/mindmaply

• Claude Code
• Codex
• Cursor
• Windsurf
• GitHub Copilot
• Gemini

To install by hand, copy skills/mindmaply into your agent's skills directory:

Tool	Directory
Claude Code	.claude/skills/
Codex	~/.agents/skills/
Cursor	.cursor/skills/
GitHub Copilot	.github/skills/

For claude.ai, zip the skills/mindmaply folder and upload it under Settings, then Skills. No build step is needed: the skill drives the published npm package through npx.

As a Claude Code plugin

Claude Code can also install it as a plugin, which keeps it updated with the repo:

/plugin marketplace add productscalexyz/mindmaply
/plugin install mindmaply@mindmaply

2. Call the CLI

No skill, no install, no account. Works in any shell and in CI.

npx -y mindmaply-core render map.md -o map.svg

mindmaply render   [file] [--format markdown|mermaid] [--direction LR|TD]
                          [--edge-style curved|straight] [-o out.svg]
mindmaply validate [file] [--format ...]   # exit 1 + line errors if invalid
mindmaply share    [file] [--short]        # share, embed, and image URLs as JSON
mindmaply convert  [file] --to markdown|mermaid

Source comes from a file argument or stdin, so it pipes:

printf '# Plan\n- research\n- build\n' | npx -y mindmaply-core render - -o plan.svg

--format is auto-detected. Default direction is LR, and TD suits org charts and top-down flows. share --short returns a tidy mindmaply.app/s/<id> link instead of one carrying the whole encoded map.

3. Call the HTTP API

No Node at all. The base is https://api.mindmaply.app and CORS is open.

curl -X POST https://api.mindmaply.app/render \
  -H 'content-type: application/json' \
  -d '{"source": "# Plan\n- research\n- build"}'

Endpoint	What it does
POST /render	SVG plus the parsed model graph and every share, embed, and image URL, as JSON. Also accepts GET with query params.
GET /svg?source=	The SVG directly, as image/svg+xml. Works in an <img src>.
GET /png?source=	The same as PNG.
POST /shorten	Trades a long d payload for a short id. Content-addressed, so the same map gives the same link back.
POST /transform	Give it {"text": "..."} or an image and its own AI writes the map for you.
POST /yt/transform	Give it {"videoId": "..."} and get a map of the video, with title, author, and a short share link.

Requests accept either a raw source string or an encoded d share payload. source is capped at 20,000 characters. Longer maps still render locally through the CLI.

The model field

The reason to prefer /render over /svg in a pipeline: you get the graph back, not just a picture of it.

{
  "svg": "<svg …>",
  "model": {
    "layout": "curved", "direction": "LR",
    "nodes": [{ "id": "n0", "label": "Plan", "shape": "root" }],
    "edges": [{ "from": "n0", "to": "n1" }]
  },
  "sharePageUrl": "…", "embedCode": "…", "pngUrl": "…"
}

The grammar, briefly

A Markdown outline is the default and handles most cases. Exactly one # Title on the first line, then headings and - bullets at two-space indents:

# Remote Work Playbook

## Communication
### Async first
- Write decisions down
- Default to public channels

## Tools
- Shared docs
- One place for tasks

For processes with real branching and cycles, use the Mermaid flowchart subset:

flowchart LR
a[Draft] --> b{Review}
b --> c[Ship]
b --> a

This is a deliberately minimal subset. Chained edges, edge labels, dashed arrows, subgraphs, and classDef are not supported, so most full-Mermaid documents will not validate. Always run validate.

The complete grammar, URL shapes, and worked examples live in one plain-text file built for LLMs: llms-full.txt. There is also a short index at llms.txt and a human-facing syntax reference.

Open source

MIT licensed, all the way down. The renderer, the editor, the skill, and this page are in one repository, and the library is on npm as mindmaply-core. Self-hosting? Point the CLI elsewhere with --base and --api-base.