Agent Diagram Pipeline

Agent Diagram Pipeline is a docs-first project for turning AI-generated diagram source into deliverable visual artifacts.

The project starts from a concrete pain point:

• AI tools often output Mermaid code instead of a usable diagram
• end users consume results in chat channels, not only in web UIs
• moving between third-party renderers breaks the workflow

This project treats diagram rendering as agent infrastructure, not a standalone toy converter.

Initial thesis

The first real integration target is OpenClaw.

OpenClaw is a strong proving ground because:

• it already supports agent tools
• it already supports artifacts and viewers
• it already sends files through multiple chat channels
• the Mermaid pain appears in real user workflows

The goal is to build a renderer that can later serve:

• OpenClaw
• Codex-like local agents
• Claude Code style tool pipelines
• MCP or HTTP consumers

Project shape

This repository is intentionally documentation-first.

Current scope:

• define the product
• define the architecture
• define the MVP
• define the OpenClaw integration strategy
• define the expansion path
• ship a working local Mermaid rendering pipeline

Docs

• Project Decision
• Product Spec
• Architecture
• MVP Scope
• OpenClaw Integration
• Install In OpenClaw
• OpenClaw follow-up Mermaid images
• Roadmap

Working name

agent-diagram-pipeline

The name is deliberately broader than Mermaid because Mermaid should be the first engine, not the last one.

Current status

The project now includes a working local baseline pipeline for Mermaid:

• Mermaid source to SVG
• SVG to PNG
• local artifact folder creation
• local viewer HTML generation
• CLI entry point
• an OpenClaw adapter layer with:
  • render_diagram tool factory
  • plugin entry factory
  • artifact HTTP handler
  • prompt guidance for Mermaid-heavy agent turns

Local usage

Install dependencies:

npm install

Build:

npm run build

Validate the package contract:

npm run check

Render a diagram:

node dist/cli.js render \
  --input ./example.mmd \
  --mode both \
  --fileFormat png \
  --theme dark \
  --title "Example"

The command returns JSON with artifact paths for:

• diagram.svg
• diagram.png
• viewer.html

Run a local smoke test:

npm run smoke

OpenClaw adapter

The repository now includes a thin OpenClaw-oriented adapter in src/adapters/openclaw.

It provides:

• createOpenClawRenderDiagramTool()
• createOpenClawRenderMermaidBlocksTool()
• createOpenClawDiagramPlugin()
• createOpenClawDiagramHttpHandler()

The adapter is intentionally thin:

• the core renderer stays independent
• the OpenClaw layer only maps tool execution and artifact delivery
• viewerUrl and file URLs are built from the artifact id and route prefix
• render_mermaid_blocks can extract Mermaid directly from a markdown reply draft and emit attachment-ready images

Browser configuration

Rendering uses Playwright + Chromium. Prefer an explicit browser:

• plugin config browserPath or browserChannel
• env OPENCLAW_DIAGRAM_BROWSER_PATH or OPENCLAW_DIAGRAM_BROWSER_CHANNEL

If unset, the pipeline tries Playwright’s bundled Chromium, then common OS install paths (see src/renderers/mermaid/runtime.ts).

Optional extras:

• browserArgs, headless, artifactDir, env OPENCLAW_DIAGRAM_ARTIFACT_DIR
• OPENCLAW_DIAGRAM_BROWSER_POOL=1 — reuse one browser process across renders (lower latency on gateways; default off for CLI isolation)

After install, run a local render smoke (no OpenClaw required):

npm run diagnose

Automatic follow-up images (message_sent)

When followUpMermaidImage is on, the plugin sends extra native image messages after outbound text that contains fenced Mermaid.

| Channel | Mechanism | | --- | --- | | Telegram / Discord / Slack | runtime.channel.*.sendMessage* with mediaUrl + mediaLocalRoots | | Feishu / Lark | sendMediaFeishu (or sendMessageFeishu fallback) on runtime.channel.feishu or .lark | | Webchat | runtime.outbound.deliverOutboundPayloads (payloads include mediaUrl / mediaUrls) — aligns with merged UI replies; fallback sendMessageWebchat if exposed | | Other channels | No auto follow-up — use render_diagram / render_mermaid_blocks so the model attaches artifacts or MEDIA: lines |

Follow-up tuning (env):

• OPENCLAW_DIAGRAM_FOLLOW_UP_MAX_NODES (default 120), OPENCLAW_DIAGRAM_FOLLOW_UP_MAX_EDGES (default 200) — skip very large diagrams fast
• In-memory file cache reuses PNG paths for identical source + title + theme + artifactDir within TTL (see follow-up-mermaid.ts)

Screenshot stability: Mermaid PNG uses a lower deviceScaleFactor, longer screenshot timeout, and page.screenshot({ clip }) on .preview-shell instead of locator.screenshot() to reduce Playwright timeouts on large diagrams.

OpenClaw channel behavior (tools)

For every channel, the reliable path is:

• keep the normal text reply
• call render_mermaid_blocks or render_diagram when you need guaranteed attachments

The plugin emits MEDIA: directives where appropriate so OpenClaw can send real attachments. Feishu/Lark users should ensure artifact / workspace paths are allowed by OpenClaw’s local media policy (mediaLocalRoots / plugin follow-up roots).

Zero-config defaults

The plugin now defaults to:

• autoRenderMermaid: true
• autoRenderMaxBlocks: 2
• loopback gateway base URL http://127.0.0.1:18789 when no explicit baseUrl is configured

You can override with:

• baseUrl
• OPENCLAW_DIAGRAM_BASE_URL
• OPENCLAW_GATEWAY_PORT