AIGUI

io.github.liliang-cnv0.48.0Updated Oct 4, 2026

Let coding agents draw charts, diagrams, 3D, molecules and animated topologies as PNGs or live pages

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & DesignData & Analytics

Overview

AI-generated overview

Lets a coding agent render charts, diagrams, 3D scenes, molecules and infrastructure topologies as PNGs or live local pages.

What it does
AIGUI turns markdown blocks written by the agent into pictures: ECharts charts, Mermaid diagrams, KaTeX maths, dashboards, 3D scenes, molecules from SMILES, orbits, knowledge graphs and step-by-step topologies. Tools include aigui_guide for block syntax, aigui_render for PNGs, aigui_open for a live page, aigui_edit for find-and-replace edits, aigui_export for PNG, PDF, HTML, GIF or WebM, aigui_topology for docker-compose or Kubernetes manifests, and aigui_feedback for reading user comments. A headless browser checks each drawing for overlapping labels, cut-off or tiny text and poor contrast before the agent sees it.
When to use it
Useful when an agent's answer is easier to understand as a picture than as prose, for example charts from data files, architecture diagrams, or infrastructure topologies read from real deployment config. It also suits workflows where the user wants to comment on a rendered page and have the agent revise it.
Requirements
Runs locally over stdio as the npm package @ai-gui/mcp; requires Node.js 18.11 or newer. The first drawing downloads a headless browser of about 100 MB, which can be skipped with AIGUI_NO_BROWSER_DOWNLOAD=1 to use an installed Chrome or Edge. No account or API key is needed. Optional variables include AIGUI_OUT_DIR, AIGUI_NO_OPEN, AIGUI_OPEN_IMAGES, AIGUI_PLUGIN_DIR and AIGUI_BROWSER_CHANNEL.
Before you install
Pages are served on 127.0.0.1 on a system-chosen port while a session runs, and only the pages directory is served. Output is written to the cache directory by default. Custom blocks are plain browser scripts whose HTML is sanitized, but they are third-party code loaded into pages. The first run downloads a browser unless that is disabled.

Installation

In SourceWeft

  1. Open AIGUI in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@ai-gui/mcp

[npm] [license] [CI]

Let your coding agent draw. An MCP server — and the engine of the AIGUI plugin for Claude Code and Codex — that turns charts, diagrams, maths, 3D scenes, molecules, orbits, dashboards and step-by-step infrastructure topologies into PNGs the agent can check, or a live page in your browser.

[A failover topology, drawn and played by the agent]

Live demos · Source · All packages

Install

Claude Code — the plugin also brings the skills that tell the agent when a picture beats text:

text
/plugin marketplace add liliang-cn/aigui/plugin install aigui@aigui

Codex:

sh
codex plugin marketplace add liliang-cn/aiguicodex plugin add aigui@aigui

Any MCP client — run aigui-mcp over stdio:

sh
npm install -g @ai-gui/[email protected]claude mcp add aigui -- aigui-mcp

Requires Node.js 18.11+. The first drawing downloads a headless browser (about 100 MB, once); everything runs locally, with no account or API key.

What it draws

[Chart][3D scene]
[Molecule][Orbits]

21 block types: ECharts charts (3D too), Mermaid, KaTeX, dashboards and data walls, 3D scenes, molecules from SMILES, orbits and collisions, topologies whose steps play, knowledge graphs, geometry, function plots, optics, mechanics, labelled figures, candlesticks, tables and more. Nine of them render straight to PNG; all of them draw in a page.

Tools

ToolWhat it does
aigui_guideLists the blocks, or returns the exact syntax for the ones named — read before writing a block.
aigui_renderDraws the blocks in a markdown string as PNGs, returned to the agent and saved to disk.
aigui_openOpens the whole answer as a live page: charts to hover, 3D to turn, topologies and walls that play.
aigui_editChanges part of a page by find-and-replace, without sending the whole answer again.
aigui_exportSaves a page as PNG, PDF, one self-contained HTML file, or a GIF / WebM of it playing.
aigui_topologyDraws a system from its docker-compose file or Kubernetes manifests.
aigui_feedbackReads the comments the user left on a page's blocks.

Why it can be trusted

  • Numbers come from your files. Pass data: {"sales": "/abs/path/sales.csv"} and write {"$data":"sales","column":"revenue"} in the chart — or pick, sum, count, max, min, avg. The figures are read from the file, never retyped by the model, and the result names the file behind each block.
  • Every drawing is checked. A headless browser looks for labels on top of each other, text cut off or under 9 px, poor contrast and crowded charts, and tells the agent to fix them before you see anything.
  • Topologies from real config. aigui_topology reads what is actually deployed, not what the model remembers.
  • Local. Pictures go to ~/.cache/aigui/images, pages to ~/.cache/aigui/pages, listed newest first in pages/index.html. A page loads nothing from the network.

Custom blocks

Add your own block type in three files — no build step, no fork:

sh
npx @ai-gui/cli plugin new ticket   # writes ~/.config/aigui/plugins/ticket/
FileWhat it is
aigui.jsonName, fences, a one-line description, whether it may render to PNG
plugin.jsA plain browser script registering an AIGuiPlugin: (globalThis.__aiguiPacks ??= {}).ticket = (theme, still) => [...]. Its HTML is sanitized like any plugin's.
spec.mdThe rules the model follows to write the block

It then appears in aigui_guide as [custom] and draws in pages, PNGs and exports. Blocks installed when a session starts are named in the tool descriptions too: in a measured run, agents used a custom block in 9 of 9 sessions with that, against 5 of 9 without. A broken folder is skipped with its reason; a name that collides with a built-in block is refused.

Comments from the page

While the session runs, pages are served on 127.0.0.1 (a port the system picks) with a Comment button: pick a block, say what should change, send. The agent reads it with aigui_feedback and edits the page. Only the pages directory is served.

Configuration

VariableEffect
AIGUI_OUT_DIRWhere pictures and pages go. Default ~/.cache/aigui (XDG_CACHE_HOME honoured).
AIGUI_NO_OPEN=1Write pages without opening them.
AIGUI_OPEN_IMAGES=1Also open aigui_render's PNGs in the image viewer — the plugins set it, since a terminal cannot show images.
AIGUI_PLUGIN_DIRWhere custom blocks live. Default ~/.config/aigui/plugins.
AIGUI_NO_BROWSER_DOWNLOAD=1Skip the headless-browser download; draw with an installed Chrome or Edge.
AIGUI_BROWSER_CHANNELPin a browser: chromium, chrome or msedge.

Programmatic use

ts
import { createServer, callTool, renderToContent, writePage } from "@ai-gui/mcp"

createServer() returns the McpServer unconnected, for a host with its own transport; callTool(name, args) runs one tool directly.

License

MIT © Liang Li

Source: packages/mcp/README.md at commit b3a8bd7

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.48.0LatestOct 4, 2026