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.

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 → Experiments → Artifacts, 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.