crabshell
a rust replacement for quickshell: your whole desktop shell is a rust crate, and every quickshell type has a crabshell counterpart. v0.8 is on crates.io, with bars, launchers, lock screens, notifications, the clipboard, http, pipewire's link graph, a screen reader, animation and drawing for sway, hyprland, niri and other wlroots compositors, and reloads that never blank the bar. the design doc has every decision, and the site has the full docs
ai disclosure
ai agents write the code, the tests and most of the docs, and other agents review each step against the design doc. a person sets the direction, makes the design calls, reads the reviews and checks the results by hand on a real desktop
get started
you need
~ rust 1.99 or newer
~ sway, hyprland or another compositor with layer-shell, like labwc. the template bar shows sway's workspaces, and the hyprland example hyprland's
~ linux 5.3 or newer
~ pkg-config, and fontconfig, libpulse, libxkbcommon and libpam with their development files: pkg-config libfontconfig1-dev libpulse-dev libxkbcommon-dev libpam0g-dev on debian or ubuntu
~ pulseaudio or pipewire-pulse for the volume, a d-bus session bus for the tray, and a notification daemon like mako for build errors
init writes a cargo project to ~/.config/crabshell and never overwrites one. crabshell init --path <clone> builds against a clone of this repository instead. the first run compiles the toolkit, which takes a few minutes, then a bar shows up at the top of every monitor with sway's workspaces, the tray, the volume and the clock. stop any other bar first
to start it with sway, add exec ~/.cargo/bin/crabshell run to your sway config, or give hyprland the same command with exec-once. cargo has to be on the PATH your session starts with
edit it
change ~/.config/crabshell/src/main.rs while crabshell run runs. each save rebuilds it and swaps the bar in about a second. if the edit doesn't build, the old bar stays and the error shows in the terminal and a notification. a crashing bar restarts, and after three quick crashes crabshell run goes back to the last build that worked. crabshell check checks a config without running it
a config
use *;
every widget property takes a value or a closure. a closure runs again when a signal it reads changes, and only what changed is redrawn. per_output builds windows for every monitor, now and later. the examples show the rest. from a clone, cargo run --release -p crabshell --example launcher runs one, and so do counter, bar, effects, desktop, motion, control, dashboard and notes
docs
~ the site, with getting started and the full docs. open it in a browser
~ the design doc, with every decision and every rule settled while building each crate
numbers
on headless sway with one 1920×1080 output, the counter example uses 19.4 MiB and draws its first frame in 12 to 18 ms, and the v0.1 bar uses 21.7 MiB. neither wakes while idle, except the bar's clock once a minute. on a 1280×720 output, a reload rebuilds a one-line edit in 1.0 s and never leaves the screen without a bar. quickshell drawing the phase 0 test bar used 125 MiB and took 219 ms to its first frame. the design doc has the latest numbers
crates
~ crabshell, run(), per_output, windows, the session lock, the prelude and the examples
~ crabshell-reactive, signals, memos, effects and owners
~ crabshell-ui, widgets, styles, layout, text and focus
~ crabshell-render, drawing on the cpu with tiny-skia, and damage tracking
~ crabshell-wayland, the event loop, windows, input and monitors
~ crabshell-services, workspaces, audio, the tray, d-bus services, programs, files and logins
~ crabshell-cli, the crabshell command: init, check, ipc and run
~ spike and baseline, the phase 0 prototype and the quickshell bar it was measured against
development
AGENTS.md has the test and formatting commands. cargo test --workspace needs dbus-daemon and dbus-monitor, and its golden images expect noto sans as your sans-serif, plus dejavu sans. ci runs it with fmt and clippy on every push. the headless suites run only on your machine, each against a private sway started from a copy of sway, so nothing reaches your session. they need sway, swaymsg, grim, labwc, wl-copy, wl-paste, pipewire and pactl. everything is indented with 2 spaces
license: mit or apache-2.0, your choice