ashell: a status bar for Wayland that tries to detect your compositor

The feature set that makes it more than a bar

ashell is a ready to go status bar for Wayland compositors, and the feature list runs to about thirty entries, which is unusual for a bar.

The first entry sets the tone: automatic Wayland compositor detection, with a link to a dedicated compositor support page. The topic list names Hyprland, MangoWC and Niri, and the feature list mentions them individually for the keyboard layout, the keyboard submap and the custom labels, so the detection is not decorative. A bar that has to know which compositor it is running under, in order to ask for a workspace switch or a layout change, has to detect it.

The display side is conventional but complete. Multi-monitor support, with all monitors, the active monitor or specific targets. Bar positioning at the top or the bottom with a configurable layer of Bottom, Top or Overlay. Theming that is either transparent, described as islands, or a solid bar surface, with custom radius, margin, colors, opacity, scale and fonts. Hot-reload configuration, so changes apply automatically via a file watch.

The status items are the usual set: an OS updates indicator with a configurable check interval, the active window by title, class or initial title and class, workspaces with naming, colour coding and per-monitor visibility, and system information covering CPU, RAM, disk, IP address, network speed and temperature, with warn and alert thresholds.

Then the parts that make it feel like an application rather than a widget: a system tray with context menus, a clock with a calendar, weather, timezone cycling and format cycling, privacy indicators for microphone, camera and screenshare use, a media player with album art and track information, and a notification manager with toast popups, grouping and urgency support.

The settings panel is the real feature

The settings panel is where ashell differs from a conventional bar, and it is worth enumerating because it determines whether the bar is a display or an interface.

The power menu offers shutdown, suspend, hibernate, reboot, logout and lock. There is battery information, including peripheral batteries, so a keyboard or mouse with a battery can be reported. Audio sources and sinks are selectable, with the microphone included. Screen brightness is adjustable. The network panel does WiFi scanning and password entry, and it supports both the NetworkManager and the IWD backends, which is the kind of detail that only appears in a project that has been used on more than one distribution.

Beyond that there is a VPN panel, a Bluetooth panel, power profiles, an idle inhibitor and airplane mode. And there are custom quick-action buttons with status commands, which is a mechanism for adding a control the project does not ship.

The visual design is shown in the screenshot gallery, which is extensive enough to be a documentation page in its own right. There are screenshots of the transparent surface, described as the default, the solid surface, the opacity settings, an updates panel, the system menu, the tray menu, the power menu, the sinks selection, the network menu and the Bluetooth menu.

The author is candid about the gallery, saying they will try their best to keep the screenshots updated but that some details could be different. That is the right thing to say about screenshots of a fast-moving UI, and it is also a reminder that the gallery is documentation of a moment rather than a specification.

Compositor-specific modules, and the IPC socket

Several features are explicitly scoped to particular compositors, and reading which is the clearest way to understand the project's shape.

The keyboard layout module supports custom labels for Hyprland, Niri and MangoWC, and the keyboard submap module is marked as Hyprland and MangoWC only. The workspaces module, with naming, colour coding and per-monitor visibility, is the feature that most depends on a compositor's own concept of workspaces, and MangoWC in particular has a different model from the other two.

The one feature that is not about the display at all is the IPC socket, which exists for scripting and keybindings, and it is invoked as `ashell msg <command>`. That is a small design decision with large consequences for a shell user. Anything you can trigger from the bar can be triggered from a keybinding, and anything the bar can show can be driven by a script, without the bar needing to expose a scripting language or a plugin API.

The custom modules feature completes the picture. There is a Button module, which executes a command on click, and a Text module, which is display-only and can update its user interface with command output through a `listen_cmd` mechanism. There is also regex-based icon mapping and alert states, so a module can change its icon based on what its command returns.

And there is an OSD overlay for volume, brightness and airplane mode changes, which is the kind of thing that has to be implemented separately because the bar itself is not necessarily visible at the moment the change happens.

The Rust stack and the forked UI toolkit

The `Cargo.toml` shows a workspace with one member, `crates/ashell-services`, and the main package at version 0.11.0. The edition is 2024 and the minimum Rust version is 1.89, and the author is Simone Camito.

The dependency that tells the most is the UI toolkit. The package is `iced`, but it is not the upstream iced: it is `iced_layershell`, pulled from a Git repository at the tag v0.6.1, with the features tokio, advanced, wgpu, tiny-skia, image, svg and canvas. That is a fork maintained by the same author as the bar.

The reason is layer-shell support. A Wayland status bar is a layer-shell surface, which is a Wayland protocol for a surface that occupies a screen edge and is not part of the normal window stack. Rendering that with the standard toolkit is not possible, so the toolkit needs a layershell backend, and rather than wait for upstream the author forked it. The wgpu feature also means the bar is rendered on the GPU through wgpu with tiny-skia for the 2D drawing.

The rest of the stack is small and deliberate. `tokio` and `zbus` are the asynchronous runtime and the D-Bus library, which is how a Wayland desktop talks to its services. `inotify` with the stream feature is what makes the hot reload possible. `chrono` handles the clock, and `iced_anim` provides the animations. There is also a `hyprland` dependency pulled from a Git repository, which is the direct integration for that compositor.

The release profile is tuned for a shipped binary: thin link time optimisation, symbols stripped, optimisation level 3, and `panic = "abort"`.

The packaging metadata is in the same file, through nfpm, for both deb and rpm, and it lists the runtime library dependencies the bar needs: libxkbcommon, libwayland-client, PipeWire, PulseAudio, libudev and D-Bus for the Debian build, with the RPM equivalents.

The build, the tests and the flake

The Makefile is a short wrapper around cargo, and its target list is the whole build story:

build:
	cargo build --release

start: build
	./target/release/ashell

install: build
	install -Dm755 target/release/ashell $(DESTDIR)$(BINDIR)/ashell

fmt:
	cargo fmt

check: fmt
	cargo check --workspace
	cargo clippy --workspace -- -D warnings
	cargo test -p ashell-services --all-features

The `check` target is where the project's standards live. It formats the code, type checks the whole workspace, runs clippy with warnings treated as errors, and runs the tests for the `ashell-services` crate with all features enabled. The `install` target honours `DESTDIR` and `PREFIX`, with the prefix defaulting to `/usr`, so it installs into distribution packaging without modification.

Note what the test command covers: `cargo test -p ashell-services --all-features`. The tests are on the services crate rather than on the whole workspace, so the UI crate is checked and linted but its own test suite is not part of that command.

The repository is a full project rather than a single crate. There is the `src/` directory for the application, `crates/` for the workspace member, `assets/` for icons, `docs/` and `website/` for the documentation, `i18n/` with an `i18n.toml` for translations, `screenshots/`, a `flake.nix` and `flake.lock` for Nix, a `dist-workspace.toml` for the release distribution tooling, and an `.rpm/` directory. There is also an `AGENTS.md` and a `CLAUDE.md`.

The project is published through a Repology badge, which is the packaging status aggregator for Linux distributions.

The AI contribution policy, which is unusually specific

The README has a section on AI-assisted contributions, and its content is worth quoting because it says what a project actually cares about.

AI-assisted contributions are accepted, and the same quality standards apply regardless of how the code was written. You are responsible for the code you submit, so you have to review AI output carefully, make sure `make check` passes, and be prepared to explain your changes.

Then the two sentences that carry the policy. Before working on a feature or a large change, discuss it with maintainers first. And small, incremental pull requests are preferred, because code review is manual and remains the bottleneck.

That second point is the important one. The stated constraint is not that the code must be good, it is that human review capacity is the scarce resource, so the contribution format is optimised for the reviewer rather than the contributor. A large AI-generated pull request consumes the scarcest resource in the project in exchange for code that still has to be read line by line.

The project has been changing fast enough for this to matter. The releases are 0.11.0 from 2026-10-02, 0.10.0 from 2026-09-01 and 0.9.0 from 2026-06-08, and the last push was on 2026-10-19. A version number in the zero series with a release every few weeks is a project in active churn, which is exactly the situation where a review bottleneck and a large feature surface combine badly.

The full policy lives in a dedicated page of the Developer Guide, under the AI-assisted contributions section.

Where ashell is the wrong choice

The first wrong case is X11. This is a Wayland bar, with a Wayland toolkit, layer-shell surfaces and a D-Bus stack, and there is no X11 path in the feature list or the dependency list. A user on an X11 session is out of luck.

The second is a compositor that is not covered. The detection covers Hyprland, Niri and MangoWC, and the topic list also mentions wlroots, so a wlroots-based compositor is broadly in scope, but the keyboard submap module is explicitly limited to Hyprland and MangoWC. If your compositor is something else, the bar will start and the compositor-specific features will be missing, which is a worse experience than a bar that refuses to start.

The third is a system without the required libraries. The packaging metadata lists libwayland-client, libxkbcommon, PipeWire, PulseAudio, libudev and D-Bus. A minimal container or a server without a desktop stack cannot run it, and the pipewire dependency in particular means the bar expects a PipeWire-capable audio stack.

The fourth is a person who wants a bar that does nothing but show a clock and a workspace list. ashell is a large application with a settings panel, IPC socket, custom modules and a notification manager. That is a lot of surface for a user who wanted a clock.

The fifth is a team that expects a stable configuration format. The configuration is hot-reloaded from a file, and a bar with this many modules produces a configuration with this many sections, and the project is on a zero-series version with frequent releases. The configuration documentation is on the website, and it is the part you will actually live with.

Editorial conclusion

ashell suits a Wayland user on Hyprland, Niri or MangoWC who wants a bar with the system controls, the tray and the notifications in one place, and who is comfortable editing a configuration file and restarting the bar when the compositor changes. It does not suit an X11 user, and it does not suit a person who wants a bar that works on every desktop without a compositor-specific layer. Before adopting it, read the compositor support page to confirm your compositor is covered, and note that the upstream dependencies list is a Wayland and PipeWire stack, so a system without `libwayland-client` and PipeWire is a non-starter regardless of what the compositor is.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. MalpenZibo/ashell on GitHub
3. Project website
4. README
5. Releases