Named after Halley's comet — periodic, precise, returning.
Windows as nodes. Windows as clusters. Windows as your command center.
Halley is a spatial Wayland compositor built for multi-monitor desktops. Each display has an independent infinite Field: a camera over freely overlapping windows, collapsed node landmarks, and clusters assembled around the work you actually want to keep together. Windows can decay when they leave your active area, return through history-aware navigation, or remain pinned as durable landmarks.
Halley 0.6 is a ground-up compositor rewrite. It keeps the Field, nodes, clusters, decay, Trail, Bearings, Apogee, Lift, and native capture experience, but rebuilds their foundations around Smithay's GLES renderer, damage-aware presentation, native embedded XWayland, and a typed public API.
Halley will continue receiving updates, fixes, protocol work, and polish. The project is active, and its core direction is not being paused or held hostage.
Sponsorship helps fund the unglamorous work that makes a compositor durable: documentation, testing, packaging, compatibility, triage, hardware debugging, tooling, and release work. It creates more time to work carefully instead of turning funding thresholds into product promises.
Sponsorship does not buy roadmap control. Halley remains maintainer-directed.
| Term | What it is |
|---|---|
| Field | An infinite, zoomable 2D canvas with an independent camera on each monitor. |
| Node | A managed window's stable identity and its collapsed representation on the Field. |
| Focus Ring | An elliptical active region used by decay and navigation policy. |
| Decay | Configurable transitions that collapse inactive windows outside the focus ring. |
| Landmark | A collapsed or pinned object that remains spatially meaningful while ordinary windows overlap freely. |
| Cluster | A group of windows that opens into its own tiling or stacking workspace. |
| Core | The collapsed Field representation of a cluster. |
| Trail | Per-monitor focus history with backward, forward, list, and exact goto controls. |
| Bearings | A directional overlay for finding and navigating offscreen nodes and cluster cores. |
| Apogee | A multi-monitor overview with live compositor-owned previews. |
Multi-monitor behavior is not an extension of one shared workspace. Every output owns its own camera, focus history, active cluster, fullscreen state, maximize state, and focus-ring policy.
- Independent cameras — pan and zoom one monitor without disturbing the others.
- Free overlap — normal active windows overlap by default instead of being forced through a global no-overlap solver.
- Decay and landmarks — inactive windows can collapse into durable nodes; pinned nodes stay fixed until explicitly moved.
- Move or carry — Mod+drag crosses monitor boundaries, while Mod+Shift+drag dwells at an edge to carry the window through its current output's Field.
- Trail navigation — walk backward and forward through each monitor's recent Field focus history.
- Directional focus — the same action vocabulary adapts to the Field, tiling clusters, and stacking clusters.
The focus ring is an invisible ellipse around the useful part of a monitor's camera. Its dimensions and offset are configurable per output. Windows outside that ring become candidates for timer-driven decay rather than disappearing because an arbitrary global window count was exceeded.
Clusters are deliberate workspaces assembled from ordinary windows.
Enter cluster mode to open the Cluster Composer on the selected monitor.
Eligible windows and collapsed nodes animate into a stable, non-overlapping
mosaic. Use the arrow keys or pointer to focus a card, Space or left click to
toggle membership, Enter to name the draft, and Escape to step back or
cancel. Selected cards keep a persistent tint and checkmark distinct from the
focus frame. Confirming creates a core on the Field; hovering a core can bloom
member previews around it, and opening it enters a monitor-local workspace
while leaving the Field geometry intact behind it.
Two layouts are available:
- Tiling — a master-and-stack layout with directional focus, tile swaps, overflow, and per-member floating.
- Stacking — an overlapping deck with focused-card cycling and retained order.
Cluster slots are per monitor. Opening the active slot again returns to the unchanged Field.
| System | Description |
|---|---|
| Field | Per-monitor infinite canvases with independent pan, zoom, focus, and presentation state |
| Nodes | Stable identities, collapse/restore, pinning, icons, labels, and landmark behavior |
| Clusters | Draft creation, core nodes, tiling, stacking, slots, floating members, and animated transitions |
| Decay | Focus-ring and timer-driven clutter reduction |
| Trail | Per-output recent-focus navigation and remote inspection |
| Bearings | Directional overlays and offscreen navigation |
| Apogee | Multi-monitor overview and live previews |
| Lift | Bundled search and action launcher |
| Capture | Native menu, region, screen, and window screenshots plus portal screencasting |
| IPC/API | Persistent typed clients, capability discovery, subscriptions, and halleyctl |
| XWayland | Native embedded XWayland and compositor-owned X11 window management |
The rewrite intentionally does not carry every old policy forward.
- Native embedded XWayland replaces
xwayland-satellite; game input and pointer-lock bugs belong in the native path instead of a special game-mode exception layer. - The old compositor-side game classifier, special game-mode exception layer, and Gamescope launch wrapper are not part of the rewritten compositor. Launchers can invoke Gamescope directly when desired.
- The supported
halley-apiis for external launchers, panels, automation, tests, and desktop components. Halley currently promises no in-process extension framework. - The former adaptive top-edge client is not being ported. Any future shell in that space will be prototyped as a new design.
- Zoom tops out at native scale. Active windows are governed by focus-ring and timer policy rather than a maximum-window cap.
Halley targets a native Linux Wayland session and expects:
- A DRM/KMS graphics stack with GBM, EGL, and OpenGL ES support
- A seat/session backend through
libseat, such asseatdor logind libinputandudevaccess for the native TTY backend- Rust and Cargo when building from source
Optional desktop components:
- The
Xwaylandexecutable for X11 applications; Halley manages it natively xdg-desktop-portaland a settings/file-dialog backend such asxdg-desktop-portal-gtk
Halley does not require systemd. The default build supports systemd user sessions, while dinit and direct init-agnostic launch paths are also packaged.
Build the complete workspace:
git clone https://github.com/saltnpepper97/halley
cd halley
cargo build --release --workspaceThe build produces:
target/release/halley
target/release/halleyctl
target/release/halley-lift
target/release/xdg-desktop-portal-halley
For user-local testing:
install -Dm755 target/release/halley ~/.local/bin/halley
install -Dm755 target/release/halleyctl ~/.local/bin/halleyctl
install -Dm755 target/release/halley-lift ~/.local/bin/halley-lift
install -Dm755 target/release/xdg-desktop-portal-halley \
~/.local/bin/xdg-desktop-portal-halleyRun a nested development compositor with:
halley --winitUse halley-session or halley --session for a native desktop session. See
the packaging guide for display-manager assets, portal
metadata, systemd, dinit, runit, s6, OpenRC, and distribution paths.
The canonical defaults live in
examples/halley.rune. Keybinds are configurable,
context-scoped, side-aware, and shared by keyboard, pointer-button, wheel,
swipe, and hold actions.
| Category | Keybind | Action |
|---|---|---|
| Basic | Super+Shift+E |
Open Halley's quit confirmation |
| Basic | Super+Q |
Close the focused window |
| Basic | Super+F |
Toggle fullscreen |
| Basic | Super+M |
Toggle Field maximize |
| Basic | Super+N |
Toggle live/collapsed state |
| Basic | Super+P |
Pin or unpin the focused window |
| Overview | Super+O |
Toggle Apogee |
| Focus | Alt+Tab / Alt+Shift+Tab |
Cycle focus forward/backward |
| Focus | Super+Arrow |
Directional focus in the active context |
| Focus | Super+H |
Center the last-focused Field window |
| Trail | Super+, / Super+. |
Previous/next Trail entry |
| Monitor | Super+Shift+Arrow |
Focus an adjacent monitor |
| Move | Super+Alt+Arrow |
Move the focused Field node |
| Resize/Tile | Super+Ctrl+Arrow |
Resize in the Field or swap in a tiling cluster |
| Arrange | Super+A |
Toggle visible Field windows between a mosaic and their saved geometry |
| Clusters | Super+Shift+C |
Enter cluster creation mode |
| Clusters | Super+L |
Cycle cluster layout |
| Clusters | Super+V |
Toggle the focused cluster member floating |
| Clusters | Super+0..9 |
Open a per-monitor cluster slot |
| Bearings | Super+Z / Super+Shift+Z |
Hold or toggle Bearings |
| Launch | Super+T |
Open the first supported terminal |
| Launch | Super+D |
Open Fuzzel (Halley Lift is a commented alternative) |
| Reload | Super+Shift+R |
Reload the selected configuration |
| Zoom | Super+- / Super+= / Super+Shift+0 |
Zoom out, in, or reset |
| Pointer | Super+Left Mouse |
Move a window |
| Pointer | Super+Right Mouse |
Smoothly resize a window |
| Pointer | Left Mouse on empty Field |
Pan the Field |
| Screenshot | Print |
Open native capture |
The same chord may be assigned distinct actions in field, cluster, tile,
and stack scopes. Left/right Super, Alt, Ctrl, and Shift can be matched
independently. Compositor move, resize, and pan grabs are ordinary remappable
bindings rather than hardcoded mouse policy.
On first launch Halley creates
$XDG_CONFIG_HOME/halley/halley.rune, falling back to
~/.config/halley/halley.rune, from the canonical
examples/halley.rune template. Startup never modifies
an existing config, and configs need no version marker. Optional compatibility
updates are explicit and structurally detected: use halleyctl config migrate --dry-run to inspect them before running halleyctl config migrate. Migration
adds only a finite set of known missing bindings or sections, skips conflicting
custom chords, validates the complete candidate, writes atomically, and retains
a timestamped backup. A gathered root reports that the file owning the affected
section must be migrated directly rather than guessing where to write.
Pass -c PATH or --config PATH to select another file. Valid edits reload as
one atomic snapshot; invalid edits leave the last valid runtime state active.
Nested Rune gather dependencies are watched recursively, including missing
dependencies that are created after startup.
The autostart section can also declare persistent named clusters using compact
command arrays, including empty members [] declarations. See
startup clusters for syntax, launch
attribution, output placement, and restart behavior.
Useful controls:
halleyctl config verify
halleyctl config edit
halleyctl config migrate --dry-run
halleyctl reloadhalleyctl also exposes output and DPMS state, capture modes, node and cluster
control, Trail, named-monitor focus, stack/tile navigation, Bearings, and portal
diagnostics. Run halleyctl --help for the current command surface.
halley-api is the supported Rust boundary for launchers,
panels, automation, tests, and desktop components. It provides typed commands
and queries, structured errors, capability negotiation, persistent clients,
and sequenced state subscriptions.
The postcard-based halley-ipc crate is Halley's private transport codec, not
an external compatibility contract. External programs should use
halley-api; halleyctl and Halley Lift are reference consumers of that API.
Halley's Discord is for practical support, config help, bug triage, packaging, release updates, and focused contributor coordination. Halley remains maintainer-directed; Discord is not a roadmap vote.
Join the Discord: https://discord.gg/J2ec3nbHYs
xdg-desktop-portal-halleyfor screenshots and ScreenCast sourcesxdg-desktop-portal-gtkfor common desktop dialogs Halley does not provide
Check the installed backend and advertised capture support with:
halleyctl portal status- Configuration template
- Keybind triggers and actions
- Compositor API
- Field behavior, maximize, zoom, and close succession
- Nodes, decay, focus rings, landmarks, and physics
- Bearings
- Apogee and Alt+Tab
- Animations
- Window decorations
- Managed-window rules
- Wallpaper
- Screen sharing and the desktop portal
- Wayland protocol support
- XWayland policy and conformance
- Building, session managers, and packaging
- niri — compositor architecture and careful Wayland behavior
- vxwm — visual experimentation
- hevel — spatial zooming
- Hyprland — configuration and visual ideas
- newm — spatial compositing
Halley is distributed under the GPL-3.0-only license.