Runic

Docs

Write text, get flows Commands Patterns & recipes Sequence diagrams Editor tips The AI agent Build package Power features Share & export styles Connect Claude (MCP)

Write text, get flows

Every line in the editor is a step. Indent with two spaces (or Tab) to nest steps under a branch. Start a line with . to use a command — a menu appears as you type. The flowchart on the right redraws instantly and stays in sync with the text, always.

Example

User lands on the login page
.if Does the user have an account?
  .then Yes
    User enters username and password
    User presses the login button
  .then No
    .go Registered
.end
.end

Commands

Anything that does not start with a dot is a plain step — one card, connected to the previous one. The commands below add structure. Type . at the start of a line for the autocomplete menu.

.if

Branch on a condition. Press Enter at the end of the line and two .then branches scaffold themselves. Every decision needs AT LEAST two branches — one outcome is not a decision. A menu with many options is ONE .if with one .then per option, never a chain of one-branch .ifs.

.if Does the user have an account?
  .then Yes
    User signs in
  .then No
    User registers

WRONG

.if download chosen
  .then yes
    System downloads it
.if delete chosen
  .then yes
    System deletes it

RIGHT

.if What does the user choose?
  .then Download
    System downloads it
  .then Delete
    System asks to confirm
  .then Cancel
    Nothing changes
.end

An .if line cannot carry an arrow caption — branch arrows are labeled by their .then labels.

.then

One branch of the decision above it, indented two spaces from the .if; the branch’s own steps go two more. The label becomes the chip on the branch arrow: Yes renders green, No renders red, anything else violet — so menu options, error classes and approval levels all read naturally.

.if How urgent is it?
  .then Urgent
    Escalate to on-call
  .then Normal
    Queue for tomorrow

.end

Closes the nearest open .if, at the SAME indent as that .if — the branches merge and the flow continues below. At the top level of the document, .end draws the End pill instead.

.if Is it valid?
  .then Yes
    Process it
  .then No
    Fix it first
.end
Archive the request
.note Runs after EITHER branch — .end merged them
.end

Never use .end as a separator — only decisions close and flows end.

.go

Jump to another process and STOP this path — like a goto between flows. The target process gets a reference badge, and renaming it updates every .go pointing at it. Nothing may follow a .go on the same path.

.go Registered

WRONG

.go Check file size
System scans the file

RIGHT

.do Check file size
System scans the file

.do

Call another process and RETURN — the flow continues on the next line. Use it for sub-processes: verification, payment, anything reusable.

Customer submits the order
.do Verify identity
Order is confirmed

.input

A step where data enters the flow — a form, an upload, an answer. Renders with its own INPUT look so data boundaries stand out.

.input Email address and password

.wait

Pause for a time or an external event — a webhook, a human approval, a nightly job. Leave the text empty while you think; the card stays blank until you fill it.

.wait for the bank webhook: confirmed

.fail

Record a FAILURE OUTCOME — a red card. It does not end the path: the lines after it are the recovery (logging, notifications, cleanup) and connect with arrows as usual. A trailing .fail with nothing after it simply ends the branch.

.fail Payment declined
Customer is notified
Retry link is sent: 24h valid

.back

A dashed transition arrow to ANY other step, matched by a few words of its text — an earlier step (a loop or retry) or a later one (skip ahead, say from a mid-flow status straight to a terminal "Cancelled"). No card is drawn — the arrow leaves the box right above the .back line, and the flow continues below it, so several .backs stack multiple arrows off one box. While the target text does not match anything yet, a small hint pill shows in its place.

created
shipping
delivered
close
.back created: cancel order
.back delivered: keep record
archive the order

: caption

Arrow captions, UML-style. End any step line (plain steps, .input, .wait, .fail, .do — and .back for its return arrow) with a colon + caption to label its OUTGOING arrow. The colon needs a space on at least one side; tight colons like https://runic.app or 14:30 never split.

Customer pays: payment confirmed
Order ships

One caption per arrow, by construction: one line, one box, one colon.

.note

A sticky note pinned beside the previous step — context, ownership, edge cases. Several notes on one step stack; in the flow they collapse into a badge you click to read.

Manager approves the request
.note Only above €500
.note SLA: one business day

Patterns & recipes

Copy-paste starting points for the shapes that come up in every real process.

State machine with return arrows

Statuses as steps, transitions as captions, corrections as .back arrows — reads exactly like a UML state diagram.

created: request shipment
shipping: confirm arrival
delivered
close
.back created: cancel order
.back delivered: lost in transit
archive the order

Terminal state fed from mid-flow

A status like "Cancelled" is not part of the happy path — park it at the end and jump AHEAD to it with .back from wherever the exit can happen. The happy chain stays clean; the exits read as labeled transitions.

Order approved
Invoice can be issued
.back Cancelled: cancelled before invoicing
Invoice issued
Paid
Cancelled

Failure with recovery

The failure is an outcome, not the end — the notification and retry still happen.

Charge the card
.if Did the charge succeed?
  .then Yes
    Receipt is emailed
  .then No
    .fail Payment declined
    Customer is notified
    .wait 24h for a retry: retried
    .back Charge the card
.end

A menu, done right

One decision, one branch per option — never a chain of separate .ifs.

.if What does the user pick?
  .then Export
    .do Export the report
  .then Share
    A read-only link is created
  .then Delete
    System asks to confirm
.end

Split across processes

.do calls a reusable sub-process and returns; .go hands off for good. Renames follow references automatically.

Customer submits the application
.do Verify identity
.if Approved?
  .then Yes
    .go Account opening
  .then No
    Rejection letter is sent
.end

Sequence diagrams

A second document type for who-talks-to-whom. Every line is one interaction between two actors — actors are created automatically the first time they appear, and each message becomes the next arrow down the page.

Example

Customer -> App: Submits credentials
> Clicks the login button        (same direction again)
< Shows a spinner                (the reply, dashed)
App -> API: Requests a session
.alt credentials valid
  API --> App: Returns a token
.else credentials invalid
  API --> App: Returns an error
.end
.note Lockout after 4 failed attempts

A -> B: text

A solid request arrow from actor A to actor B. Both actors appear automatically.

A --> B: text

A dashed response arrow — use it for replies and returned data.

A -> A: text

A self message: the actor does something internally (validate, compute, retry).

> text

Shorthand: the same two actors again, same direction — no names needed.

< text

Shorthand: the reply — flips the direction of the previous message, drawn dashed.

.actor Name

Declare an actor up front to pin its column order.

.alt / .else / .end

Alternative paths. Indent the messages inside each branch by two spaces.

.loop label

A repeated block — indent its messages, close with .end or just dedent.

.note text

A sticky note pinned beside the flow.

Plain prose isn't drawable in a sequence diagram — if a line can't be understood, the panel under the diagram explains exactly what to change.

Editor tips

Enter after .if

scaffolds two .then branches with the caret in the first one

Tab / Shift-Tab

indent / outdent the current line (two spaces per level)

⋮⋮ drag handle

hover a line, drag the handle — a block moves with its branches and .end

Drag on the canvas

rubber-band select nodes; the matching lines select in the text

Hover either pane

the other pane highlights AND scrolls the twin into view

Click a step icon

pick an icon by hand, or leave it — Runic auto-detects from the text

Chevron on an .if line

fold the whole decision; folded blocks travel as one unit

Select several lines

the floating bar extracts them into a new process, sends them to AI edit, or attaches them to chat

Drag the pane dividers

resize editor / flow / chat; the editor collapses to a rail entirely

⤢ on the flow

fullscreen the diagram — Esc returns

Toolbar toggles

compact cards, branch alignment, tight packing, top-down ↔ left-right — hover any button for its tooltip

History (clock icon)

automatic snapshots every ~10 minutes; NAME the ones worth keeping — named versions never roll off

The AI agent

The chat panel on the right of the editor is an agent scoped to the open process. It proposes, you decide; everything it applies stays reversible.

CHAT

Ask for a change in plain words

Type what should happen in the chat panel (open by default on the right). Change requests come back as a green/red diff. Click Apply to accept, Discard to drop it — nothing touches your document until you decide.

CHECKPOINTS

Undo any applied change, any time

Every applied change keeps a ↩ Restore button on its chat entry. Click it — even much later, even after more edits — and the document returns to how it was before that change.

PREVIEW

Judge suggestions as a diagram

While a proposal is pending, the visual flow renders the suggested document with new steps glowing green. Apply or Discard right from the banner on the diagram.

SELECTION

Scope the agent to exact lines

Select lines in the editor and press “Copy to chat” on the floating bar. The chip pins your selection; the agent may rewrite only those lines — the rest of the document is off-limits by construction.

AUDIT

Run the two-stage audit

Click “⚙ Audit + AI review” under the chat. Instant checks flag structural gaps (decisions without a No branch, unreachable steps) with clickable line numbers; an AI analyst then reads for domain gaps like missing failure paths or undefined roles.

MEMORY

Refer back — it remembers

Say “do what you suggested” and the agent knows. Long conversations fold into summaries it can recall, and the whole chat follows your account to any browser.

From flows to a build — the AI handoff

Shape the idea in Runic, then export a Build Package your AI tools execute. The pipeline below is the whole story; the three steps follow.

INTERVIEW

1 · Answer the analyst

Press Build in the top bar and pick which flows to include. Runic interviews you for what flows can’t express — roles, data, failure handling. Unanswered questions land in the spec as open questions; nothing is invented.

PACKAGE

2 · Download the zip

You get CLAUDE.md (project memory), docs/spec.md (the full build spec with acceptance criteria), a milestone plan, a design brief and your flows as source files. Unzip it into an empty repo.

HANDOFF

3 · Paste the kickoff

Open the folder in Claude Code and paste KICKOFF.md. It reads YOUR spec, plans Milestone 1 and waits for approval. For screens, copy the design brief into your design tool.

Editor essentials

The moves you’ll use every day. Keyboard: ⌘Z undo · ⇧⌘Z redo · Tab accept a gray suggestion · ⌘Click a .go/.do jumps to its process · Esc closes whatever is open.

IMPORT

Import a whiteboard photo or Mermaid

Drag a screenshot onto the chat, paste one from the clipboard, or use 📎 Import flow (Mermaid files welcome). The agent translates it into Runic — as a new process, or merged into the open one. Steer it: “import as new” / “merge into this”.

SELECT

Select in either pane

Select lines in the text, or drag a box over diagram nodes — it is the same selection. The floating bar offers Convert to process, AI edit and Copy to chat wherever the selection came from.

STRUCTURE

Fold, reorder, extract

Chevrons fold .if blocks; drag the ⠿ handle to move steps with their children; Convert to process lifts a selection into its own linked process. Whole decisions travel together so documents never break.

HISTORY

Versions, undo, redo

Undo/redo cover your last 15 moves. The clock icon opens version history; “Save version” stamps a named snapshot you can always restore. In the sidebar, drag rows to reorder and drop one onto another to nest it.

Sharing & export styles

Everything lives under the Share button on the diagram. A share link is read-only and always shows the current document — the embed iframe too, so the diagram in your wiki can never rot. Revoke kills the link instantly.

Images export as PNG (2× resolution), SVG (scales forever) or straight to the clipboard — in a style of your choice. The editor never changes; the style dresses the export:

Runic

exactly what you see in the editor

Boardroom

ink on white — made for print and PDFs

Blueprint

deep navy, cyan lines, monospace type

Midnight

dark mode — hues survive, lifted to glow

Pastel

soft, rounded, gallery-wall calm

Sunset

warm coral and amber on cream

Custom

pick page, card, ink and accent colors — the whole diagram follows

The plain-text source exports too — your processes are never locked in.

Connect Claude (MCP)

Runic ships an MCP server, so Claude Code, Claude Desktop or any MCP client can list, read, search, edit, create and share your flows — and even browse version history. Claude learns the Runic language automatically.

1 · Create a token

In the editor, open the avatar menu → Claude & MCP → Create a token. The token is shown once — copy it right away. You can hold up to five tokens and revoke any of them at any time.

2 · Connect your client

Claude Code — one command:

claude mcp add --transport http runic https://runicflow.ai/api/mcp \
  --header "Authorization: Bearer <your token>"

Claude Desktop / other clients — add a custom MCP server with:

Transport: HTTP (streamable) · Endpoint: https://runicflow.ai/api/mcp
Header: Authorization: Bearer <your token>

3 · What Claude can do

list_documents

every flow and sequence, with ids and sizes

read_document

full text of one document + a reading legend

search_documents

full-text search across everything, with line numbers

write_document

replace a document — parse errors and audit findings come back in the response

create_document

start a new process or sequence

rename_document

rename a document

audit_document

quality review without writing anything

share_document

create the public read-only link (and embed URL)

list_versions / restore_version

browse snapshots and roll back — restores are themselves undoable

get_syntax_guide

the Runic language reference

Things to try

“List my Runic flows and summarize what each covers.”
“Read the Onboarding flow and write a gap analysis — what edge cases are missing?”
“Create a customer-refund process in Runic: eligibility check, warehouse inspection, appeal loop.”
“Search my flows for every step that mentions ‘invoice’ and list where they live.”
“Audit every process and fix the findings, then give me share links.”

Security: tokens are hashed at rest, shown only once, revocable from the same menu, and deleted with your account. Calls are rate-limited. A token grants read/write access to your documents — treat it like a password.