agentty-gpui

Agentty's own UI framework — a GPU-drawn Rust UI for macOS, Windows and Linux, published on crates.io as 20 crates.

agentty-gpui is the UI framework made for Agentty, based on Zed's gpui.

It holds everything Agentty needs to draw its interface on the GPU: elements and layout, windows and menus, keyboard and mouse input, text shaping and fonts, images and SVG, and the backends and renderers for macOS, Windows and Linux. Fixes and features Agentty needs go straight into it, and it is published on crates.io as 20 crates so any Rust app can use it the same way.

Getting started#

Add two crates: agentty-gpui, the framework, and agentty-gpui-platform, which starts the backend for the OS it runs on. Their library names are gpui and gpui_platform, so code says use gpui::....

sh
cargo add agentty-gpui --rename gpui
cargo add agentty-gpui-platform --rename gpui_platform
rust
fn main() {
    gpui_platform::application().run(|cx: &mut gpui::App| {
        // open windows, bind keys, ...
    });
}

Each platform has something to switch on:

PlatformSetup
macOSruntime_shaders on agentty-gpui-platform compiles the Metal shaders at startup, so the build doesn't need Xcode's Metal toolchain. Without it they compile at build time and the toolchain is required (xcodebuild -downloadComponent MetalToolchain).
WindowsNothing extra. The default windows-manifest feature embeds the app manifest in the executable.
LinuxTurn on wayland and/or x11 on both crates.

Features#

The features of agentty-gpui. The defaults are font-kit, wayland, x11 and windows-manifest.

FeatureWhat it does
font-kitFinds and loads system fonts (default)
wayland, x11Linux display server support (default)
windows-manifestEmbeds the Windows app manifest in the executable (default)
screen-captureScreen capture
inspectorAn inspector for the elements of a running UI
test-supportThe test platform and helpers
leak-detectionTracks entity handles so tests can catch leaks; setting GPUI_LEAK_DETECTION at build time turns it on too
bench-supportBenchmarks and the profiler (bench is its older name)
profilerFrame time histograms
stackerGrows the stack for deep recursion
hot-reloadHot reloading of code during development

agentty-gpui-platform passes the features of the same name on to each backend (font-kit, inspector, screen-capture, test-support, bench-support, wayland, x11, runtime_shaders). Its default is multithreaded.

The crates#

All are published at the same version, and a build compiles only the crates for its target. Each link goes to the crate's crates.io page.

Framework#

CrateLibrary nameWhat it isDepends on
agentty-gpuigpuiThe framework: elements, flexbox layout (Taffy), windows, input, actions and key bindings, text, images and SVG, the async executorcollections, http-client, macros, refineable, scheduler, shared-string, sum-tree, util, bench-metrics (optional)
agentty-gpui-platformgpui_platformPicks the backend for the current OS and starts the app (gpui_platform::application())agentty-gpui, macos, windows, linux, wgpu (optional)
agentty-gpui-macrosgpui_macrosThe framework's derive and attribute macros—

Platform backends and renderers#

CrateLibrary nameWhat it isDepends on
agentty-gpui-macosgpui_macosmacOS backend: AppKit windows and menus, input, notifications, screen capture (optional)agentty-gpui, apple, collections, scheduler, util
agentty-gpui-applegpui_appleMetal renderer and Core Text text, shared by Apple platformsagentty-gpui, collections, util
agentty-gpui-windowsgpui_windowsWindows backend: Direct3D 11 renderer, DirectWrite text, DirectCompositionagentty-gpui, collections, scheduler, util
agentty-gpui-linuxgpui_linuxLinux backend: Wayland and X11, keyboard layouts (xkbcommon), desktop portalsagentty-gpui, collections, http-client, util, wgpu (optional)
agentty-gpui-wgpugpui_wgpuwgpu renderer, used on Linuxagentty-gpui, collections, util

Foundations#

CrateLibrary nameWhat it isDepends on
agentty-gpui-utilgpui_utilSmall shared helpers—
agentty-gpui-shared-stringgpui_shared_stringSharedString, a string shared without copying—
agentty-gpui-collectionscollectionsHash map and hash set typesutil
agentty-gpui-sum-treesum_treeThe concurrency-friendly B-tree under lists and textztracing
agentty-gpui-schedulerschedulerAsync task scheduler—
agentty-gpui-refineablerefineableThe Refineable trait that lets a style be partly overriddenderive-refineable
agentty-gpui-derive-refineablederive_refineableIts derive macro—
agentty-gpui-http-clienthttp_clientHTTP client interface, for images loaded from URLs—
agentty-gpui-zlogzlogLoggingcollections
agentty-gpui-ztracingztracingTracing, with optional Tracy profiler supportztracing-macro, zlog (optional)
agentty-gpui-ztracing-macroztracing_macroIts attribute macro—
agentty-gpui-bench-metricsbench_metricsPerformance counters—

The iOS and web backends are left out, because Agentty ships on macOS, Windows and Linux. So are the image and image_gallery examples, which need the original's HTTP client.

crates.io dependencies#

A crate on crates.io can depend only on crates on crates.io. Where the original takes a dependency from Git or a fork, agentty-gpui uses the crates.io release:

CrateWhat the original's version adds
async-taskA fix for task waker vtable identity
calloop (Linux)Idle callbacks capped at about 10 ms per loop
khronos-egl (Linux)No panic when a failed EGL call reports success
wgpu, naga (Linux)A newer API (QueueDescriptor, has_srgb_suffix)
zed-font-kit, zed-scap, zed-ximSmall fixes since
oo7 (Linux)An error when the prompt stream ends
windows-capture (Windows, screen-capture)Nothing; held in Cargo.lock at the last release that builds with zed-scap, and a crate that turns on screen-capture must hold it too

How it is updated#

There are two branches:

  • main: the published code, with every change made for Agentty.
  • upstream: the original code it is based on, unchanged, one commit per original release. zed/SNAPSHOT.md names the release.

Taking in a new original release:

sh
scripts/sync-upstream.sh <tag>   # a new snapshot on upstream
git merge upstream                 # into main; only files changed here can conflict
python3 -I scripts/apply_agentty.py

If a crate manifest conflicts in the merge, take the original's side (git checkout --theirs <file>) and rerun the script.

Tests#

sh
cargo nextest run --workspace --features agentty-gpui-apple/runtime_shaders
cargo test --workspace --doc --features agentty-gpui-apple/runtime_shaders
  • Use nextest: a few tests read process-wide state and fail when cargo test runs them side by side.
  • CI uses --profile ci (.config/nextest.toml), which retries a failed test twice, because a few bench tests time an 80 ms poll and can miss on a busy runner.
  • Linux CI uses Mesa's software Vulkan driver for the wgpu renderer tests.

Publishing#

  1. Bump VERSION in scripts/apply_agentty.py, rerun it and push. CI must pass, cargo publish --workspace --dry-run included.
  2. Run the Agentty workflow in GitHub Actions. It builds and tests Agentty against this checkout on macOS, Windows and Linux.
  3. cargo publish --workspace publishes the crates in dependency order.
  4. Tag the release (git tag v<version> && git push origin v<version>).

Reporting a problem#

A bug in agentty-gpui, or a change you want in it, goes to agentty-gpui's issues. A bug in Agentty goes to Agentty's. For how Agentty differs between operating systems, see Platforms.