In livediagram
This page is for people building a workbench : a developer tool (a coding agent's app, an editor extension) that shows a livediagram canvas live beside an agent. It covers the whole contract between your tool and livediagram. To use a workbench rather than build one, see Diagrams in Your Developer Tools .
In liveplanner
This page is for people building a workbench : a developer tool (a coding agent's app, an editor extension) that shows a liveplanner plan live beside an agent. It covers the whole contract between your tool and liveplanner. To use a workbench rather than build one, see liveplanner in Your Developer Tools .
In livedocuments and livedesign
This page is for people building a workbench : a developer tool (a coding agent's app, an editor extension) that shows a every app file live beside an agent. It covers the whole contract between your tool and every app. To use a workbench rather than build one, see Files in Your Developer Tools .
Your tool never holds a every app credential. It runs the person's own CLI , which holds their token, to get a ticket : a single-use link that opens one file in a frame, signed in as that person. The frame then talks to your tool with window.postMessage.
Your OriginEverything is bound to your tool's origin , exactly scheme://host[:port] as the browser reports it in event.origin: https on any host, or http only on localhost, 127.0.0.1 or [::1]. No path, query, trailing slash or default port. https://127.0.0.1:5175 is valid; https://127.0.0.1:5175/ and http://192.168.1.4:5175 are refused with invalid_origin.
Pairing is per origin, so the same tool on a laptop and on a LAN address pairs twice.
PairingA token opens files only in a workbench its owner has approved. The first time, run:
--name is optional, 1 to 40 characters, and is only a label shown beside the origin. The command prints the approval link on its first line of stdout before it waits (with --json, a line {"status":"pending","pairingUrl":"…","expiresAt":…}), so your tool can read it straight away and show it as one button, "Approve in every app". It opens the browser itself only when stdout is a terminal.
The link opens a page headed Allow this workbench? in the person's own signed-in browser, where only the token's owner can choose Allow or Don't allow . The command then exits:
0 once paired, printing paired <origin> as <name> (or {"status":"paired","origin":…,"name":…} with --json). An origin already paired exits 0 at once.
4 when declined (pairing_declined), when the request expired after ten minutes unanswered (pairing_expired), or when it disappeared, for example because the token was revoked (pairing_gone).
A pairing lasts as long as its token. The person can end it from Settings , under API Tokens , with Unpair .
Opening a FileThe file can be a name, an id prefix or a every app link to one of the person's own files (a share link is refused). Add --tab with a tab name or id prefix to open on that tab; without it, the editor opens on the first tab. With --json it prints:
In livediagram
{
"url": "https://www.livediagram.app/embed/workbench?d=3h9x2a…#ticket=…",
"documentId": "3h9x2a…",
"tabId": null,
"expiresAt": 1791234567890
}
In liveplanner
{
"url": "https://www.liveplanner.app/embed/workbench?d=3h9x2a…#ticket=…",
"projectId": "3h9x2a…",
"tabId": null,
"expiresAt": 1791234567890
}
In livedocuments
{
"url": "https://www.livedocuments.app/embed/workbench?d=3h9x2a…#ticket=…",
"documentId": "3h9x2a…",
"tabId": null,
"expiresAt": 1791234567890
}
In livedesign
{
"url": "https://www.livedesign.app/embed/workbench?d=3h9x2a…#ticket=…",
"designId": "3h9x2a…",
"tabId": null,
"expiresAt": 1791234567890
}
If the token is not paired with your origin, the command exits 4 with the code pairing_required and names the workbench pair command to run. Each token can mint 30 tickets a minute (pairing requests share that allowance), which is plenty for opening files but not for polling.
The FrameIn livediagram and livedocuments
Frame url exactly as printed. It has the form <app origin>/embed/workbench?d=<documentId>#ticket=<ticket>: the file id is not a secret, and the ticket travels in the fragment, which no server, log or Referer sees. The page reads the ticket and removes it from its address before doing anything else.
In liveplanner
Frame url exactly as printed. It has the form <app origin>/embed/workbench?d=<projectId>#ticket=<ticket>: the plan id is not a secret, and the ticket travels in the fragment, which no server, log or Referer sees. The page reads the ticket and removes it from its address before doing anything else.
In livedesign
Frame url exactly as printed. It has the form <app origin>/embed/workbench?d=<designId>#ticket=<ticket>: the design id is not a secret, and the ticket travels in the fragment, which no server, log or Referer sees. The page reads the ticket and removes it from its address before doing anything else.
A ticket works once , within one minute . Take the app origin from new URL(url).origin and accept messages only from that origin.
In livediagram
If the ticket has expired or was already used, the frame shows Open this diagram from your workbench and sends no messages: mint a fresh one. If the page is not framed, or framed by another origin, it says "This view opens only inside" your origin, and does nothing else.
In liveplanner, livedocuments and livedesign
If the ticket has expired or was already used, the frame shows Open this file from your workbench and sends no messages: mint a fresh one. If the page is not framed, or framed by another origin, it says "This view opens only inside" your origin, and does nothing else.
The HandshakeIn livediagram
Once the ticket is redeemed, the page posts livediagram:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with livediagram:hello-ack and your name within five seconds , or the page ends the session and mounts nothing:
const appOrigin = new URL(url).origin;
window.addEventListener('message', (event) => {
if (event.origin !== appOrigin || event.source !== frame.contentWindow) return;
const message = event.data;
if (message?.type === 'livediagram:hello') {
frame.contentWindow.postMessage(
{ type: 'livediagram:hello-ack', v: 1, name: 'Acme Editor' },
appOrigin,
);
}
});
In liveplanner
Once the ticket is redeemed, the page posts liveplanner:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with liveplanner:hello-ack and your name within five seconds , or the page ends the session and mounts nothing:
const appOrigin = new URL(url).origin;
window.addEventListener('message', (event) => {
if (event.origin !== appOrigin || event.source !== frame.contentWindow) return;
const message = event.data;
if (message?.type === 'liveplanner:hello') {
frame.contentWindow.postMessage(
{ type: 'liveplanner:hello-ack', v: 1, name: 'Acme Editor' },
appOrigin,
);
}
});
In livedocuments
Once the ticket is redeemed, the page posts livedocuments:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with livedocuments:hello-ack and your name within five seconds , or the page ends the session and mounts nothing:
const appOrigin = new URL(url).origin;
window.addEventListener('message', (event) => {
if (event.origin !== appOrigin || event.source !== frame.contentWindow) return;
const message = event.data;
if (message?.type === 'livedocuments:hello') {
frame.contentWindow.postMessage(
{ type: 'livedocuments:hello-ack', v: 1, name: 'Acme Editor' },
appOrigin,
);
}
});
In livedesign
Once the ticket is redeemed, the page posts livedesign:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with livedesign:hello-ack and your name within five seconds , or the page ends the session and mounts nothing:
const appOrigin = new URL(url).origin;
window.addEventListener('message', (event) => {
if (event.origin !== appOrigin || event.source !== frame.contentWindow) return;
const message = event.data;
if (message?.type === 'livedesign:hello') {
frame.contentWindow.postMessage(
{ type: 'livedesign:hello-ack', v: 1, name: 'Acme Editor' },
appOrigin,
);
}
});
The name (1 to 40 characters) appears in the editor's copy, such as "Reconnect in Acme Editor to keep editing."
MessagesEvery message is an object { type, v: 1, ... }. The page sends only to your origin and accepts only messages from its parent window at that origin. A message with an unknown type, a different v, or a field that fails validation is ignored (and logged once per type in the page's console), so check your payloads against this table.
In livediagram
Type Direction Payload livediagram:helloPage to tool Nothing: asks the tool to answer livediagram:hello-ackTool to page name: 1 to 40 characterslivediagram:readyPage to tool documentId, documentName, tabId, tabName, role (view, participate or edit), once the canvas is loadedlivediagram:tabPage to tool tabId, tabName: the tab now shown, after each later tab changelivediagram:selectionPage to tool documentId, documentName, tabId, rev, count (0 for nothing selected), reference: the selection referencelivediagram:renewPage to tool Nothing: asks for a fresh ticket livediagram:ticketTool to page ticket: the whole ticket from a new workbench open link (22 characters, a dot, then 64 hex characters)livediagram:revealTool to page refs: 1 to 20 element refs, each 1 to 64 characters; brings them into view on the current tab and outlines themlivediagram:themeTool to page colourScheme: light or dark; until one arrives, the editor follows the systemlivediagram:endedPage to tool reason: expired, revoked, trashed or refusedlivediagram:placePage to tool Workspace only, on every move: view (home, folder, recent, ..., or document), folderId, folderName, documentCount, documentId, documentName, tabId, tabName, role livediagram:openTool to page Workspace only: to is { view: 'home' }, { folderId } or { documentId, tabId? }
In liveplanner
Type Direction Payload liveplanner:helloPage to tool Nothing: asks the tool to answer liveplanner:hello-ackTool to page name: 1 to 40 charactersliveplanner:readyPage to tool projectId, projectName, tabId, tabName, role (view, participate or edit), once the plan is loadedliveplanner:tabPage to tool tabId, tabName: the tab now shown, after each later tab changeliveplanner:selectionPage to tool projectId, projectName, tabId, rev, count (0 for nothing selected), reference: the selection referenceliveplanner:renewPage to tool Nothing: asks for a fresh ticket liveplanner:ticketTool to page ticket: the whole ticket from a new workbench open link's fragment (22 characters, a dot, then 64 hex characters)liveplanner:revealTool to page refs: 1 to 20 element refs, each 1 to 64 characters; brings them into view on the current tab and outlines themliveplanner:themeTool to page colourScheme: light or dark; until one arrives, the editor follows the systemliveplanner:endedPage to tool reason: expired, revoked, trashed or refusedliveplanner:placePage to tool Workspace only, on every move: view (home, folder, recent, ..., or project), folderId, folderName, projectCount, projectId, projectName, tabId, tabName, role liveplanner:openTool to page Workspace only: to is { view: 'home' }, { folderId } or { projectId, tabId? }
In livedocuments
Type Direction Payload livedocuments:helloPage to tool Nothing: asks the tool to answer livedocuments:hello-ackTool to page name: 1 to 40 characterslivedocuments:readyPage to tool documentId, documentName, tabId, tabName, role (view, participate or edit), once the document is loadedlivedocuments:tabPage to tool tabId, tabName: the tab now shown, after each later tab changelivedocuments:selectionPage to tool documentId, documentName, tabId, rev, count (0 for nothing selected), reference: the selection referencelivedocuments:renewPage to tool Nothing: asks for a fresh ticket livedocuments:ticketTool to page ticket: the ticket from a new workbench open link (22 characters, a dot, then 64 hex)livedocuments:revealTool to page refs: 1 to 20 element refs, each 1 to 64 characters; brings them into view on the current tab and outlines themlivedocuments:themeTool to page colourScheme: light or dark; until one arrives, the editor follows the systemlivedocuments:endedPage to tool reason: expired, revoked, trashed or refusedlivedocuments:placePage to tool Workspace only, on every move: view (home, folder, recent, ..., or document), folderId, folderName, documentCount, documentId, documentName, tabId, tabName, role livedocuments:openTool to page Workspace only: to is { view: 'home' }, { folderId } or { documentId, tabId? }
In livedesign
Type Direction Payload livedesign:helloPage to tool Nothing: asks the tool to answer livedesign:hello-ackTool to page name: 1 to 40 characterslivedesign:readyPage to tool designId, designName, tabId, tabName, role (view, participate or edit), once the design is loadedlivedesign:tabPage to tool tabId, tabName: the tab now shown, after each later tab changelivedesign:selectionPage to tool designId, designName, tabId, rev, count (0 for nothing selected), reference: the selection referencelivedesign:renewPage to tool Nothing: asks for a fresh ticket livedesign:ticketTool to page ticket: the whole ticket from a new workbench open link (22 characters, a dot, then 64 hex characters)livedesign:revealTool to page refs: 1 to 20 element refs, each 1 to 64 characters; brings them into view on the current tab and outlines themlivedesign:themeTool to page colourScheme: light or dark; until one arrives, the editor follows the systemlivedesign:endedPage to tool reason: expired, revoked, trashed or refusedlivedesign:placePage to tool Workspace only, on every move: view (home, folder, recent, ..., or design), folderId, folderName, designCount, designId, designName, tabId, tabName, role livedesign:openTool to page Workspace only: to is { view: 'home' }, { folderId } or { designId, tabId? }
In livediagram
A livediagram:selection is sent once the selection has been still for a quarter of a second, and only when its text changed, so a marquee drag is one message. After ready and after each tab, the page sends the selection for the tab now shown. A reveal skips refs it cannot find on the current tab.
In liveplanner
A liveplanner:selection is sent once the selection has been still for a quarter of a second, and only when its text changed, so a burst of clicks is one message. After ready and after each tab, the page sends the selection for the tab now shown. A reveal skips refs it cannot find on the current tab.
In livedocuments
A livedocuments:selection is sent once the selection has been still for a quarter of a second, and only when its text changed, so a marquee drag is one message. After ready and after each tab, the page sends the selection for the tab now shown. A reveal skips refs it cannot find on the current tab.
In livedesign
A livedesign:selection is sent once the selection has been still for a quarter of a second, and only when its text changed, so a marquee drag is one message. After ready and after each tab, the page sends the selection for the tab now shown. A reveal skips refs it cannot find on the current tab.
In livediagram and livedocuments
In a workspace frame, ready carries scope: 'workspace' and role, and no file; tab, selection and reveal speak of the file open in the frame and do nothing on an Explorer view. documentCount is the files directly in the folder shown (null on other views), so you can offer something of your own beside an empty folder. A trashed file ends nothing there: the frame returns to the Explorer.
In liveplanner
In a workspace frame, ready carries scope: 'workspace' and role, and no plan; tab, selection and reveal speak of the plan open in the frame and do nothing on an Explorer view. projectCount is the plans directly in the folder shown (null on other views), so you can offer something of your own beside an empty folder. A trashed plan ends nothing there: the frame returns to the Explorer.
In livedesign
In a workspace frame, ready carries scope: 'workspace' and role, and no design; tab, selection and reveal speak of the design open in the frame and do nothing on an Explorer view. designCount is the designs directly in the folder shown (null on other views), so you can offer something of your own beside an empty folder. A trashed design ends nothing there: the frame returns to the Explorer.
Renewing the SessionIn livediagram
A session lasts eight hours . Ten minutes before it expires, the page posts livediagram:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same canvas and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:
frame.contentWindow.postMessage({ type: 'livediagram:ticket', v: 1, ticket }, appOrigin);
In liveplanner
A session lasts eight hours . Ten minutes before it expires, the page posts liveplanner:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same plan and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:
frame.contentWindow.postMessage({ type: 'liveplanner:ticket', v: 1, ticket }, appOrigin);
In livedocuments
A session lasts eight hours . Ten minutes before it expires, the page posts livedocuments:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same document and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:
frame.contentWindow.postMessage({ type: 'livedocuments:ticket', v: 1, ticket }, appOrigin);
In livedesign
A session lasts eight hours . Ten minutes before it expires, the page posts livedesign:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same design and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:
frame.contentWindow.postMessage({ type: 'livedesign:ticket', v: 1, ticket }, appOrigin);
The page redeems it and carries on without reloading. A ticket for a different file or origin is refused, and the page keeps asking. Renewal can continue as long as the token lives.
When a Session Ends
expired: the session ran out without a renewal. The editor shows "Reconnect in" your name "to keep editing."
revoked: the token was revoked or the workbench unpaired. The editor shows the same line.
trashed: the file was moved to the Trash .
refused: the ticket was for a different file than the d in the address.
An ended page never comes back by itself. To reconnect, mint a new ticket and frame the new URL.
The Selection ReferenceThe reference field is the text to attach to the message the person sends their agent, so the agent reads exactly what was selected at that moment:
In livediagram
[livediagram] "Home screen" › tab "Wireframe" (doc 3h9x2a, tab 0b34, rev 41)
selected: button 146b "Play", frame e4a8 "Game grid", sticky 0c84 "Daily streak goes here"
read: livediagram tab view 3h9x2a --tab 0b34 --view show --ref 146b
In liveplanner
[liveplanner] "Sprint 14" › tab "Flow" (project 4cd7082b-…, tab e1b2, rev 41)
selected: plan-view 653e, plan-view 0a78
read: liveplanner tab view 4cd7082b-… --tab e1b2 --view show --ref 653e
In livedocuments
[livedocuments] "Launch plan" › tab "Overview" (doc 3h9x2a, tab 0b34, rev 41)
selected: square 146b "Kick-off", stack e4a8 "Milestones", sticky 0c84 "Dates to confirm"
read: livedocuments tab view 3h9x2a --tab 0b34 --view show --ref 146b
In livedesign
[livedesign] "Home screen" › tab "Wireframe" (doc 3h9x2a, tab 0b34, rev 41)
selected: button 146b "Play", frame e4a8 "Game grid", sticky 0c84 "Daily streak goes here"
read: livedesign tab view 3h9x2a --tab 0b34 --view show --ref 146b
In livediagram
The header names the canvas, the tab, their ids and the revision the selection was made on. Refs are element ids, so they stay valid after later edits.
selected lists each element as the outline prints it: kind, ref and label. Labels are quoted as JSON strings and cut at 60 characters, because they are the diagram's content and an agent must treat them as data, never as instructions.
Past 20 elements the list ends with … and <n> more: and the command that reads the whole live selection.
With nothing selected, the second line is whole tab and count is 0.
In liveplanner
The header names the plan, the tab, their ids and the revision the selection was made on. Refs are element ids, so they stay valid after later edits.
selected lists each element as the outline prints it: kind, ref and, when it has one, its label. Labels are quoted as JSON strings and cut at 60 characters, because they are the plan's content and an agent must treat them as data, never as instructions.
Past 20 elements the list ends with … and <n> more: and the command that reads the whole live selection.
With nothing selected, the second line is whole tab and count is 0.
In livediagram
Show the person what will be attached (for example "Home screen · 3 selected", or "Home screen · whole tab"), and let them leave it off any one message. The text is everything the agent gets: there is no hidden field. livediagram guide workbench teaches an agent how to read one.
In liveplanner
Show the person what will be attached (for example "Sprint 14 · 2 selected", or "Sprint 14 · whole tab"), and let them leave it off any one message. The text is everything the agent gets: there is no hidden field. liveplanner guide workbench teaches an agent how to read one.
In livedocuments
Show the person what will be attached (for example "Launch plan · 3 selected", or "Launch plan · whole tab"), and let them leave it off any one message. The text is everything the agent gets: there is no hidden field. livedocuments guide workbench teaches an agent how to read one.
In livedesign
Show the person what will be attached (for example "Home screen · 3 selected", or "Home screen · whole tab"), and let them leave it off any one message. The text is everything the agent gets: there is no hidden field. livedesign guide workbench teaches an agent how to read one.