# Glimpse: a native micro-UI for scripts and agents

> Glimpse opens a native WebView window and talks to it over a bidirectional JSON Lines protocol on stdin and stdout, so a Node script can show real UI without Electron or a browser. Each platform has its own backend and its own toolchain, and a few features, notably cursor following and the menu bar mode, do not work everywhere.

**HazAT/glimpse** — Native micro Web UI for scripts and agents — super fast OS native webview with bidirectional JSON communication for agents

- Repository: https://github.com/HazAT/glimpse
- Stars: 979 · Forks: 46
- Language: JavaScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/hazat-glimpse

## A native window instead of a browser

Glimpse is described as a native micro-UI for scripts and agents, running on macOS, Linux and Windows. The mechanism is the interesting part. It opens a native WebView window and speaks a bidirectional JSON Lines protocol over stdin and stdout. There is no Electron and no browser, just a small native binary plus a Node.js wrapper. That combination decides what the tool is good for. A script that wants to show a small panel, a status indicator or a prompt can now put a real window on the desktop without shipping a browser runtime, and because the protocol is line based JSON on the standard streams, the same idea works for an agent that drives the window from a harness rather than from a user interface. The Node API is a single import, and the package is published as glimpseui with a native binary, a Node wrapper and a small command line entry point.

## Four backends, four toolchains

The platform table is the first thing to read, because the requirements are heavier than the one line install suggests. On macOS the backend is Swift with WKWebView and you need the Xcode Command Line Tools. On Linux the native backend is Rust with GTK4 and WebKitGTK, and you need a Rust toolchain plus the GTK4 and WebKitGTK development packages. On Windows it is .NET 8 with WebView2, so you need the .NET 8 SDK and the Edge WebView2 Runtime. And on Linux there is a fourth option, a Chromium CDP backend that needs no compilation at all, just any Chromium based browser. The package is published with the platform list restricted to darwin, linux and win32, and the engine requirement is Node 18 or newer. The zero-compile Chromium route is the pragmatic one for a quick evaluation, because it is the only route on Linux that does not need a Rust and GTK development environment, and the fallback is what makes the tool usable on a machine where you do not want to install a toolchain.

## The install compiles, and quietly skips if it cannot

Installation is a single command:

```bash
npm install glimpseui
```

What happens next is worth knowing, because it is unusual for a package that looks like a pure JavaScript library. The install runs a postinstall hook that compiles the native binary for your platform. If the required toolchain is not found, the build is skipped with a warning rather than failing the install, and you can compile it later. That is a considerate default for a package with three different native toolchains, but it also means a successful npm install does not guarantee a working binary, so a script that fails to open a window should be checked against a manual build. The manual commands mirror the platform matrix:

```bash
npm run build            # auto-detect platform
npm run build:macos      # swiftc
npm run build:linux      # cargo build --release
npm run build:windows    # dotnet publish
```

There is also a path for agent users. The package installs as a Pi agent package with pi install npm:glimpseui, which installs the Glimpse skill for the pi agent, and the repository includes an optional cursor-following status pill extension in the examples directory.

## The API is one function and a set of window flags

The core call opens a window and returns a GlimpseWindow:

```js
import { open } from 'glimpseui';

const win = open(`
  <html>
    <body style="font-family: sans-serif; padding: 2rem;">
      <h2>Hello from Glimpse</h2>
      <button onclick="glimpse.send({ action: 'greet' })">Say hello</button>
    </body>
  </html>
`, { width: 400, height: 300, title: 'My App' });

win.on('message', (data) => {
  console.log('Received:', data); // { action: 'greet' }
  win.close();
});

win.on('closed', () => process.exit(0));
```

The page calls glimpse.send to push an object back to the script, and the script listens for the message event, so the direction of travel is symmetric. The defaults are an 800 by 600 window titled Glimpse, and x and y place it on screen while omitting them centres it. The window style flags are the part that makes this useful for overlays. Frameless removes the title bar so your own HTML can be the chrome. Floating keeps the window above others. Transparent clears the background, which needs a transparent body in your HTML. ClickThrough makes the window ignore every mouse event. NoDock removes the dock icon on macOS while the window still works. The readme lists the useful combinations: a floating HUD for status panels and agent indicators, a custom dialog, an overlay built from frameless plus transparent, and a visual-only companion built from all four.

## Cursor following, and the Linux gap you will hit

The most distinctive feature is a window that tracks the cursor across all screens, and the platform support for it is where this project is honest about its limits. Follow cursor works on macOS and Windows. On Linux with the native backend it requires Hyprland, through its IPC socket. The Chromium CDP backend also supports X11, using xdotool. Any other Wayland compositor without the Chromium backend emits a warning and silently ignores followCursor, and the word silently is the part to remember. The positioning itself is more considered than a raw offset. A cursorAnchor option snaps the window to one of six named points around the cursor, and a fixed safe zone is applied automatically so the window never overlaps the cursor graphic, with cursorOffset available on top for fine tuning. The followMode option chooses between an instant snap and a spring animation with overshoot, and the behaviour can be changed at runtime, including switching to a different anchor, with the spring mode passed as an argument.

## Menu bar mode is a macOS feature and says so

The second native integration is a menu bar icon with a popover WebView, created by statusItem, where clicking the icon shows and hides your HTML content and the popover closes when you click outside it. The same object exposes a click handler, a setTitle method for dynamic updates and a resize method, and there is a command line equivalent that takes a title, a width and a height. The important detail is the failure mode: the call throws on Linux and Windows rather than degrading quietly, so a script that uses statusItem will stop with an explicit error on those platforms instead of pretending to work. If your script needs to run on more than one operating system, that means the menu bar path has to sit behind a platform check in your own code, and the window and overlay APIs are the portable ones.

## What the package contains and where it stands

The published files list is short enough to describe the architecture. The Swift source, the main module at src/glimpse.mjs, the Chromium backend, a follow-cursor support module, a linux directory, the command line entry point at bin/glimpse.mjs, the Windows project and program files, the NuGet configuration, the build and postinstall scripts, the companion example, the skill file and the readme with the changelog. The Windows build is a .NET project published with dotnet, which is why a NuGet configuration is part of the package. Tests are plain Node scripts run with the test script, covering the core, the open links behaviour and the status item, with a separate platform script. The licence is MIT, the author is hazat, and the repository carries an AGENTS.md, a skills directory and a .pi directory, which fits a project that is partly a tool and partly an agent package. On activity, the release line is v0.8.1 from 2026-05-15, after v0.8.0 and v0.7.0 in April, and the last push was on 2026-05-15. There is no release since, so if you adopt it, pin that version and check the changelog before moving.

## Conclusion

Glimpse is the right tool when a script or an agent needs a small, real interface: a status pill, a confirmation dialog, a progress overlay, something that belongs to the desktop rather than to a terminal. It is the wrong choice if you need a real application with menus, tabs and a settings screen, or if you want the same behaviour on every Linux desktop, because cursor following there depends on the compositor. Before you depend on it, check the backend requirements for your platform, call npm run build yourself if the postinstall hook skipped the native binary, and note that the last push was on 2026-05-15 with the release line at v0.8.1.

## FAQ

### What is Glimpse?

Glimpse is a Node package that opens a native WebView window and communicates with it over a bidirectional JSON Lines protocol on stdin and stdout. There is no Electron and no browser, just a small native binary and a Node wrapper, and it runs on macOS, Linux and Windows.

### What do I need to install Glimpse?

Run npm install glimpseui, which triggers a postinstall hook that compiles the native binary for your platform and skips with a warning if the toolchain is missing. macOS needs the Xcode Command Line Tools, the Linux native backend needs Rust with GTK4 and WebKitGTK development packages, Windows needs the .NET 8 SDK and the Edge WebView2 Runtime, and the Chromium CDP backend on Linux needs only a Chromium based browser.

### How does a page send data back to the script?

The page calls glimpse.send with an object, and the script listens for the message event on the window, as in win.on('message', (data) => ...). The window also emits a closed event, which the quick start uses to end the process.

### Does the cursor following feature work on Linux?

Only in specific cases. It works on macOS and Windows, on the Linux native backend it requires Hyprland through its IPC socket, and the Chromium CDP backend supports X11 with xdotool. Other Wayland compositors without the Chromium backend emit a warning and ignore the option.

### Is the menu bar mode available outside macOS?

No. The statusItem call creates a menu bar icon with a popover WebView and throws on Linux and Windows, so a cross platform script has to keep that path behind a platform check.

## Sources

- [HazAT/glimpse on GitHub](https://github.com/HazAT/glimpse)
- [Issues](https://github.com/HazAT/glimpse/issues)
- [License: MIT](https://github.com/HazAT/glimpse/blob/main/LICENSE)
- [README](https://github.com/HazAT/glimpse/blob/main/README.md)
- [Releases](https://github.com/HazAT/glimpse/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hazat-glimpse