Claude Code Mod API UI

Mod API: UI Methods

$.ui draws and manages the interface: lines in the transcript, toasts, panes, scroll, focus, the clipboard, and element tables. Each method is also an event with the same name, such as ui.log, so a hook above the caller can rewrite or refuse the call. Example: await $.ui.open({ id: "clock", title: "Clock" }) opens a pane, and $.ui.toast("Saved") shows a short message.

In the "Where" column, Run time means in a hook, in a closure that a hook drew, or in a timer callback. It does not mean inside register.

Members of $.ui

Mark	Item	What it does	How it works	Where it can be used	Source
✅	$.ui.notice	Shows text as one line under the dialog open for tool_use_id, or removes the line when text is undefined.	Type: (tool_use_id: string, text: string | undefined) => void. Shows a line under an open dialog. Core removes it when the call ends. undefined removes it at once.	A tool.call hook while the call's dialog is open.	CoreEngineInterface line 2378, Mods Reference
✅	$.ui.invalidate	Re-runs an event whose results the engine caches: ui.render draws the instances this plugin may draw again, the others drop the cached answers.	Type: (event: InvalidatableEventName) => void. Asks for a redraw, at most ten a second. It can also drop a cached answer, such as prompt.section or tool.describe.	Run time.	CoreEngineInterface line 2392, Mods Reference
✅	$.ui.blit	Repaints a mounted Raster this plugin's own render hook drew with new cells, or swaps a keyed Image it drew to a new source, no redraw.	Type: (args: UiBlitArgs) => Promise<UiBlitResult>. Paints cells or an image at the next frame. Up to 120 calls a second are taken. Resolves {} or { deny }.	A plugin's own mounted Raster or keyed Image.	CoreEngineInterface line 2413, Mods Reference
✅	$.ui.resolve	The elements of the surface e is drawn on (Elements[e.surface]): a frozen table of constructors, the JSX tags a render hook draws with.	Type: <E extends ResolveInput>(e: E) => Elements[E['surface']]. Reads the frozen element table of the surface. It is a read, not a dispatch.	A ui.render hook (it takes that hook's e).	CoreEngineInterface line 2429, Mods Reference
✅	$.ui.log	Appends one line to the transcript, drawn like a system notice (dim, not sent to the model), or with { to: "debug" } to the debug log alone.	Type: (text: string, options?: UiLogOptions) => void. Adds a log row. The terminal draws 2000 characters, a remote surface 10000. to is transcript (default) or debug.	Run time.	CoreEngineInterface line 2446, Mods Reference
✅	$.ui.ask	Asks the user question in the engine's own AskUserQuestion dialog and resolves to the label they chose, or the text typed under "Other".	Type: (question: string, options?: readonly string[] | AskOptions) => Promise<string>. Asks the person a question with 2 to 4 labels. Rejects if dismissed and in a -p run.	Not in a -p run (rejects). Drawn by ui.render on AskUserQuestion.	CoreEngineInterface line 2462, Mods Reference
✅	$.ui.toast	Shows text for a few seconds under the plugin's name: a small box on the stack of plugin toasts over the transcript's top right corner.	Type: (text: string, options?: ToastOptions) => void. Shows a short message that floats. A click removes it. timeoutMs sets how long it stays (default 4000).	Run time.	CoreEngineInterface line 2479, Mods Reference
✅	$.ui.notify	Raises a native notification of text through the person's own notification channel, the one their preferredNotifChannel names.	Type: (text: string, options?: NotifyOptions) => Promise<UiNotifyResult>. Sends a notification. The Notification hooks run first. Resolves { isSent, channel } or { isSent: false, reason }.	Run time.	CoreEngineInterface line 2497
✅	$.ui.status	Pins text as this plugin's status line under the prompt, beside the engine's own pinned notices, until the next call replaces it.	Type: (text: string | undefined) => void. Keeps one status line for the plugin. undefined removes it. 2000 characters are drawn.	Run time.	CoreEngineInterface line 2509, Mods Reference
✅	$.ui.open	Opens a pane, a framed region the surface places and this plugin draws by hooking ui.render for { component: "Pane" }, says if it is drawn.	Type: (pane: PaneOpenArgs) => Promise<UiOpenResult>. Opens a pane with an id of 1 to 64 characters. Asked panes fit at any width. Unasked panes need 144 columns.	Run time.	CoreEngineInterface line 2532, Mods Reference
✅	$.ui.close	Closes one of the open panes, an id that is not open is left alone.	Type: (pane: PaneCloseArgs) => Promise<void>. Closes the pane with this id. A ui.close hook can keep it open, except on an unload.	Run time.	CoreEngineInterface line 2546, Mods Reference
✅	$.ui.panes	Lists this plugin's own open panes (UiPane): each one's id and title, and whether it is shown, holds the keyboard, and is placed.	Type: () => Promise<readonly UiPane[]>. Lists this plugin's panes in open order, placed ones first. Another plugin's panes are not listed.	Run time.	CoreEngineInterface line 2559, Mods Reference
✅	$.ui.scroll	Scrolls something into view as the DOM's scrollIntoView would: a render instance by requestId, an element by key, a site's edge.	Type: (args: UiScrollArgs) => Promise<UiScrollResult>. Scrolls a site of this plugin. to says where, in says which site, block says where it lands.	Run time.	CoreEngineInterface line 2574, Mods Reference
✅	$.ui.focus	Moves the focus ring of one of this plugin's sites onto an element it drew there, as the DOM's element.focus(), while it holds the keys.	Type: (args: UiFocusArgs) => Promise<UiFocusResult>. Moves the focus to the element key of the site requestId. Resolves {} or { deny }.	Run time.	CoreEngineInterface line 2590, Mods Reference
✅	$.ui.copy	Puts text on the clipboard of a surface the session draws on, as the DOM's navigator.clipboard.writeText, and says whether it took.	Type: (args: UiCopyArgs) => Promise<UiCopyResult>. Puts text on the clipboard of a surface. Resolves { isCopied: true } or { isCopied: false, reason }.	Run time.	CoreEngineInterface line 2604, Mods Reference
✅	$.ui.selection	Returns what the person last selected with the mouse: the text as a copy would take it, and the transcript row it lies in.	Type: () => Promise<UiSelection | undefined>. Returns what the person last selected. undefined with nothing selected, in -p, or when fullscreen is off.	Run time.	CoreEngineInterface line 2618, Mods Reference
✅	$.ui.view	Puts an agent's transcript in the main view, as the person's own switch from the tasks list does, {} goes back to the main one.	Type: (view: SiteView) => Promise<UiViewResult>. Shows another agent's view, named by agentId. Works only while the call answers the person's own input.	Only while the call answers the person's own input (press, pick, prompt, command).	CoreEngineInterface line 2635

See Also

• Mod API: UI Events
• Mod API: Surfaces, Elements, and Render Sites
• Mod API: UI Types
• Claude Code Mod API
• Draw in the Interface