Skip to main content
Artifacts are files the agent writes for you to look at: a report, a chart, a table, a diagram, a small interactive page. Xum shows them in an Artifacts tab in the right sidebar, rendered instead of as raw text. Artifacts are an experiment. Turn on Artifacts in Settings → Experiments.

Where artifacts live

The agent writes artifacts to $XUM_SCRATCH_DIR/artifacts/. Every file in that folder appears in the tab, but files the agent did not publish can wait under Other files (see Open the tab). Files outside it do not, unless you open them yourself (see Open any file). On SSH, Docker and dev container workspaces the scratch folder exists only while the Artifacts experiment is on. Deleting a workspace deletes its scratch folder. Archiving keeps it.

Open the tab

  • Press Ctrl+Shift+K (Cmd+Shift+K on macOS). If the tab already shows, the shortcut moves focus into it. On wide windows, press it again while focus is in the tab to hide the right sidebar.
  • Click an artifact card in the chat. The card shows the file name and its title.
  • On narrow windows, where the right sidebar is hidden, the same shortcut shows the sidebar full-screen on the Artifacts tab. Its Close button or Esc closes it.
The toolbar has a picker for the file, a pin button, and buttons for fullscreen and reload. A dot in the picker marks files that changed since you last looked at them. When the agent published only some of the files (see Publishing), the picker lists those under Artifacts first. The rest, such as screenshots that a published page uses, are under Other files, which starts collapsed. Choose Show N other files to list them. The picker stays open. J and K skip the hidden files.

What each file type looks like

Files over 10 MB are not rendered. The tab offers to copy their path.

Publishing

The tab always shows the file as it is now. When the agent edits the file, the tab follows. Xum keeps no earlier copies. When you delete the file, it leaves the tab. When the agent calls the artifact tool, the chat shows a card for the file, and Xum remembers the file’s title, kind and shelf pin. Publishing the same path again updates them. A kind the agent sets (for example markdown for a .txt file) decides how the tab shows the file.

Layout check

When the agent publishes an HTML artifact, Xum loads the file in agent-browser at 390, 768 and 1440 px wide and measures the layout. It needs no screenshots and no model: a script in the page measures where each line of text and each control lands. It reports text that a container clips or that runs past the page edge, a page that scrolls sideways, controls you cannot reach, and text that another element covers. The agent reads the findings in the result of its artifact call and can fix them in its next publish. The check adds up to 15 seconds and never fails the publish. When Xum cannot close the browser in that time, it removes the browser’s temporary folder in a separate step, which can add up to 5 more seconds.
  • Not checked is not clean. A width counts as checked only when the page settled and the check finished there. When agent-browser is missing, a step times out, the browser fails, or the page keeps animating or changing, the result lists that width as not checked, with the reason, and tells the agent not to call the layout verified. The issues from the widths that did finish are still listed.
  • The check runs where the agent runs. It uses the workspace’s runtime, and a trusted project’s .xum/tool_env decides where agent-browser is found, as for the agent’s shell. It starts its own browser session and closes it when the check ends. It ignores every AGENT_BROWSER_* environment variable and every agent-browser config file, so it never attaches to a browser you already have open. A setting that the browser needs from them, such as a Chrome path, is not applied: if the browser then cannot start, the width reads as not checked. A page that never finishes loading keeps that browser busy, so the close cannot reach it: the browser then shuts itself down within about half a minute.
  • The page is not sandboxed, and the check runs it with the network off. The check opens the file in agent-browser with that tool’s normal access, not in the sandboxed frame of the tab, so the page’s scripts run. Xum turns the network off for the whole browser, not for one tab: every connection goes to a proxy that nothing listens on, no host name resolves, and WebRTC cannot use UDP. A script, style sheet, image, font, socket or window that the page loads from the network fails, so the page is checked without it and can differ from what the tab shows. Files that the page names by a relative path still load. When a window that the page opens takes over the browser’s tab, the check does not trust what it measures there, and that width reads as not checked. The check runs in the page’s own JavaScript world, so a page script that replaces DOM or built-in methods can blind it, and the result then reads as clean. Xum accepts this limit: the author of the page is the user of the check.
  • Clean means the rules found nothing. The check runs six rules at three widths. A clean result means none of them found an issue there. It does not prove that the page has no layout problem. Known false alarms: a collapsed panel (height: 0; overflow: hidden) that holds a block child, such as a paragraph, reads as clipped text. Lines that a line clamp cuts away can read as covered when the clamped element sits inside a text element (a paragraph, heading, list item, button, label, table cell or link) and an opaque block sits right after it. Text in an absolutely positioned or fixed box can read as covered when the box sits in an overflow: hidden element that is not positioned but has a transform, filter, perspective, contain or will-change: the browser cuts the box at that element, and the check does not. Text scrolled out of view inside a scrolling panel can read as covered when an opaque block sits after the panel. Known misses: an image, video or canvas that widens the page, a word cut sideways in a line-clamped box, and a cover over content above or below the visible part of a scrolling panel (an element with overflow: auto or scroll): the check scrolls the page, never a panel.
  • Only .html and .htm files are checked. The browser picks the document type from the file name, so a file with another name that is published as html is not checked, and its result has no layout section.
  • At most 10 issues are listed, new ones first. The rest are counted.
  • Persistent issues. An issue that a publish listed is marked persistent when the next publish of that file finds it again (same rule, same element, same kind of width: phone, tablet or desktop), and the note tells the agent that it may move on and mention the issue to you. An issue that was only counted in the rest is not marked until a publish has listed it. Only a complete check that no longer finds the issue clears it. A width that did not finish and a publish you cancel clear nothing. Xum remembers this in memory only, so a restart of Xum forgets it.

Checks at the end of a turn

A page that the agent edits in place is not published again, so Xum also checks by itself when the agent’s turn ends. You do not need to do anything. Xum checks each due page, a published HTML artifact that changed since its last check: an edit in place, a rewrite from the shell and a change by a sub-agent all count. If a checked page has an issue that no publish result has listed yet, Xum sends the agent one message, which the chat shows as a short row (“Asked the agent to re-publish HTML artifacts and fix layout issues”, or a row that also names the TODO list or status page message sent with it). The message asks the agent to publish the pages it changed again. The result of that publish lists the issues.
  • Silent unless something is new. Xum sends no message when every page is clean, when only issues that a publish already listed remain, or when no page is due for a check. A width that was not checked is not a reason for a message, but a new issue at a width that was checked still is. A publish that happened in the same turn is not checked a second time at the end of the turn.
  • One message for each turn, until a publish lists the issue. Xum asks at most once for each turn that you or a wake-up start, and never at the end of the turn that its own message started, so the check cannot loop. Your next message, a wake-up or a Stop can arrive before Xum’s message, and Xum then does not send it. So Xum checks a page with a new issue again at the end of each later turn, changed or not, until a check settles the page: the agent publishes it again, or a later check finds nothing new. The result of a publish lists the issues, or names the widths that it could not check. After the agent publishes, the issues it was shown count as listed, and the next turn end stays silent for them. The check at the end of a turn does not remember any issue itself. Only a publish does.
  • Where it runs. It runs in the turns that the other end-of-turn messages run in, and not in sub-agent turns, in turns that another workspace waits on, in Plan mode or another plan-like agent (one whose tools include propose_plan), in a turn whose request did not carry the artifact tool (a tool policy or XUM_DISABLE_AGENT_TOOLS removed it), in a side chat, in a turn that xum run or an ACP client waits on, or after a plugin stopped the turn. It also skips a workspace with the Artifacts experiment off. In a workspace that has published a page, every other turn end lists the artifacts folder, and checks nothing when no page is due. In a workspace without agent-browser the check cannot look at the page: it reports that within a fraction of a second, settles the page, and Xum sends no message. Stop ends a running check, and no message follows. A message that you send while the check runs waits for the check to end, and then goes first: Xum does not send its own message. The wait is at most about 15 seconds for the browser (about 20 when Xum cannot close the browser in time), plus the time to list the files.
  • At most 3 pages. If more than 3 pages are due at the end of one turn, Xum checks the 3 that changed last. The rest stay due. Xum checks each of them at the end of a later turn, as soon as fewer than 3 newer pages are due.
  • What “due” means. A page is due when it is published, shown as HTML, named .html or .htm (the publish check skips other names), and its modified time is at or after its bar. The bar is the start of the last check that settled the page, or, when Xum has no such check in memory, the time of the page’s latest publish. A check settles a page when it ran to its end with nothing new to tell the agent, or when it was part of a publish. A check that found a new issue, a check that a Stop ended, and a page past the cap of 3 settle nothing: the bar does not move, so the page stays due at every later turn end, after a restart of Xum too. Xum keeps the start times of the last checks in memory only, for at most 64 pages. After a restart, or when Xum has dropped the start time of a page, the page is due again if it was edited after its latest publish, and the next check settles it. Edits made before the latest publish are not due: that publish checks them. If that check was cancelled and Xum has no earlier check of the page in memory (after a restart, or for a page that no check has settled yet), those edits stay unchecked until the page changes again. A check that could not check a width (it timed out, the browser failed, or agent-browser is missing) still settles the page when the widths that finished show nothing new: a page that cannot be checked costs one check per change, and Xum checks it again when it changes. A remote runtime whose clock differs from this machine’s clock by more than a check takes can make Xum miss a change or repeat a check. On a remote runtime Xum reads modified times in whole seconds, so it counts an edit in the same second in which the last check of that page started, or in which the page was published, as a change, and checks the page once more.
Xum does not hold a page back from the tab until it is checked, the tab has no button for this, and Xum does not read findings from the frame that you see.

Open any file

Open any file as an artifact from the review panel’s file header, from a file path in a tool card, or with Open File as Artifact… in the command palette. A path outside the workspace checkout must be absolute, such as a plan or a skill file in your home folder. Dev container workspaces can open only files inside the checkout. Opened files appear under Pinned files in the picker and update as the file changes. Unpin them from the toolbar.

Shelf

The agent can pin an artifact to a shelf by publishing it with pin: "project" or pin: "global". You can pin the file you are viewing with the pin button in the toolbar.
  • The project shelf shows in every workspace of the same project.
  • The global shelf shows in every workspace.
  • Pinned items appear under Shelf in the picker, marked “pinned by agent” or “pinned by you”. They are read-only copies.
  • Agents read shelf items with artifact_list (scope shelf) and artifact_read.
  • Pinning the same file again from the same workspace replaces its entry. A pin never replaces an entry from another workspace or one you pinned yourself; it gets a numbered name instead.
  • Each shelf file can be up to 10 MB. Workspaces with more than one project have no project shelf.
Shelf files are stored under ~/.xum/artifacts/. The settings backup leaves them out unless you turn on Pinned global artifacts, or include projects (which brings their project shelves). Files over the backup’s 8 MiB limit are skipped and listed.

Talking back to the agent

HTML artifacts can send messages to the agent with a small script API:
  • Call send from a click or key handler. Then Xum sends the message at once. If the send fails, Xum shows the text and the error above the artifact, with Send and Dismiss.
  • A send that comes within a few seconds of your click or key in the artifact, also from a timer, counts as a click. Only one such send goes out at once in 5 seconds.
  • A send with no recent click or key in the artifact, or the second send within those 5 seconds, does not send on its own. Xum shows the text above the artifact with Send and Dismiss. Only your click or the Send shortcut sends it, and Send waits a moment after the message appears.
  • A sent message arrives as your message, labeled “from artifact”. If the agent is busy, it arrives at the next tool step. A message you sent survives an app restart, even if it was still waiting for the agent. A message you have not sent yet does not.
  • setState saves a small JSON value for the artifact. Publishing the artifact again keeps it. The agent sees it in artifact_list.
  • openWorkspace switches Xum to the workspace with that ID. A task ID from the task tool works too, for a sub-agent or a workspace task. Call it from a click or key handler: Xum ignores it unless you just clicked or typed inside the artifact. For an unknown or archived workspace, nothing switches and Xum shows a short notice above the artifact. The artifact never gets an answer, and no workspace list or title reaches it. Pinned files and shelf copies cannot switch workspaces.

Theme variables

Xum sets the current theme’s colors and fonts as CSS variables on the root element of HTML and SVG artifacts, and updates them when you change the theme, without a reload:
The variables are --xum-surface (the background of the pane that shows the artifact), --xum-bg, --xum-bg-secondary, --xum-fg, --xum-muted, --xum-border, --xum-border-light, --xum-accent, --xum-danger, --xum-success, --xum-warning, --xum-font-sans, --xum-font-mono and --xum-radius. Give each one a fallback, so the page also looks right outside Xum. The root element also has data-xum-theme (light or dark) and data-xum-theme-name (light, dark, flexoki-light or flexoki-dark).

Canvases

A canvas is a JSON file that Xum draws with its own components, so it needs no HTML or scripts:
Block types are markdown, table, chart (bar or line; inline rows or a file reference with a JSON pointer), stat, diff, image and button. A button sends its message when you click it.

Annotate

Press C, or use the annotate button, to comment on an artifact.
  • In Markdown, JSON, CSV, text and canvases, select text and add a comment.
  • In HTML and SVG, click to drop a pin.
With the keyboard, press Tab to move into the artifact text, then extend the selection with Shift and the arrow keys. The comment box opens when you release Shift. The artifact text is not an editable field, so Shift and the arrow keys select text only when a screen reader is running, or, in the browser version of Xum, when caret browsing is on (F7 in Chrome and Edge). The desktop app has no caret browsing. Comments attach to your next message, with the artifact and the anchor, so the agent can find the spot.

Goal status board

When the workspace has an active goal, Xum keeps goal.status.html up to date in the artifacts folder. It shows the objective, status, cost against budget, turns against the cap, the todo list, and the pull request’s checks and open review threads when there is one.

Agent interface view

Agent interface view is a sub-experiment of Artifacts. Turn it on under the Artifacts row in Settings > Experiments. When it is on, the main pane shows the agent’s status page, status.html in the artifacts folder, instead of the chat transcript. The message box stays at the bottom, so you can send messages from the status page.
  • At the start of each turn, if status.html does not exist, Xum writes a starter page that uses the theme variables. Xum never replaces a page that exists. The agent is told to keep the page current. Side chats get no starter page, so they show their chat.
  • Switch between the status page and the chat with the Status and Chat buttons in the workspace header, Ctrl+Shift+S (Cmd+Shift+S on macOS), or Switch Status Page / Chat in the command palette. With focus inside the status page, the shortcut only switches to the chat.
  • With focus inside the status page, Esc (Ctrl+C in Vim mode) stops the agent, as in the chat. It does not when you type Esc in a text field, when Esc closes a dialog or popover on the page, or when the page’s script cancels the key (preventDefault). So that a page cannot stop the agent by itself, Esc works there only shortly after you click or press another key in the page.
  • Xum remembers your choice for each workspace. A workspace where you made no choice shows the status page.
  • When the workspace has no status page, or the page is empty or cannot be shown (for example a binary file), the main pane shows the chat transcript.
  • On the status page, every window.xum.send asks first, also from a click: Xum shows the text above the page with Send and Dismiss. The page shows without you opening it, so its script could otherwise take a click elsewhere in Xum for a click in the page.
A bar above the status page, drawn by Xum and not by the page, shows what the agent is doing now (for example the tool it runs, or Idle) and where your last message is: Queued, Held, not sent, Sending…, or In transcript. Show transcript, or Ctrl+Alt+Shift+P (Cmd+Option+Shift+P on macOS), opens the newest transcript rows below the bar, and Xum remembers whether it is open. Start here, or Ctrl+Alt+Shift+H (Cmd+Option+Shift+H on macOS), starts a new context from the agent’s last reply and keeps earlier history, like Start Here on a reply in the chat. It is off while a turn runs. Its shortcut does nothing while focus is in the page, so the page’s script cannot open the confirmation while you type in the page.

Status page agent

Status page agent is a sub-experiment of Artifacts that needs Agent interface view. Turn both on under the Artifacts row in Settings > Experiments: the Status page agent row shows there only while Agent interface view is on. When it is on, a separate status page agent keeps status.html current, so the main agent spends no time or tokens on the page.
  • The main agent sends short updates with the status_update tool. The call returns at once, and the status page agent edits the page in the background. Updates sent while it runs go into its next run together.
  • When the main agent ends a turn without a status_update call, and the page is missing, blank, still Xum’s placeholder, or did not change in a turn that did work, Xum asks the agent once to call status_update. A turn that sent an update gets no reminder, because the status page agent can still be editing the page when the turn ends. When you turn the status page agent off before the turn ends, the reminder asks the agent to edit the page itself.
  • Pick the status page agent’s model in Settings > Agents > Status Page. That card shows only while Artifacts, Agent interface view and Status page agent are all on. When the model is Inherit, it uses the workspace’s model. A small, fast model is usually enough.
  • The status page agent can change only status.html. It does not write to an archived or removed workspace, or after you turn the experiment off. Removing a workspace stops its run in progress.
  • Its spend shows in the workspace’s costs, like other background agents.
  • Waiting updates are capped at the newest 20, and at 20,000 characters in total. Older updates are dropped.
  • An update can have up to 4,000 characters. A run stops after 8 model steps and keeps the edits it made until then. A run fails when it takes more than 2 minutes, or when status.html is larger than 256 KiB. The status page agent cannot make the page larger than 256 KiB.
  • When a run fails (for example the model is unavailable, or the run ends without a change to the page), the main agent’s turn goes on. The result of its next status_update call says that the last update failed, and the agent can then edit the page itself. The updates of the failed run are applied again with the next update.
  • When the page changes while a run is in progress (for example the main agent edits it), the run does not overwrite that change. Its updates count as failed and are applied again, on top of the changed page, with the next update.
  • Some updates are dropped without being applied: updates over the caps, and updates of a run cut short because you turned the status page agent off or archived the workspace. The result of the next status_update call says how many were dropped, so the main agent can send again what still matters.
  • To stop the status page agent without turning off the experiment, switch off Enabled on its card in Settings > Agents. The main agent then edits the page itself. When a turn starts while the status page agent is off (its Enabled switch, or one of the experiments it needs), waiting updates and a failure that was not reported yet are dropped, so they do not come back when you turn it on again. A run that is in progress at that time writes nothing, and its updates are dropped too. When you turn it off and on again before a turn starts, nothing is dropped.
  • An agent whose tool policy removes status_update (for example a custom agent with tools.remove: [status_update]), a turn that disables it, or a plugin hook that removes it from the request, gets the usual guidance and reminder to edit the page itself.

Apps from MCP servers

MCP servers that support MCP Apps can return a small interface with a tool result. Expand the tool card to use the app inside the card. App views do not appear in the Artifacts tab, which lists only files. MCP Apps are a separate experiment. Turn on MCP Apps in Settings → Experiments. They do not need the Artifacts experiment. If you had Artifacts on before MCP Apps got their own experiment, Xum keeps MCP Apps on for you.
  • Open in tab on the tool card opens the app in its own tab in the right sidebar, named after the tool and its server. If the app already has a tab, Xum selects it.
  • The command palette has an Open App View entry for each app in the workspace.
  • An app runs in one place at a time. While its tab is open, the tool card shows Go to tab instead. Close the tab to bring the app back to the card.
  • On narrow windows, where the right sidebar is hidden, Open in tab shows the sidebar full-screen on the app’s tab.
  • The app asks before it calls a tool that the agent can also call, before it opens a link, and before it inserts text into your message.
  • It cannot reach domains it did not declare, and only declared domains that are on the CDN list below.
  • If the project or workspace limits which MCP tools are allowed, the app can call only tools on that list, including tools meant only for the app.

Security

HTML and SVG artifacts run in a sandboxed frame with no access to Xum, your files, cookies or storage. A strict content security policy blocks network requests. Allow CDN assets in artifacts (Settings → Sandbox & limits → Artifacts, shown while the Artifacts experiment is on; on by default) lets artifacts load scripts, styles and fonts from a few public CDNs: cdnjs, unpkg, jsDelivr, the Tailwind CDN, the jQuery CDN and Google Fonts. The URL of such a request can carry data out. Turn the setting off to block these hosts. The policy cannot block every channel (for example WebRTC). Treat artifact content as untrusted. If an artifact or app tries to load a different page, Xum blocks it and the artifact stays as it was. While Xum asks you to confirm a message, a tool call or a link, the artifact cannot change what you are confirming. The confirm buttons stay disabled for a moment after the prompt appears. When agent-browser is not installed where the agent runs, HTML artifacts show “Not checked by the agent: agent-browser is not available on this runtime.”

VS Code extension

The VS Code extension shows artifact cards in the chat, but it has no Artifacts tab. Open artifacts in the Xum app.