One line, one message
Write 'Customer -> App: Submits credentials' and both actors appear as navy headers with dashed lifelines, joined by a solid arrow carrying the text. '-->' draws a dashed reply; '->>' an asynchronous send with an open head. A '+' right after the arrow activates the receiver, a '-' deactivates the sender, so 'Client ->+ Auth' opens a bar on Auth and 'Auth -->- Client' closes it. The text after the colon is optional: 'App -> DB' on its own draws an arrow with an italic 'Message…' placeholder. 'App -> App: Validates input' is a self message, a small loop off the actor's own lifeline. Lines starting with # or // are comments.
Actors are created the first time they are named, left to right in order of appearance. Put '.actor Payment API' near the top to fix a column's position before any message uses it. '.actor Payment API as Pay (service)' gives it an alias to write in messages and a type glyph: user, system, service, database, queue or external. Everyday words map onto those types — person, human, customer or actor → user; db, store or cache → database; api, svc or worker → service; app or server → system; broker, topic or bus → queue; third, vendor or ext → external. Any other word in the parentheses is an error that lists the six types. The header tooltip reads 'Label · written as “alias”' when they differ. Columns spread apart on their own to fit the longest label between them.
Shorthands for the same two actors
Once a message exists, a line that starts with '>' repeats the previous sender, receiver and arrow style — no names needed. A line that starts with '<' flips the direction and draws it dashed, which is what a reply usually is. Either character before any message exists is an error: '“>” continues the previous message — but there is none yet. Start with “From -> To: …”.' Both shorthands work inside fragments. '.activate A' and '.deactivate A' draw activation bars explicitly, for an actor that already appears; '.autonumber' anywhere numbers every message.
Fragments
.loop label opens a repeated block. .alt label opens the first of several alternative paths, and .else label starts the next path of the same .alt. .opt, .break and .group are single-section boxes; .par opens parallel blocks separated by .and; .critical is an uninterruptible block and accepts .else sections too. Indent the messages inside by two spaces. A block closes when you dedent, or explicitly with .end, which closes the innermost open block from any indent; an .end with nothing open says '.end has no open fragment to close.'
In the diagram each block is a rounded box around its rows with LOOP, ALT, OPT, PAR, BREAK, CRITICAL or GROUP and the label in the corner, and a dashed 'ELSE · label' or 'AND · label' divider between sections. A misplaced section line explains itself: '.else only works inside an .alt — a .loop has a single body.', 'Inside a .par the next block starts with .and, not .else.', '.and only works inside a .par — use .else for an .alt.', or '.else needs an open .alt at the same indent as its opening line.'
.note text pins a comment icon in a side column to the right of the last lifeline. '.note over A: text' anchors it over an actor, '.note A, B: text' spans two, '.note left of A: text' and '.note right of A: text' sit beside one; the actor must exist by alias or label, or the line reads '“X” isn’t an actor in this diagram yet — declare it with .actor or mention it in a message first.' A plain '.note some text: more' stays a side note.
References to other documents
.do Name draws a REF box — that document runs here, then this diagram continues; .go Name is a hand-off. '.do Refund process: on failure' captions the box; the caption is split at ': ' and is not part of the name. The name may be a process or another diagram, and the reference index counts it, so the diagram nests in the sidebar under its only caller and rename propagation rewrites it. A box whose name no document answers to is tinted amber, labelled '+ Create', with the tooltip 'No document is named “X” — click to create it'; the click creates a process. After '.do ' or '.go ' the menu lists your other documents, labelled 'Process' or 'Sequence diagram', until you type a caption. An empty .do or .go says '.do needs the name of a document, e.g. “.do Refund process”.'
Errors that explain themselves
Plain prose is not drawable here. A line the parser cannot read gets a pink background in the editor and the header chip reads 'Check line N'. A panel under the diagram lists up to four problems with their line numbers and what to write instead — 'Not an interaction — write “From -> To: what happens” (or --> for a response, ->> for async, or start with > / < to continue).', '.actor needs a name, e.g. “.actor Payment API”.', '“.x” isn’t a command — try .actor, .loop, .alt, .else, .opt, .par, .note, .do, .go or .end.' — and counts the rest as '+ N more'. Hover a line in the editor and the matching message, box or note turns violet in the diagram, which scrolls to keep it in view; hover a message in the diagram and the editor highlights that line and scrolls to it.
What is different from a process
Sequence documents use their own parser. The process commands (.if, .then, .back) mean nothing here, and an arrow line in a process is just a step. The '⚙ Audit + AI review' button exists for processes only; sequence diagrams have their own structural checks — a request without a reply, an activation never closed, a single-section .alt or .par, an empty fragment, a lonely actor, a silent receiver, a reference to an unknown document, a diagram where nothing ever fails, and actors that were never pinned with .actor — which run on every document the AI writes and behind the MCP audit_document tool, not behind a button. Share links, embeds, image export and version history work the same; the text export is a .sequence.runic file and the Markdown export carries the sequence legend. Undo and redo answer to ⌘Z, ⇧⌘Z and ⌘Y as well as the header buttons. The AI chat panel and the sidebar's ✨ Create with AI (set to Sequence diagram) both write this syntax.
How to use it
- Create a diagramClick + at the top of the sidebar and choose 'Sequence diagram' (processes and diagrams share one list; each row carries a small kind glyph). The document is named 'Diagram N' and opens with a seven-line starter you can overwrite. Clear it and the empty pane reads 'Nothing to draw yet' and offers 'Insert an example' instead.
- Write the first messageType 'Customer -> App: Signs in'. Two headers, two lifelines and one arrow appear in the pane on the right.
- Reply with the shorthandOn the next line type '< Shows the dashboard'. The arrow runs from App back to Customer and draws dashed.
- Reuse actor names from the menuStart a line with the first letters of an existing actor and pick it: Runic appends ' -> '. After the arrow, pick the receiver and it appends ': '. Up to eight matches are listed.
- Branch with .altType a dot and choose .alt from the menu: Runic inserts '.alt ', an indented blank line, '.else ' and another indented line. Fill in the labels and the messages. Enter after a .loop, .alt, .else, .opt, .par, .and, .break, .critical or .group line indents the next line for you.
- Reference a processType '.do ' and pick a document from the list. A REF box appears in the diagram; click it to open the document, or, if the name is new, to create it as a process.
- Fix what the panel flagsIf a line cannot be drawn, read the message under the diagram and rewrite the line as 'From -> To: text', a '>' or '<' shorthand, or one of the seventeen commands.
- Zoom, fullscreen, shareUse − and + in the header to zoom between 50% and 150%, the Fullscreen button to hide everything but the diagram (Esc returns), and Share for the link, embed code, PNG, SVG, clipboard, Markdown or the text file.
Commands & shortcuts
| A -> B: text | synchronous call (filled arrowhead); both actors are created on first use |
| A --> B: text | dashed reply |
| A ->> B: text | asynchronous send — open arrowhead, nothing waits for a reply |
| A ->+ B / B -->- A | activation: "+" marks the receiver busy, "-" on the reply ends the sender's bar |
| A -> A: text | self message — a loop on A's own lifeline |
| > text · < text | same pair and direction again · the dashed reply back |
| .actor Label as Alias (type) | pin column order; write the alias in messages; type user, system, service, database, queue or external — or an everyday word such as customer, db, api, app, broker or vendor |
| .loop · .opt · .break · .group | repeated, optional, leave-when, or labelled blocks; indent the messages two spaces |
| .alt / .else | alternative paths; .else at the .alt's indent (.critical takes .else too) |
| .par / .and | parallel blocks; .and starts the next one |
| .critical | an uninterruptible block, with optional .else sections |
| .end | close the innermost open fragment; dedenting also closes it |
| .note over A: text | a sticky over an actor; "A, B" spans two; "left of" / "right of" sits beside one; a bare .note goes in the side column |
| .do Doc: caption · .go Doc | reference another document (process or sequence) here, or hand off to it — click the box to open it, or to create a process when it is missing |
| .activate A · .deactivate A | explicit activation bars on an actor that already appears |
| .autonumber · # comment | number every message · lines starting with # or // are ignored |
| Paste a Mermaid sequenceDiagram | converted to Runic on the way in, no AI — participants, every arrow kind, +/- activation, notes, loop/alt/opt/par/break/critical, autonumber |
| . at line start | menu of the seventeen sequence commands — ↑ ↓ move, Enter or Tab inserts, Esc closes |
| Tab / Shift+Tab · ⌘Z / ⇧⌘Z | indent or outdent by two spaces · undo and redo |
Tips
- Declare actors with .actor in the order you want the columns before writing any message — otherwise first mention wins.
- Write the request path with -> and > first, then add < replies; long labels push the columns apart on their own.
- Put the condition in the .alt and .else labels ('credentials valid', 'credentials invalid') — they print in the box corners.
- Type the alias, not the label, in messages: after '.actor Auth Service as Auth (service)' the messages say 'Auth', the header says 'Auth Service'.
- Several notes in a row become one icon with a count; click anywhere else to close an open note.
- Keep each message on one line — a long label wraps and just makes its row taller.
Questions
Do I have to close every block with .end?
No. Dedenting back to the block's indent closes it. .end is for when you want the close to be visible; it closes the innermost open block from any indentation.
Can I change the order of the actors later?
Yes. Add .actor lines at the top in the order you want. A declared actor takes its column before any message mentions it.
Why is my line marked 'Not an interaction'?
Every line must be a message ('From -> To: text'), a shorthand ('> text' or '< text'), a comment, or one of the seventeen commands. Prose on its own has nothing to draw. The panel under the diagram shows the exact form to use.
What happens when I click a REF box for a document that does not exist?
Runic creates an empty process with that name and opens it — always a process, even from a diagram. Create a diagram with the name from the + menu first if the reference should point at one.
Is there a limit on sequence diagrams?
Once paid plans are switched on, the free plan includes 10 sequence diagrams per account; while billing is not configured there is no cap at all. The language is the same on every plan.