Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

md2ui

md2ui

md2ui is experimental. Its Markdown conventions, THEME.md keys, CLI, MCP tools and Python API can change between any two releases. It is tested on macOS only.

md2ui turns an ordinary Markdown document, such as an LLM's answer, into a rendered UI.

What it is for

An agent writes its reply as plain Markdown; md2ui groups it, lays it out and draws it as UI, styled by a THEME.md that belongs to the app showing it. Clicks on the buttons the agent wrote come back to the agent as sentences built from its own Markdown. The questions behind it: can plain Markdown carry enough to generate a good UI, can that UI couple with an existing front end's design system, and how cheap and compact can it be for the model that writes it?

The design comes from patterns observed in real LLM answers, from UI design samples and from several Gestalt principles, not from a spec: "what should this do?" is answered by looking at documents and designs.

Install

md2ui needs Python 3.13 or later. It depends on skia-python and glfw, and is tested on macOS. Only pre-releases exist: pip needs --pre, or pin the version.

The CLI, the app and the MCP servers, as commands on your PATH:

uv tool install md2ui                    # or: pip install --pre md2ui
uvx --from md2ui==0.1.0a1 md2ui render path/to/content.md    # one command, nothing installed

The library, for a backend that sends md2ui Markdown to its frontends:

uv add md2ui                             # or: pip install --pre md2ui, or pin md2ui==0.1.0a1

The frontend runs the same pipeline in the browser or a webview: md2ui-ts, on npm as @md2ui/dom, @md2ui/react, @md2ui/vue and @md2ui/wire under the alpha dist-tag (npm install @md2ui/dom@alpha). Its README is at github.com/md2ui/md2ui-ts.

Command Is
md2ui The CLI: render, layout, group, check. See The CLI
md2ui-app The window, with live reload. See The app
md2ui-mcp The authoring MCP server (stdio). See The MCP authoring server
md2ui-mcp-demo The live demo's MCP server, which opens the window. See Live demo with Claude
md2ui-wire The wire's reference server, which serves one document. See The wire reference server
md2ui-demo-activity The Claude Code hook the md2ui plugins run, so the demo's window says what Claude is doing. Not run by hand

To work on md2ui itself, from a checkout, see CONTRIBUTING.md.

Files md2ui reads at run time

The theme. md2ui and md2ui-app render a document with the first THEME.md they find:

  1. the one passed with --theme;
  2. THEME.md beside the document;
  3. THEME.md in the working directory;
  4. md2ui's default theme, shipped in the package.

Both print the one they used ([theme] …). md2ui-mcp and md2ui-mcp-demo use the theme passed with --theme. A MEANINGS.md beside THEME.md says what each of the theme's spellings is for; agents read it through guide. Every key of both files is in THEME_GUIDE.md.

What the package ships. The authoring notes an agent reads (skills/), the section patterns (patterns/), the default THEME.md and MEANINGS.md, the font lock (assets/fonts.lock), the icon font, the window's working animation and the image placeholders are inside the installed package, in md2ui/shipped/. To print where:

python -c "from md2ui import session; print(session.resource_root())"

Fonts. The package ships no text font. A font file a theme names is looked for beside the THEME.md, then in the working directory, then among md2ui's own files (the icon font). When assets/fonts.lock locks a file of that name (Inter, IBM Plex Mono and the other fonts of md2ui's themes), md2ui downloads it on first use into ~/.cache/md2ui/fonts ($XDG_CACHE_HOME/md2ui/fonts when that is set) and checks it against the locked SHA-256. A font named by an http(s) URL is downloaded as written. A font that cannot be found is logged under [fonts], and its text falls back to a system face.

Fetching. Fonts, pictures in the document and theme backgrounds are downloaded only where fetching is on:

Where Fetches
md2ui, md2ui-app Always
md2ui-mcp, md2ui-mcp-demo Only with --fetch; without it, pictures draw as placeholders
md2ui.mcp_server.build_server() in your own process Only with fetch=True

A hosted server keeps fetching off, so a URL a model wrote never becomes a request from inside its network. Put the fonts its theme needs beside its THEME.md.

A frontend's fonts. md2ui-ts measures and draws text only with the fonts its host gives it, so a backend serves THEME.md and every font file it names, for example beside its WebSocket with build_app(..., routes=[...]) (protocol/server-guide.md, The theme, to the client).

Render a document

Both md2ui and md2ui-app take the Markdown document itself and run the whole pipeline. skills/ says how to write Markdown that renders well; it is written for the LLM that writes it.

The app: md2ui-app

A window that stays in step with the document: save the Markdown and it re-renders.

md2ui-app path/to/content.md
md2ui-app path/to/content.md --width 1280 --wireframe
Option Does
--theme PATH Use this THEME.md
--width N Initial layout width; resizing the window lays it out again
--bento Start in the bento mosaic layout
--wireframe --debug --debug-padding --text-boxes Start with that overlay on: layout wireframe, spacing gaps, padding rings, text boxes
--connect URL Show a wire server's messages (ws://…/ws) instead of a file; clicks go back to it. Sends the secret in MD2UI_WIRE_BEARER, when set, as the server's bearer
--working-animation PATH With --connect: the animated WebP or GIF played while the agent works (default: the one shipped in the package)
--capture-requests DIR Answer screenshot requests written into DIR, so the agent driving the wire can see what the user sees
Key Does
R / T Reload the document / reload the theme
S Save the whole layout as a PNG in screenshots/ under the working directory, named after the document
E Save the layout tree as JSON beside the document
C / Shift+C Copy the Markdown on screen to the clipboard / save it as a timestamped .md beside the document
W D P B Overlays: wireframe, spacing gaps, padding rings, text boxes
I Force image placeholders
F Show or hide the frame (title, path and key hints); the window opens without it
G / K Toggle bento / section stacking
Arrows, PgUp PgDn Home, wheel Scroll; a code block wider than its box scrolls sideways under the pointer (Shift+wheel)
Click A web or mail link opens the browser, an #anchor scrolls, and agent: links and task boxes print their event as JSON; with --connect they go back to the server
Esc Quit. A --connect window closes only with ⌘Q or its close button

Drop another .md file onto the window to switch to it.

The CLI: md2ui

Every command runs once and exits: no window, no watcher, no prompt. It prints the path of what it wrote.

md2ui render path/to/content.md --width 1280 --out out.png
md2ui layout path/to/content.md --width 1280
md2ui group  path/to/content.md
md2ui check  path/to/content.md            # the document's authoring issues
md2ui check  --theme path/to/THEME.md      # the theme against its MEANINGS.md
Command Does Writes, beside the document unless --out
render Renders the page render-<width>w.png
layout Lays it out layout-dump-<width>.json, the layout tree
group Groups it grouping-ast.json, the grouper's tree
check Prints the document's authoring issues, the ones the MCP check tool returns; with --theme and no document, lints the theme against its MEANINGS.md and patterns Nothing
Option Applies to Does
--out PATH render, layout, group Where to write
--width N render, layout Layout width, default 1024; a document that needs more gets its own minimum
--theme PATH render, layout, check Use this THEME.md
--bento render, layout Force the bento mosaic layout
--scale F render Pixel scale, e.g. 2 for retina
--wireframe --debug --debug-padding --text-boxes render Draw that overlay
Exit status Means
0 Written; for check, no error-level issue (a theme lint always exits 0)
1 Nothing written: the grouper produced no tree, the page is too big for one bitmap, or the PNG did not encode; for check, the document has an error-level issue
2 Bad arguments

md2ui <command> --help lists the same.

Connect md2ui to an agent

The agent writes Markdown, following the notes in skills/. Its backend sends that plain Markdown to the frontend, which runs the pipeline with its own theme, fonts and assets. A click comes back as a small event naming the target; the backend verifies it against its own copy of the page and hands it to the agent as a sentence.

Your own backend

The library holds the wire's codec and verifier, and a WebSocket binding you can serve as is. A taste:

from md2ui.wire_server import Conversation, Served

conversation = Conversation()
served = Served(conversation, port=8765)                      # ws://127.0.0.1:8765/ws
served.call(conversation.send("# Hello\n\n[Say hi](agent:greet?to=you)\n"))
served.call(conversation.set_state("l"))                      # listening
print(served.next_event(timeout=60).agent_text())            # User chose "Say hi": greet {to: you} (message c1)

The MCP authoring server: md2ui-mcp

An MCP server (stdio) an agent uses to check the Markdown it wrote before its backend delivers it. Each call runs once, like the CLI. Register it with your agent's host; in Claude Code:

claude mcp add md2ui -- uvx --from md2ui==0.1.0a1 md2ui-mcp --theme /path/to/THEME.md
Option Does
--theme PATH The THEME.md, and the MEANINGS.md beside it, it checks and previews with
--fetch Load pictures, theme fonts and backgrounds as the window does. For a local install only, never a hosted server
Tool Returns
check Authoring issues, as errors, warnings and notes, each with its fix
actions What the answer offers the user, numbered by the wire's ordinal x, and which clicks come back to the agent
outline / layout The grouped structure / the layout shape at a width, compact
preview A PNG at a width
guide The skills/ notes by name; with no name, the core note to read first

The notes are also resources (md2ui://skills/<file>, and the server's theme as md2ui://theme). guide("patterns") lists short section patterns, and guide("pages") whole example pages.

The wire reference server

Serves one document over the wire, prints the sentence each click would hand an agent, and ticks task boxes itself, so the round trip can be seen:

md2ui-wire path/to/content.md --port 8765
md2ui-app --connect ws://127.0.0.1:8765/ws

Where md2ui is not installed in an environment, run it with uvx --from md2ui==0.1.0a1 md2ui-wire path/to/content.md.

Option Does
--host HOST The address to listen on, default 127.0.0.1
--port PORT The port, default 8765

Live demo with Claude

Claude answers in md2ui Markdown, the answer opens in md2ui's window, and your clicks come back to Claude. The demo is local only.

Install it with a plugin. github.com/md2ui/plugins holds the host packages: the Claude Code plugins, the Claude Desktop extension, and a local plugin for ChatGPT Desktop and Codex. Its README has the steps.

Or register it by hand. Claude Code:

claude mcp add md2ui-demo -- uvx --from md2ui==0.1.0a1 md2ui-mcp-demo --fetch --theme /path/to/THEME.md

Claude Desktop, in claude_desktop_config.json (give the full path of uvx if Claude Desktop does not find it):

{
  "mcpServers": {
    "md2ui-demo": {
      "command": "uvx",
      "args": ["--from", "md2ui==0.1.0a1", "md2ui-mcp-demo", "--fetch"]
    }
  }
}
Option Does
--theme PATH The THEME.md the window and previews use
--fetch Load pictures, theme fonts and backgrounds, as a local install should
--working-animation PATH The animated WebP or GIF the window plays while Claude works
--no-window Open no window: connect a client of your own
--port PORT Serve the conversation at ws://127.0.0.1:PORT/ws from launch; by default, a free port once the first answer is shown. A taken port stops the launch

The demo adds these tools to the authoring ones:

Tool Does
show Puts an answer in the window and returns what it offers and its authoring issues; given an earlier message_id, puts that page back. ask names the question Claude is waiting on, shown as the prompt bar's placeholder
wait_for_event Returns everything the user did since the last call: clicks as sentences, or what they typed into the window
mark Ticks, unticks or disables a target, or sets a slider, in place; takes ask as show does
showing What the window holds, as data: the live Markdown, its offers, and what the user asked for that is not answered yet
screenshot A PNG of the window as the user sees it, or of the whole answer
status The state the window was last told, and whether a window is connected
patch Adds, removes or replaces sections of a page already shown, and checks that nothing outside the edit moved
history The pages shown in this session, newest first
feed Lets a process Claude runs move the bars and marked values ([3:53 PM](feed:arrives)) of a shown page, without a turn of Claude's

How a session runs. Claude hears the window only while a wait is open, and nothing can wake it once its turn ends. So show and mark listen after replying, and Claude keeps waiting until you close the window or tell it in the chat to stop. What you do in the window while nobody listens waits in a queue, and the window says so: say "check md2ui" in the chat and Claude picks it all up. The window's prompt bar sends what you type to Claude (Enter or Send); its placeholder says whether Claude is listening, working or not listening. In Claude Desktop, allow show, wait_for_event and mark always, or every step asks. To step away, minimise (⌘M) or hide (⌘H) the window; closing it (⌘Q or its close button) ends the session.

Your own client. With --no-window --port 8765, the demo serves the conversation at ws://127.0.0.1:8765/ws and opens no window; status returns the address as url. The demo authenticates every client with a bearer secret: the one in MD2UI_WIRE_BEARER in its environment (at least 32 characters; a shorter one is ignored), else one it mints per run and gives only to the window it opens. A client sends Authorization: Bearer <that value> on the WebSocket upgrade; one without it is refused with a 403. md2ui-app --connect sends the same variable. A browser page cannot set that header, so it cannot connect to the demo. screenshot needs md2ui's own window.

After upgrading md2ui (a new pin in uvx --from, or uv tool upgrade md2ui), the demo server and its window keep running the code they started with:

  • Claude Code: /reload-plugins does not restart the server. Use /mcp, choose md2ui-demo and reconnect, or restart Claude Code.
  • Claude Desktop: restart it, or turn the extension off and on under Settings → Extensions.
  • Either: close the open md2ui window, so the next show opens one with the new code.

License

md2ui's own code is under the MIT License (LICENSE).

The package also ships one file that is not md2ui's: the icon font assets/icons/material-design-icons-md2ui.ttf, built from Google's Material Symbols, which is under the Apache License 2.0 (assets/icons/LICENSE); assets/icons/NOTICE says how it was modified. Both licenses apply to what you install, so the package declares MIT AND Apache-2.0.

The fonts md2ui downloads on first use (those in assets/fonts.lock) are not part of the package. Each keeps its own license, recorded beside it in the lock: OFL-1.1, or CC BY-SA 4.0 for OpenMoji.

Metadata

Release files for md2ui 0.1.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for md2ui 0.1.0a1
File Size Uploaded Provenance Actions
md2ui-0.1.0a1.tar.gz 1.9 MB With provenance Details for md2ui-0.1.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for md2ui 0.1.0a1
File Interpreter ABI Platform Actions
md2ui-0.1.0a1-py3-none-any.whl Python 3 none any Details for md2ui-0.1.0a1-py3-none-any.whl

Total release size: 3.9 MB

Release files / md2ui-0.1.0a1.tar.gz

Download URL md2ui-0.1.0a1.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
a018aab1da06f1e895d81ed4a723255b0ea1efa6ac935b2179cd45d5d6020f5e
BLAKE2b-256 checksum
How to use checksums
e25d9f81dd2df07f4f75bbb3ed9049a169d41143fc9dfe3b0cf4b3011fba3594
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / md2ui-0.1.0a1-py3-none-any.whl

Download URL md2ui-0.1.0a1-py3-none-any.whl
Size 2.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
cc6252a71f5b9c3c36f0d2787f5abcae64110136d5c3e3517dc1448f8b09861f
BLAKE2b-256 checksum
How to use checksums
6e54794e159762b638cd3d200b74f127975a1a0f3e3f494a7f5456fbfe2ea275
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for md2ui 0.1.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for md2ui-0.1.0a1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page