Wayland Shell

woven-shell

A complete desktop environment shell for Sway. Everything you need to run a full Wayland desktop — compositing shell, bar, app launcher, lock screen, wallpaper engine, power menu, control center, configuration manager, OSD notifications, screenshot tool, workspace switcher, and session daemon.

v1.2.1 · Rust + Smithay · CachyOS + Niri tested

↗ GitHub ↗ AUR
Components

What's Included

woven-bar

Top/bottom status bar with workspaces, window title, clock, system info (CPU, memory, audio, battery), notifications, systray integration, and customizable modules.

Rust Smithay

woven-power

Full-screen power menu overlay with lock, logout, suspend, hibernate, reboot, shutdown. Keyboard + mouse navigation. Integrates with woven-lock or swaylock.

Rust tiny-skia

woven-lock

Elegant Wayland lock screen with blurred background, clock, date, customizable colors, animations, shake on wrong password. PAM authentication.

Rust Smithay

woven-wall

Wallpaper engine. Random or fixed image, pixel transition effects (pixelate, fade, dissolve), automatic rotation timer, smooth transitions.

Rust image processing

woven-launch

Application launcher with fuzzy search, system command execution, calculator mode, command runner. Fast, minimal, zero-bloat.

Rust tiny-skia

woven-cfg

GUI configuration manager for all woven-shell components. Edit bar height, colors, themes, keybinds, power menu settings, lock screen appearance, all from one place.

Rust Smithay

woven-cc

Control center overlay. Quick access to brightness, volume, WiFi, airplane mode, screen layout settings without leaving your desktop.

Rust DBus

woven-osd

On-screen display for volume, brightness, media playback feedback. Stays out of the way, appears when needed.

Rust DBus

woven-screenshot

Screenshot tool. Region select, full screen, window capture with customizable output directory and naming. Integrates with clipboard.

Rust screencopy

woven-switch

Workspace switcher. Visual grid of all workspaces with live previews. Click or keyboard to switch. Always know where your windows are.

Rust Smithay

woven-session

Session manager. Coordinates startup, manages config hot-reload, acts as DBus service hub for all other components, handles systemd user session.

Rust zbus · systemd

woven-pick

Color picker. Click anywhere to sample colors. Hex, RGB, HSL output. Copy to clipboard instantly.

Rust screencopy
Features

Why woven-shell

  • Complete solution — Everything a desktop needs. No hunting for separate utilities.
  • Consistent design — All components share the same aesthetic, theme, and principles.
  • Fast and minimal — No frameworks, no bloat. Smithay + tiny-skia render everything precisely.
  • Highly configurable — TOML configs for everything. GUI config manager for quick changes.
  • Wayland-first — Built on modern protocols. No X11 legacy code.
  • Keyboard-driven — Everything accessible via keyboard. Vi keybindings where sensible.
  • Active development — Regular updates, responsive to issues, Sway + Niri tested daily.
  • Themeable — Light/dark themes, color customization throughout.
  • Well-documented — Clear config examples, keybind reference, component docs.
Installation

Get Started

Arch Linux / CachyOS

Available on AUR as woven-shell-git:

yay -S woven-shell-git
# or
paru -S woven-shell-git
# or
git clone https://aur.archlinux.org/woven-shell-git.git
cd woven-shell-git && makepkg -si

From Source

git clone https://github.com/viewerofall/woven-shell.git
cd woven-shell
./install.sh --all  # Interactive install
# or
./install.sh --package  # Build release tarball

Configuration

Config files live in ~/.config/woven-shell/:

  • bar.toml — Height, position, modules, colors, fonts
  • lock.toml — Lock screen appearance, background, animations
  • launch.toml — Launcher size, colors, features
  • wall.toml — Wallpaper path/directory, transition effects
  • keybinds.toml — All keyboard shortcuts (managed by woven-cfg)

Edit files directly in your editor or use woven-cfg GUI to configure everything visually.

Configuration

Customization Example

Here's what a typical lock screen config looks like:

# woven-lock config — ~/.config/woven-shell/lock.toml

[background]
type = "random"
dir  = "~/Pictures/Wallpapers"

[lock]
lock_program   = "woven-lock"  # or "swaylock"
blur_radius    = 20
show_clock     = true
clock_format   = "%H:%M"
show_date      = true
date_format    = "%A, %B %e"
text_color     = "#cdd6f4"
accent_color   = "#cba6f7"
error_color    = "#f07178"
fade_in_ms     = 200
fade_out_ms    = 200
shake_on_error = true

Most settings can be edited through woven-cfg GUI without touching TOML files.

Architecture

Design Principles

Surface State Machine

Each component is a Wayland layer shell surface with explicit lifecycle. No orphan surfaces, no scrambled rendering. woven-via enforces protocol compliance.

No Null-Buffer Unmapping

Surfaces stay permanently mapped on Niri. Instead we toggle keyboard interactivity to show/hide. This avoids compositor state thrashing.

Tight Rendering Loop

50ms main loop tick. All animations frame-synced. No wasted redraws. Tiny-skia for immediate-mode rendering.

Workspace Deps Inherited

Single Cargo.toml workspace root. All crates inherit versions, avoiding dep hell across 13 binaries.

Config Before Render

Lua config seeded into every render thread before it spawns. No config mutation at runtime.

Smithay Foundation

Smithay client toolkit v0.20 handles all Wayland protocol machinery. Tested against Sway, Niri, Hyprland.

Credits

Tech Stack

  • Rust — Primary language. ~15k lines total across all components.
  • Smithay — Wayland client toolkit. Protocol handling, layer shells, input events.
  • tiny-skia — 2D rendering. All UI drawn immediately-mode, no retained state.
  • fontdue — Fast font rasterization. Supports Nerd Font icons.
  • zbus — DBus daemon for session management and component IPC.
  • image — Image loading and JPEG decoding for wallpapers.
  • toml — Config file parsing. Simple, human-readable format.
  • Tauri — woven-cfg GUI (v2), Electron alternative for desktop apps.
Community

Get Involved

Found a bug? Want to suggest a feature? Have a config you want to share?

Open an issue or PR on GitHub. Tested on CachyOS + Niri daily. Sway fully supported.