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

1. Install the extension and open a folder.

2. 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
     }
   }
   

3. 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.

4. 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.

5. 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 has rounded, lifted boxes with a tinted band behind the name, keywords as badges, softer lines and tinted swimlanes. colour (the default) adds a colour per category of element (interfaces, components, data, signals, actors, nodes, artifacts) or per stereotype, with a colour key in free space on 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.
• 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.
• 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.

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 umlt command-line tool

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.

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.

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

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.