| name | diagram |
| description | Build a Tidal Diagrams diagram from a natural-language prompt and hand it to the running app as a clickable deep-link. Use when the user types /diagram <description> or asks to create/build/draw a diagram in the tidal-diagrams app. |
/diagram — prompt → diagram in the Tidal Diagrams app
Turn the user's description into a quick-text diagram, encode it into a deep-link,
and print the link. When the user opens it, the running app loads the diagram
(decoded by src/diagram/urlLoad.ts, laid out fresh via the same path as Mermaid import).
Steps
- Author quick-text from the user's prompt using the syntax below. Aim for a
clear, well-grouped diagram — pick a sensible
direction, give nodes real labels,
use shapes (#db, #pill) and groups where they add meaning.
- Build the link by piping the quick-text into the encoder script. Give it a short title:
ENC="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/}scripts/diagram-link.mjs"
printf '%s' "$QUICKTEXT" | node "$ENC" --title "Checkout flow"
- Target host is resolved automatically: installed as a plugin it points at the
hosted app (
https://tidal-diagrams.vercel.app) — so the user just opens the
link, nothing to run locally. Working in this repo it points at http://localhost:5173
(pass --port <n> / $TIDAL_PORT if the dev server moved; start it with npm run dev
if it isn't up). Override either with --host <url> or $TIDAL_HOST.
- Direction: prefer a
direction LR line in the quick-text. The
--direction LR|TB|RL|BT flag is a convenience override for the whole diagram.
- Aspect / dimensions: pass
--aspect 4:3 (also 16:9, 1.5) to bias the
layout so the content bounding box approximates that ratio. This is best-effort
— dagre never wraps ranks, so a long linear chain keeps its shape; branching
diagrams respond well. If the user wants a specific ratio, prefer a direction
that suits it (wide ratios → LR, tall → TB) and add branching where natural.
- Show the result: print the quick-text in a code block (so the user can read/tweak it)
followed by the link on its own line, e.g.
Open: <url>. The link is long — that's expected.
If the app is already open in the browser, opening the link in that same tab swaps in
the new diagram live (the app also listens for hashchange).
Quick-text syntax (cheat-sheet)
direction LR # flow direction: LR | TB | RL | BT (also right/down/left/up)
Node Label # a card (default shape)
Service / detail line # two-line card: title / mono subtitle
Database #db # cylinder shape
Gateway #pill # pill shape
Cache #outline # surface: #solid | #outline | #ghost
Queue @q # explicit id with @id (so edges can reference it)
Group Name: # group header; indent the lines under it to nest
Worker A
Worker B
A -> B # arrow A --> B is the same
A ..> B # dotted arrow
A <-> B # bidirectional A <..> B bidirectional dotted
A -- B # plain line, no arrow
A -> |label| B # labelled edge (also A ..> |retries| B)
A, B -> C, D # fan-out: every left node connects to every right node
// a comment line
Notes:
- Reference a node in an edge by its label text (its id is the slugged title) or by an explicit
@id.
- Quote a label to keep punctuation literal:
"Auth (OAuth2)".
- Keep it to flowchart-style nodes/edges/groups. Sequence diagrams use a different
syntax and are imported separately, not via this command.
Example
Prompt: "a checkout flow with payment retries"
Quick-text:
direction LR
Cart #pill
Checkout
Payment / Stripe #db
Order Service
Cart -> Checkout
Checkout -> |charge| Payment
Payment ..> |retry| Checkout
Checkout -> |on success| Order Service
Then run the encoder with --title "Checkout flow" and share the printed URL.
Label placement matters: the label goes right after the operator —
A -> |label| B, not A -> B |label|. The latter folds the label into B's name.
