UMLT: UML as text
UMLT keeps UML 2.5.1 models as small, readable text files (.umlt) in your repository, and draws them as
diagrams you can edit. The text is the source of truth: a diagram you change writes back minimal text changes, so
the files review well in Git. People and AI coding agents work on the same files.
Preview. UMLT is an early release. The notation and the tools can still change, and the
known limitations below say what is not there yet.
- Diagrams you can edit. Every
.umlt file with diagrams opens as a diagram, next to its text. Draw, connect,
rename and move on the canvas, or type in the text; both edit the same file and share one undo history.
- All 14 UML diagram kinds, drawn from the text, with the notation of UML 2.5.1.
- Made for coding agents. An MCP server, a command-line tool, rules for
AGENTS.md and prompts let an agent
read, check, draw and extend a model, and tell you what changed since the last iteration.
There is no built-in AI and no code generator. Code and model meet through your own coding agent, which reads and
writes the files. Synchronization happens between the text and the diagrams only.
Quick start
Install the extension and open a folder.
Create shop.umlt in it with this model:
package shop {
/// What a customer buys in one checkout.
«entity» class Order {
+ id: OrderId {readOnly}
+ place()
+ total(): Money {query}
}
class OrderLine {
+ quantity: Integer
+ price: Money
}
class Customer {
+ name: String
}
interface Payments {
+ charge(order: Order): Boolean
}
primitive OrderId
primitive Money
composition Order[1] -- OrderLine[1..*] lines
association Customer[1] -> Order[*] orders
usage Order -> Payments
interaction Checkout "Check out" {
lifeline customer: Customer
lifeline order: Order
lifeline payments: Payments
call customer -> order: place()
call order -> payments: charge(order)
reply payments -> order: charge(): Boolean
}
diagram class Overview {
Customer
Order
OrderLine
Payments
}
}
Open the file. It opens as a diagram, and the list at the top picks among the file's diagrams: the class diagram
Overview and the sequence diagram of the interaction Checkout. Cmd+K V (Ctrl+K V on Windows and Linux) opens the text beside
it, and UMLT: Show Text switches to the text.
Drag a box. Only that element's line in the text changes (Order at 40, 40). The diagram block lists what a
view shows without positions, so UMLT lays the rest out.
Mistakes show in the editor and in the Problems panel as you type.
The 14 diagram kinds
Class, object, package, component, composite structure, deployment, profile, use case, state machine, activity,
sequence, communication, interaction overview and timing diagrams. Class, object, package, component, deployment,
profile and use case diagrams list their elements in a diagram block. Sequence, timing, state machine, activity,
communication and interaction overview diagrams, and the internal structure of a classifier, are drawn from the model
and laid out automatically. Timing diagrams are edited in the text, and a communication diagram is derived from its
interaction; the other kinds are edited on the canvas too.
The diagram editor
- Tools. The toolbar has the elements of the diagram's kind, rarer ones under More. Click to place one and
type its name. Some work by gesture: a combined fragment of a sequence diagram (Alt, Opt, Loop, Par,
Break, Critical) is a frame dragged over the messages it wraps, and a use case clicked into a subject's box
belongs to that subject.
- Connecting. Drag from near an element's edge onto another element for the usual relationship (Change Type
picks another). Drag into empty space to make a new, connected element. Alt-drag connects from anywhere inside an
element, and Connect… in an element's menu starts a line that a click ends.
- Shaping lines. Select a line and drag its handles to bend it, move its name along it, or slide an end around
the outline of its element. The shape is stored as a
line statement. Line Style switches between curved,
elbow and straight lines, and Reset Line hands one back to the layout. Auto Layout and Auto Layout Selected
give positions and line shapes back to the layout. State machines, activities and the other behaviors lay
themselves out; a node you drag stays where you put it.
- Diagram styles.
classic is the plain UML look. modern is flat, a documentation look: thin ink lines on a white
panel, muted frames and details, set in IBM Plex Sans with IBM Plex Mono for the keywords of lines. colour (the default)
has rounded, lifted boxes with a tinted band behind the name, keywords as badges and tinted swimlanes, and a colour per category
of element (interfaces, components, data, signals, actors, nodes, artifacts) or per stereotype, with the colours
listed in the key below the diagram. The notation and the layout are the same in every style, and light and dark follow
the editor's theme. Switch with Style in the diagram's toolbar, in its right-click menu, with
UMLT: Choose Diagram Style… or with the setting umlt.diagram.style.
- Frame and caption. A diagram is drawn in a UML frame whose name tag is Annex A's heading: the kind and name of the
package or element the diagram shows (
pkg shop, stm Lifecycle). That heading is the same for a class diagram and a
use case diagram of one package, so a caption below the frame names the kind of the diagram and the view's own title
(Use case diagram · Library desk). The caption is outside the frame and is UMLT's own, not UML notation; the setting
umlt.diagram.kindInCaption leaves the kind out of it.
- Notation key. Below the caption a key explains the notation the diagram uses, and only that: each entry is a small
sample drawn as the diagram draws it, then UML's name and what it means (
Generalization: is a kind of, Composition: part of, lives and dies with it, Synchronous call: waits for the reply, alt: one of the alternatives, Choice: picks one branch by guard). A box that names itself, such as «interface», is not listed. In the colour style the key also
lists the colours, and the key of change highlighting stands beside it: every key is in one place, outside the frame, so
the diagram itself stays plain UML and nothing in it moves. It is in exported SVG and PNG files too; the setting
umlt.diagram.notationKey turns it off.
- Hide, show and detail levels. A diagram is a view of the model. Hide leaves an element out and keeps its
place, Show Related brings in what is related to a box, Hide Member and Hide Members… leave members out of
their box (the list then ends with
...), and Detail Level shows a box's name only, its attributes, its public
members or everything. Show Elements…, or the N hidden chip, brings hidden elements back. Nothing leaves the
model.
- Links between diagrams. A box that has a diagram inside it (a class's state machine, a package's diagrams, an
activity an action calls, an interaction that a
ref names) shows a small ⊞ in the editor; click it to open that
diagram. Link to Diagram… links a box to any other diagram, and Appears In… lists the other diagrams that show
an element. The diagrams you open form a trail under the toolbar: Alt+← and Alt+→ go back and forward, also
into other files.
- Details card. A click only selects. Right-click an element, line or message and choose Details… (or press
Alt+Enter) for a card with its stereotypes, description, members, multiplicities and roles, and its identifier;
renaming that updates every reference.
- Changes since an iteration.
UMLT: Show Changes Since… picks a baseline (the last iteration of
umlt-iterations.txt, an earlier one, or a git ref) and every diagram then shows what changed since: translucent
yellow, strong for what is new and light for what changed, with removed things listed in a small key. Hovering a
changed row or label shows what it was. The status bar item Changes since … turns the highlighting off and on
again, and UMLT: Hide Changes ends it. It is an overlay, never written into the files.
- Export. The SVG and PNG buttons in the toolbar save a diagram as a file at one click; Export ▾ also copies it as
a PNG image to paste into Word, PowerPoint, Teams, Confluence or an e-mail, copies its SVG, or exports every diagram of
the file (see Exporting diagrams below).
- Diagnostics as you type. The whole model is checked after a short pause, or on save with the setting
umlt.validate. Problems appear in the editor and in the Problems panel. Deprecated notation is struck through,
with its fix as a quick fix.
The context menu of a diagram also has Change Type, Reverse Direction, Remove from Diagram,
Delete from Model… and Copy Prompt for Agent. Undo and redo are the editor's own, shared with the text.
Exporting diagrams
To put a diagram into a document, a wiki or a slide, click SVG or PNG in the diagram's toolbar, or use Export ▾
beside them (the right-click menu of the empty diagram has the same items).
- Export as SVG… and Export as PNG… ask where to save the file. The name they suggest is the diagram's, such as
Overview-class, in the folder of the model file the first time and in the folder of your last export after that.
Exported … then offers Reveal (in the file manager) and Open.
- Copy as PNG puts the diagram on the clipboard as an image, so that you can paste it into Word, PowerPoint, Teams,
Confluence or an e-mail without saving a file. It is the same picture Export as PNG… writes, at the same scale. The
toolbar's Export ▾ and the right-click menu of the empty diagram copy it through the page, which needs nothing
installed. Copy Diagram as PNG in the right-click menu of an element, line or selection, and the command UMLT Diagram:
Copy as PNG, copy the whole diagram (not only the selection) through the operating system instead, because they come
with no click of the page's; that uses
osascript on macOS and PowerShell on Windows, which every machine has, and
wl-copy (Wayland) or xclip (X11) on Linux, which you may have to install (the message says so). On Windows that
way puts a plain bitmap on the clipboard, which may lose the transparency of a PNG whose background is transparent (the
setting umlt.export.background). In a remote window (SSH, a container, a codespace) the extension cannot reach your
computer's clipboard that way, so use the toolbar's Export ▾ there, or Export as PNG….
- Copy SVG puts the SVG on the clipboard as text.
- Export All Diagrams in This File… asks for SVG or PNG and a folder, and writes one file per diagram.
The file shows the diagram as the editor draws it now: in your diagram style, with the key below it as the settings have it
(the notation, and the colours of the colour style), and with the change highlighting while that is on. It never shows what the editor lays over a diagram: the selection, handles, the
small ⊞ of a link, the N hidden chip. Exports are light on a solid background by default, whatever the editor's theme,
because they usually go into documents; the settings umlt.export.theme, umlt.export.background and umlt.export.pngScale
change that.
An exported SVG is portable by default, so that other systems can use it: it has no stylesheet and no CSS variables, every
colour, stroke and font is an attribute of its element, and arrowheads are paths of their own. Word, PowerPoint, Confluence,
draw.io and older Inkscape read that, and a browser draws it the same. For a web page that restyles the diagram, the setting
umlt.export.svgFormat set to web keeps the stylesheet. The same two forms come from the command line: umlt render --format svg and umlt render --format svg --portable.
A PNG, saved or copied, is made with the native module that the extension carries for the command-line tool, so a package
built for another platform may lack it. The message then names the platform, and SVG still works. A diagram too big for a
PNG at the chosen scale is made smaller, and the message says so.
For coding agents
No model knows UMLT from its training, so agents get it from three places.
- The MCP server. Run
UMLT: Set Up the MCP Server for AI Agents. It copies the command-line tool that the
extension carries to a folder that survives updates, and adds the server umlt to the workspace folder's
.vscode/mcp.json (the file holds this computer's paths, so don't commit it). Use it from the chat of an editor with
MCP support, in agent mode. It runs on a Node.js 20 or newer from your PATH, or else on the editor's own
executable, so nothing else needs installing. Its tools are umlt_guide (how to write UMLT), umlt_validate,
umlt_fix, umlt_describe, umlt_render (draws a diagram and returns the picture; with since the changes
highlighted) and umlt_diff (what changed since the last iteration). Its prompts fill_in, write_code and
update_from_code take a diagram from sketch to code. Any other MCP client can run the same server: the command and
the script path are in .vscode/mcp.json, for example claude mcp add umlt -- node <that path> mcp in Claude Code.
- The rules.
UMLT: Add Rules for AI Agents to AGENTS.md writes the UMLT rules into the folder's AGENTS.md,
and into CLAUDE.md when that file does not import AGENTS.md; run it again to update them. The rules say how to
validate before and after every edit, to keep identifiers and diagram layout lines intact, to use UML vocabulary
exactly, and how each diagram kind is written. When a folder has .umlt files and no agent rules, the extension
offers to add them. It writes nothing until you agree, and Don't ask again silences the offer.
- The guide.
umlt guide, umlt guide sequence or the tool umlt_guide give the rules and, for each diagram
kind, the syntax with a complete validated example.
In a diagram, Copy Prompt for Agent (in an element's menu) copies the prompt for the next step to paste into your
agent: Fill In the Sketch, Write the Code or Update from the Code.
The tool is one Node.js 20+ script, umlt.js. The extension carries it for the MCP server; after the MCP setup, its
path is the first argument in .vscode/mcp.json. Below, umlt stands for node <that path>/umlt.js.
| Command |
What it does |
umlt validate [--format text\|json] [--strict] [path ...] |
Checks every .umlt file under the paths as one model. Exit code 0: no errors; 1: errors (or warnings with --strict); 2: usage or I/O problem. |
umlt fix [--check] [path ...] |
Applies the safe automatic fixes of deprecated notation as minimal edits; --check only lists them. |
umlt describe [--outline] [--scope <name or path>] [path ...] |
Prints the resolved model compactly. --outline maps a big model; --scope prints one file, package or element. |
umlt render [--format png\|svg] [--portable] [--style classic\|modern\|colour] [--out <dir>] [--all \| name] |
Draws a diagram, or every one, as SVG or PNG. --portable writes an SVG for other programs: no stylesheet, no CSS variables. |
umlt wiki --out <dir> [path ...] |
Writes the model as wiki pages with SVG diagrams. |
umlt diff [--since last\|<label>\|<date>\|<git ref>\|<folder>] |
What changed in the model since a baseline, grouped by package and diagram. |
umlt iteration add, umlt iteration list |
Appends the iteration that ends now to umlt-iterations.txt, or lists the log. |
umlt guide [topic] |
How to write UMLT, per diagram kind. |
umlt mcp [folder] |
The MCP server, on stdin and stdout. |
umlt agents [--write] [folder] |
Shows, or writes, the UMLT rules into AGENTS.md and CLAUDE.md. |
Drawing PNG uses a native module that is part of the extension's package for your platform. umlt render --format svg
needs nothing else.
Commands
All are in the Command Palette (Cmd+Shift+P, Ctrl+Shift+P). The two Show Diagram commands need the text of a
.umlt file open, and Show Text, Open Text to the Side and the UMLT Diagram: commands need a diagram open.
| Command |
What it does |
UMLT: Show Diagram |
Opens the .umlt text as a diagram. |
UMLT: Show Diagram to the Side |
The same, beside the text (Cmd/Ctrl+K V). |
UMLT: Show Text |
Switches a diagram to its text. |
UMLT: Open Text to the Side |
Opens the text beside the diagram (Cmd/Ctrl+K V). |
UMLT: Choose Diagram Style… |
Picks classic, modern or colour, and turns the colour key on or off. |
UMLT: Show Changes Since… |
Highlights what changed since an iteration or a git ref. |
UMLT: Hide Changes |
Ends change highlighting. |
UMLT: Turn Change Highlighting Off or On |
Turns the highlighting off and on without losing the baseline. |
UMLT: Check the Model |
Checks the whole model and shows the number of errors and warnings. |
UMLT: Add Rules for AI Agents to AGENTS.md |
Writes or updates the UMLT rules for coding agents. |
UMLT: Set Up the MCP Server for AI Agents |
Registers the umlt MCP server in .vscode/mcp.json. |
UMLT Diagram: Zoom In |
Zooms the diagram in. |
UMLT Diagram: Zoom Out |
Zooms the diagram out. |
UMLT Diagram: Zoom to Fit |
Fits the diagram to the window. |
UMLT Diagram: Actual Size (100%) |
Shows the diagram at 100%. |
UMLT Diagram: Back |
Goes back in the trail of opened diagrams (Alt+←). |
UMLT Diagram: Forward |
Goes forward in the trail (Alt+→). |
UMLT Diagram: Show Elements… |
Brings hidden elements back into the diagram. |
UMLT Diagram: Auto Layout |
Gives the positions and line shapes of the diagram back to the layout. |
UMLT Diagram: Export as SVG… |
Saves the diagram as an SVG file. |
UMLT Diagram: Export as PNG… |
Saves the diagram as a PNG file. |
UMLT Diagram: Copy as PNG |
Puts the diagram on the clipboard as a PNG image, to paste into Word, PowerPoint, Teams, Confluence or an e-mail. |
UMLT Diagram: Copy SVG |
Puts the diagram's SVG on the clipboard as text. |
UMLT Diagram: Export All Diagrams in This File… |
Saves every diagram of the file as SVG or PNG files in a folder. |
The commands of the diagram's right-click menu (Details…, Rename, Hide, Detail Level, Link to Diagram… and
the rest) work on the element you click.
Settings
| Setting |
Values |
Default |
What it does |
umlt.diagram.style |
classic, modern, colour |
colour |
How diagrams look. A change shows at once in every open diagram. |
umlt.diagram.legend |
true, false |
true |
Lists the colours of the colour style in the key below the diagram. It has no effect in the other styles. |
umlt.diagram.kindInCaption |
true, false |
true |
Names the kind of the diagram in the caption below its frame (Use case diagram · Library desk), also in exported SVG and PNG files. With false the caption has only the diagram's own title. A change shows at once in every open diagram. |
umlt.diagram.notationKey |
true, false |
true |
Explains the notation the diagram uses in a key below its frame (Generalization: is a kind of), also in exported SVG and PNG files and Copy as PNG. A change shows at once in every open diagram. |
umlt.validate |
onType, onSave |
onType |
When to check the model: while you type, after a short pause, or when a .umlt file is saved. |
umlt.export.theme |
light, dark, editor |
light |
The palette of exported diagrams: light or dark whatever the editor shows, or the editor's own theme. |
umlt.export.background |
solid, transparent |
solid |
The background of exported diagrams. transparent leaves it out, so the picture takes the colour of the page. |
umlt.export.svgFormat |
portable, web |
portable |
The form of an exported SVG: portable for other programs (no stylesheet, no CSS variables), or web for a page that restyles it. A PNG is not affected. |
umlt.export.pngScale |
1 to 4 |
2 |
How large an exported or copied PNG is: pixels per unit of the diagram, so 2 is twice its size at 100%. |
Requirements
- VS Code 1.90 or newer on Windows, macOS or Linux (x64 or arm64). The MCP server also needs an editor with MCP support.
- Nothing else: the extension carries its own copy of the command-line tool, and runs it on your Node.js 20 or newer,
or else on the editor's own executable.
Known limitations in this preview
UMLT draws all 14 UML diagram kinds but implements a subset of UML 2.5.1. It is not a complete or conformant UML
tool, and independent audits against the specification still find gaps, listed here.
- Not supported: internal transitions and deferred triggers of state machines, association classes, n-ary
associations and connectors, qualifiers, generalization sets, OCL constraints, templates, collaborations,
submachine states, protocol state machines, conditional, loop and sequence nodes of activities, gates, found or
lost messages and comments inside sequence diagrams, and message labels and general orderings of timing diagrams.
- Interchange: there is no import or export of XMI or UML Diagram Interchange. The model is the
.umlt files.
- Checks: only the well-formedness rules UMLT lists are checked, not every constraint of the specification.
- Editing: timing diagrams are edited in the text only; a communication diagram is derived from its interaction.
- No code generation, no built-in AI. Agents work through the MCP server, the rules and the prompts.
- Layout: diagrams are laid out automatically, and the layout is still being refined. In large or busy diagrams
a label can sit next to the wrong line, lines can run close together, and wide views need zooming. Position what
matters by dragging; Auto Layout hands it back.
- Platforms: the packages cover Windows, macOS and Linux on x64 and arm64. The extension does not run in
VS Code for the Web.
- Preview: names, notation extensions and commands can still change between versions.
umlt validate reports
deprecated notation, and umlt fix brings it up to date.
License
Copyright (c) 2026 the UMLT authors. All rights reserved. UMLT is proprietary software that is free to install and
use; it may not be copied, modified or redistributed. See the LICENSE file in the package. The package includes the
third-party component listed in THIRD_PARTY_NOTICES.txt.
UML® is a registered trademark of the Object Management Group, Inc. UMLT is not affiliated with or endorsed by the
Object Management Group.
| |