Skip to content
sammwyyPublic

Repository files navigation

Coconut

A focused, modern desktop shell for Wayland.

Warning

Coconut is under active development and is not yet intended for daily use or distribution packaging.

Coconut puts common desktop actions within immediate reach: launch an application, move between running windows, control media, or adjust your system without losing focus. Its top statusbar and centered dockbar are designed to stay calm, responsive, and consistent.

What it includes

  • A configurable statusbar and dockbar, with widgets usable in either or both
  • Island groups for visually separated widget sections
  • A centered running-app dockbar with active-window feedback
  • Application browsing, category navigation, and search
  • A reusable Pinned apps widget with contextual pinning and .desktop file drag and drop
  • Now-playing information with playback controls
  • Clock and weather widgets
  • A permission-controlled clipboard history service and optional history widget
  • A control center for network, brightness, volume, Bluetooth, battery, and power profiles
  • Floating volume and brightness indicators with configurable placement
  • D-Bus desktop notifications with icons, actions, replacement and expiration
  • Dedicated panels for the same system controls when you need more detail
  • Native desktop integrations for Blair and KDE Wayland, plus Windows 10

Applications

Run the desktop and its local portal services without installing:

./scripts/dev.sh --build  # Build into .build/ without UPX, then start Blair and Coconut.
./scripts/dev.sh          # Use the existing staged binaries.

The development session uses its own D-Bus bus and XDG directories. See the shell development guide for dependencies, Blair selection, logs and running additional apps in that session.

Use make dev, make build, or make test as shortcuts to the repository scripts.

Command Purpose
coconut Start the shell.
coconut settings Open Coconut Settings.
coconut bg Start the standalone background renderer.
coconut-settings Open Coconut Settings directly.
coconut-bg Render the desktop background directly.
coconut terminal Start the terminal emulator.
cedit [FILE ...] Open CEdit, the text, code, Markdown and byte editor.
ccalc [--scientific] Open Calculator with standard/scientific modes and unit conversions.
cviewer [IMAGE ...] Open Image Viewer with zoom, pan, rotation, temporary color adjustments and metadata.
coconut-screenshots Take a screenshot and annotate it: drag to select, draw, blur, erase, then copy or save. --screen captures headlessly, --save-as asks where to save.
coconut-permission-portal --service Run the permission service that stores per-application decisions and shows consent prompts.
coconut-clipboard Run the session clipboard history service and its permission-controlled D-Bus API.
cterm --settings Open Terminal Settings.
coconut files Start the file manager.
cfiles --settings Open File Explorer settings.
cfiles --portal Run the FileChooser portal backend.
coconut monitor Start the system monitor.
coconut media-player Start the media player.
cplayer --settings Open Media Player settings.
coconut-greeter Start the Alphin login screen.
coconut-greeter --preview Preview the login screen with sample accounts, without Alphin or Blair.
coconut-greeter --preview-multiple Preview the account switcher and session dropdown.

coconut now contains only the shell and transparent desktop-icon layer. coconut-bg renders the desktop background as an independent session daemon; the installed session profile launches both automatically — startcoconut (the greeter-facing bootstrapper, which starts the compositor selected at install time) hands off to coconut-session, which spawns coconut-bg, coconut-clipboard and then the shell. Future session components get added there, not to the shell. When running pieces by hand instead of through the session, start coconut-bg alongside coconut yourself. It renders one bottom layer surface per output, follows output size/scale changes, and stores its independent configuration in ~/.config/coconut/bg.toml (or the equivalent XDG configuration directory). Coconut Settings updates it live. Image mode supports Full (aspect-preserving fill), Centered, Stretched, and Mosaic placement. The background can also be a solid color, a two-color linear gradient, or a built-in GPU shader animated through frame callbacks. Each shader can be tuned independently for animation speed, target frame rate (1-60 fps) and palette colors under [shaders.<name>]. When GPU rendering is unavailable, shader mode falls back to the solid color.

Clipboard history is configured in Settings → Privacy → Clipboard. Enable its optional icon in Settings → Desktop → Islands. History stays in memory, with configurable size and expiration, and supports text on compositors with wlr-data-control, including Blair. See the service/API guide for permissions and configuration, and the widget guide.

Notifications and status updates

Open Settings → Desktop → Notifications & popups to set the screen edge, alignment, edge offset and duration separately for application notifications and volume/brightness indicators. Coconut also shows its own notifications when Wi-Fi or Bluetooth connects, disconnects, or is turned on/off. These use the notification preferences directly and work without the D-Bus notification service. Changes apply immediately. The same options are stored in [notifications] and [status_updates] in shell.toml: enabled, edge (top/bottom), align (left/center/right), offset (in logical pixels) and duration_ms.

On Linux, Coconut provides org.freedesktop.Notifications on the session bus when no other notification service owns that name. Test it with notify-send -i dialog-information "Coconut" "Notifications are ready". Application timeouts take precedence over the configured default; critical notifications stay visible until dismissed unless the application sets a timeout.

Platform notes

Coconut desktop themes share resolved colors, typography and geometry across the shell, CreamUI, GTK and Qt. Packages can use automatic adapters or native overrides/templates. See THEMES.md for package authoring, dynamic variants/accents, session integration and compatibility details.

On Linux, Coconut integrates with Blair through its org.blair.Compositor1 D-Bus API for window management and layer-shell surfaces. KDE Wayland services are supported where available.

On Windows 10, Coconut uses native APIs and PowerShell for window discovery, application launching, media sessions, volume, power, display brightness, network, and Bluetooth. Unavailable hardware features fall back gracefully.

When Weather is enabled, Coconut resolves the configured location on first use, stores its coordinates in the user profile, and retrieves forecasts directly from MET Norway. Disabling the widget prevents new weather requests.

Development

See the development documentation:

Run ./scripts/setup.sh --dry-run to inspect native dependencies, then ./scripts/setup.sh to install them.

For a local development session:

cargo run -p coconut-background &
cargo run -p coconut-shell

Launch the settings application separately with:

cargo run -p coconut-settings

Releases

Sponsor this project

Contributors

Languages