| name | glimpse |
| description | Show native macOS UI from scripts and agents — dialogs, forms, visualizations, floating widgets, cursor companions. Use when you need to display HTML to the user, collect input, show a chart, render markdown, or create any visual interaction without a browser. |
Glimpse — Native macOS Micro-UI
Glimpse opens a native macOS window with a WKWebView in under 50ms. You write HTML, the user sees it instantly. Bidirectional communication via window.glimpse.send() (webview -> Node) and .send(js) (Node -> webview).
When to use Glimpse:
- You need user input beyond yes/no (forms, selections, text input)
- You want to show something visual (charts, markdown, images, diffs)
- You want to confirm a destructive action with a proper dialog
- You want a floating indicator, notification, or companion widget
- You need the user to interact with rich content
Import: Always use the absolute path to glimpse.mjs within the installed package:
import { open, prompt } from '/Users/joemccann/dev/apps/util/glimpse-ui/src/glimpse.mjs';
Quick Reference
One-Shot Dialog (prompt)
const answer = await prompt(html, {
width: 400, height: 300,
title: 'My Dialog',
frameless: true,
transparent: true,
});
Persistent Window (open)
const win = open(html, options);
win.on('ready', (info) => {});
win.on('message', data => {});
win.on('closed', () => {});
win.send('document.title = "Hi"');
win.setHTML('<h1>New content</h1>');
win.close();
All Options
{
width, height,
title,
frameless: true,
floating: true,
transparent: true,
clickThrough: true,
followCursor: true,
followMode: 'spring',
cursorAnchor: 'top-right',
cursorOffset: {x, y},
openLinks: true,
autoClose: true,
x, y,
timeout,
}
In-Page JavaScript Bridge
window.glimpse.send(data)
window.glimpse.close()
Common Patterns
- Confirm Dialog:
prompt() with yes/no buttons, Enter/Escape keyboard handling
- Text Input Form: Input fields with submit on Enter
- Selection List: Arrow keys + Enter to pick from a list
- Live Progress:
open() + push updates via .send() as work progresses
- Floating Notification: Frameless + transparent + floating + clickThrough + auto-dismiss
- Cursor Companion: followCursor + clickThrough for agent status indicators
- Command Palette: Frameless + transparent + backdrop blur + search input
Tips
- Always set
cursor: pointer on clickable elements
- Use
autofocus on the primary input field
- Add keyboard shortcuts — Enter to confirm, Escape to cancel
- For transparent windows, set
background: transparent !important on <body>
prompt() returns null when the user closes without sending — always handle this- Be generous with window height — content clips without scrollbars
