lambdock

tools/record-demo/ records a scripted showcase of every feature and every built-in theme in a nested niri session, then encodes it as a GIF under 15 MiB:

./tools/record-demo/record-demo.sh
# output: tools/record-demo/out/lambdock-demo.gif

The storyboard covers auto-hide, fish-eye magnification, launching, the window popover, the right-click menu, the About window, a live Guile REPL session, theme hot-swapping and taskbar mode. See tools/record-demo/README.org for prerequisites and options.

• People who miss the macOS Dock – and want it on a compositor where windows are told who is in charge. Fish-eye magnification, a glassy capsule, running indicators, window titles: all there, none of it proprietary.
• Wayland minimalists who keep a compositor, a terminal, and a small pile of well-chosen tools – and want a dock that does not drag an X11 toolkit, a configuration daemon, or a GNOME session along with it.
• Ricers and theme collectors, who will want the thirteen built-in themes, the CSS override hook, and the ability to restyle anything on the fly.
• Lisp people, who would rather write eleven lines of Scheme than file a feature request, and who expect a REPL inside the program they are running.
• Free software lovers who want the dock to be theirs: GPL-3.0-or-later, no account, no telemetry, no phone-home.

lambdock is powered by: C and GTK4 / GSK for the graphics core and the frame-clock-driven animations, gtk4-layer-shell for the Wayland surface protocol, GNU Guile 3.0 embedded in-process through libguile, Meson and Ninja for the build, GNU Guix and Nix for hermetic, reproducible environments, Maak for the task runner, GNU gettext for translations, and Emacs (with Geiser) as the recommended way to talk to the running dock.

There is no scripting bridge to a separate process, no D-Bus daemon in the middle, and no configuration format to learn in JSON or YAML: the interpreter is inside the dock, and the dock is the interpreter's playground.

New to the Wayland, GTK or Lisp stack? Every piece of jargon in this document is one line away. Skim it now, or come back when a word bites.

lambdock is a GNU/Linux first utility. It uses gtk4-layer-shell to render, position itself, and behave like a dock. That means it works well in Wayland compositors that implement the wlr-layer-shell-unstable-v1 protocol, including:

• Smithay-based compositors: Niri, COSMIC Desktop
• wlroots-based compositors: wlroots powers Sway, Hyprland, River, Wayfire
• KDE Plasma (Wayland session)
• Mir-based compositors

Note: GNOME (Mutter) is currently not supported, because it does not implement the protocol.

On the 30th of July 2026, I had a revelation and set out to build lambdock: a Wayland-native desktop dock that wouldn't just replicate the macOS or Cairo-Dock experience, but would transcend it with full runtime inspectability, hackability, and Lisp enlightenment.

I find GTK to be the very best UI toolkit for GNU/Linux and other platforms, anno 2026. So for me that choice was pretty clear, even if I also toyed with Qt and others, but GTK always came on top. After the wreckage of many PoCs and while reading some HackerNews in bed, a thought crossed my mind, and suddenly, absolute clarity!

Why not use idiomatic modern GTK4, in the language that it's written in. Oh wait, that language, C, has libguile.h, a great library inter-operability with Lisp (GNU Guile Scheme), allowing bi-directional bindings and communication. Why not go down this rabbit hole, which might at the same time teach me more about my favourite language (GNU Guile) and allow me a frictionless setup with GTK and native super performance.

I therefore designed lambdock in my mind, in bed, much inspired by Emacs. A powerful, small C core that powers the program, rendering, graphics and low level details, and an embedded GNU Guile Scheme engine that at runtime is the heart and brain of the whole thing. This architecture uniquely delivers interactive socket REPL control, Lisp metaprogramming macros, dynamic multi-dock spawning, native Wayland foreign-toplevel window tracking, and frame-clock-driven hover animations.

lambdock is a story of resilience in many ways, as I cannot even remember how many attempts I made at building a dock (in different ways). Little did I know how many paradigms, ideas and PoCs would collapse before my vision became tangible reality.

• Left click a pinned launcher: the app starts. If the app is already running, its window is focused and raised instead of a second instance being spawned.
• Left click a running app with several windows: the window popover opens (see below), so you pick which window you meant.
• Right click a running app with several windows: the same popover, useful when you want to close one instance without stealing focus.

When an app has one window, clicking it just focuses it. When it has more than one, lambdock opens a floating GTK popover built from what the compositor told it:

• a header with the application's name, then a separator;
• one row per open window, with the window title as a button (ellipsized at 30 characters) to focus that instance, and a close button next to it;
• New Instance, to start another instance of the application, when the item has an exec command;
• Close All Windows, shown only when more than one window is open;
• Launch Application, when an app is in the dock but nothing is running yet.

The protocol behind that list is described in Wayland Toplevel Tracking & Popovers.

With dock-auto-hide? enabled, the dock slides off the screen edge with a 250 ms cubic ease-out transition and comes back when the pointer reaches a two-pixel strip at that edge. It waits a moment before hiding again (400 ms after a popover closes, 600 ms after the pointer leaves) so that a hasty mouse movement does not chase the dock away. The hide/show is driven by gtk_widget_add_tick_callback, so it stays in step with your display's refresh rate, 60 Hz or 120 Hz or whatever your compositor gives it.

Parking the pointer on that edge keeps the dock out, and leaving does not need any particular gesture: the strip is the last two pixels of the screen, so a pointer resting there is on the dock when it is in and a hair past it when it is out. The dock ignores the crossings its own slide produces – a window that moves under a still pointer makes a compositor report the pointer leaving a surface it is still on – and a leave only counts once the pointer has actually moved since it arrived. That is what used to make it bounce in and out for as long as the pointer stayed put.

A stack is a dock icon that opens the contents of a directory – the macOS Downloads stack, except that you decide which folder it shows. Add one with stack-item:

(define dock-items
  (list (stack-item #:name "Downloads"   ; what the header and tooltip say
                    #:path "~/Downloads" ; the folder to show ("~" is expanded)
                    #:view-mode 'grid)   ; 'grid, 'list or 'fan
        (stack-item #:name "Screenshots"
                    #:path "~/Pictures/Screenshots"
                    #:icon "folder-pictures"
                    #:view-mode 'fan)))

Clicking the icon opens a popover with the folder's contents (hidden dot-files are skipped, folders come first, then names; at most 300 entries are listed so a gigantic directory cannot lock the UI up):

• grid: a flow box of tiles, four to seven per row, the default;
• list: one row per entry with its content-type icon, close to a file manager's list view;
• fan: an arc of tilted cards, macOS style. GTK cannot rotate child widgets, so this view paints its cards itself (rounded rectangle, preview, name) and hit-tests the click by rotating the pointer back into each card's frame. The centre card stands upright, the outer ones lean and sink away from it, and the card under the pointer comes to the front with its full name printed above the fan. A fan with more cards than fit scrolls sideways instead of shrinking every card into a sliver; it shows at most 16 cards and a note says so, since the folder itself is one click away in the header.

In every view, an image file shows a live, centre-cropped thumbnail of its contents instead of a generic type icon. Thumbnails are decoded in the background, one at a time, so opening a folder of large photos does not stall the dock; closing the popover stops the remaining work.

The header carries the folder name, how many items are inside and a button to open the folder in your file manager. Clicking any entry opens it and dismisses the popover, so the file manager or application is not left underneath the panel. Right-clicking the stack switches the view mode (the choice is remembered per stack) or opens the folder. Changing it from a config file is the same thing: (stack-item #:view-mode 'list ...).

Empty folders are not an error: the popover says "This folder is empty".

One item puts every installed application one click (and half a keystroke) away:

(define dock-items
  (list (launchpad-item)                          ; name: "Launchpad"
        (launchpad-item #:name "Apps"             ; or your own label
                        #:icon "view-app-grid-symbolic")))

Clicking it covers the screen with a layer-shell overlay: a search field, and below it every application found in the XDG application directories, sorted by name and shown as icon tiles. Type to filter (the name and the command line are both searched), press Enter on a result… nothing else: click a tile to launch it, press Escape, click the X in the top right corner or click the backdrop to go back to whatever you were doing.

Its appearance follows the settings of the dock that opened it:

(define dock-launchpad-icon-size 80)
(define dock-launchpad-columns 6)
(define dock-launchpad-blur? #t)

A real blur of what is behind the launchpad is the compositor's job, and almost every Wayland compositor can do it for translucent layer surfaces. KWin blurs them by default. On niri, add a layer rule matching the launchpad's namespace:

layer-rule {
  match namespace="^lambdock-launchpad$"
  background-effect {
    blur true
  }
}

Without such a rule the option still gives a lighter, tinted glass backdrop, just not a blurred one.

Under the hood it parses the .desktop entries with GKeyFile (locale aware Name, Exec with the %f / %U / %i field codes stripped, Icon), skips what the user or the distribution hid (Hidden=true, NoDisplay=true) and deduplicates by desktop file name, so a Flatpak export overrides the identical system entry. The list is rescanned every time the launchpad opens, so an app you just installed is there without restarting the dock.

One item puts the desktop trash on the dock:

(define dock-items
  (list (trash-item)                        ; name: "Trash"
        (trash-item #:name "Bin"            ; or your own label
                    #:icon "user-trash-symbolic")))

The icon follows the trash: the configured icon while it is empty, and the icon theme's user-trash-full (or user-trash-full-symbolic, when the configured icon is a symbolic one) once it holds anything, with the number of items in the tooltip. A custom theme icon used as #:icon is the empty-state artwork, and the full state swaps in the theme's full icon; an icon given as a file or resource is kept as it is in both states (the tooltip still counts the items). The item re-counts every two seconds, so a file deleted from any other program shows up without restarting the dock.

• Left click opens the trash in your file manager: trash:/// when your desktop provides a handler for it, then the folder-handling file manager with that URI (the usual case, because most distributions never register an x-scheme-handler/trash), then the home trash folder as a last resort.
• Right click shows how many items are in the trash, with Open Trash and Empty Trash (disabled when there is nothing to empty).
• Drop files or folders on it moves them to the trash. Folders go with everything inside them, and a name that is already taken in the trash gets a fresh one instead of overwriting anything.

None of this is specific to one desktop. The item reads and writes the trash the way the freedesktop.org Trash specification defines it: the home trash lives in $XDG_DATA_HOME/Trash (normally ~/.local/share/Trash), and every mounted volume can have its own under $topdir/.Trash/$uid or $topdir/.Trash-$uid. The count and the empty action cover all of them, with no gio command, GVfs or GNOME/KDE helper involved, which is what makes the icon behave the same across GNOME, KDE, Xfce, Cinnamon, MATE and the rest. Dropped files are handed to GIO's g_file_trash() – the library call, not a desktop service – which implements that same specification: it picks the right volume's trash, writes the *.trashinfo entry and resolves name collisions. Emptying and dropping both run off the main loop, so a trash with thousands of files does not freeze the dock while it is cleared or filled.

The dock is not a fixed row of icons: it is something you arrange.

• Reorder: drag any icon along the dock and drop it where you want it. The item is inserted on the side of the icon you dropped over.
• Remove: drag an icon out of the dock and let go anywhere that is not the dock (the desktop, a window, empty space). The icon goes away; nothing is uninstalled, the app just leaves the dock.
• Add an application: drag a .desktop file from your file manager onto the dock and it becomes a launcher, using the entry's own name, icon and command.
• Add a stack: drag a folder onto the dock and it becomes a stack showing that folder.

There are also two menu items for the impatient: right-click any item and pick Remove from Dock, and right-click a stack to change its view mode.

Where do the changes go? Your settings file stays the source of truth, so drag-and-drop writes a small override file next to the dock's state instead of rewriting (or fighting with) a configuration that other tools may generate:

;; ~/.local/state/lambdock/layout-settings.scm  (or $XDG_STATE_HOME/lambdock/)
;; Written automatically by drag and drop in the dock.
;; Delete this file to go back to the items in your settings file.
((order "app:Firefox" "app:Terminal" "stack:Downloads")
 (removed "app:Files")
 (added ("app" "Slack" "slack" "slack --start" "")
        ("stack" "Shots" "folder" "/home/you/Pictures/Shots" "grid"))
 (views ("stack:Downloads" . list)))

It records four independent things: the item order, the items you dragged out, the items you dragged in, and per-stack view modes. On the next start they are replayed on top of whatever the settings file says, so regenerating your configuration keeps working: new items appear, the ones you removed stay removed, and the stack you switched to a fan stays a fan. Delete the file (or call (dock-layout-reset! path) from the REPL) to go back to the pure configuration.

Item identity is kind:name (the Scheme procedure dock-item-key), which is why the file is readable and why two items with the same name and kind are treated as the same item. Separators have no stable name, so they are not listed at all: they keep their place between their neighbours.

A dock is easy to think of as a mouse-first object. It does not have to be: every pointer action on the dock has a keyboard equivalent, and every icon says out loud what it is.

(define dock-reduce-motion? #t)

The project requires the following C and Scheme dependencies:

• GTK 4 (gtk4)
• GTK4 Layer Shell (gtk4-layer-shell)
• GNU Guile 3.0 (guile-3.0)
• Wayland development files (libwayland-dev, wayland-protocols, wlr-protocols)
• Meson & Ninja, and pkg-config
• GNU gettext (for building the translations)

lambdock is officially distributed via the Guix package manager. You can also use Guix locally and to develop on this project. See also the run maak task.

Enter a development container with all required dependencies:

guix time-machine --channels=channels.scm -- shell -m manifest.scm

Also, a guix.scm is provided to run lambdock fully with Guix.

guix time-machine --channels=channels.scm -- shell -f guix.scm -- lambdock

lambdock is officially part of NixPkgs, and can also easily be used with Nix (flakes) too, where nixpkgs supplies the packages. See also the nix-build maak task.

nix --extra-experimental-features 'nix-command flakes' build
nix --extra-experimental-features 'nix-command flakes' run .#

The plain path, with Meson and Ninja from your own distribution:

# Setup build directory
meson setup build

# Compile project
meson compile -C build

# Run locally
./build/lambdock

On Arch Linux, ensure the dev build tools are installed: sudo pacman -S --needed base-devel

Then go to packaging/arch and run makepkg -sic to install lambdock. See also the arch-build maak task.

lambdock is packaged on openSUSE's OBS and you can download it from there, or add the Zypper repo. The packages it produces are RPMs, which also fit Fedora and RHEL.

To build the RPM locally on Tumbleweed, install the packaging tools and setup the developer directories. See also the rpm-build maak task.

sudo zypper install rpm-build  rpmdevtools  osc  rpmlint
rpmdev-setuptree

Create the source tarball. You can do this with git archive (or also simply copying the directory and manually tar -cvzf). This tarball should be placed in ~/rpmbuild/SOURCES/

Copy the spec and build the RPM:

cp packaging/opensuse/lambdock.spec ~/rpmbuild/SPECS/
rpmbuild -ba ~/rpmbuild/SPECS/lambdock.spec

Then you should get the RPM files successfully generated:

~/rpmbuild/RPMS/x86_64/lambdock-0.13.2-0.x86_64.rpm
~/rpmbuild/SRPMS/lambdock-0.13.2-0.src.rpm

Test the resulting package. Install it:

sudo zypper install ~/rpmbuild/RPMS/x86_64/lambdock-0.13.2-0.x86_64.rpm

Then you can run lambdock.

Install the required build tools and compile the package on Debian or Ubuntu (whose package manager is APT). See also the deb-build maak task.

# Install build dependencies on your Debian/Ubuntu system
sudo apt update
sudo apt install build-essential debhelper devscripts meson ninja-build \
                 pkg-config libgtk-4-dev libgtk4-layer-shell-dev \
                 guile-3.0-dev libwayland-dev wayland-protocols

# Build the package (unsigned binary build)
# you will need to copy the packaging/debian/* to root of repo or equivalent approach
debuild -b -uc -us

You can also use lambdock as a Flatpak (experimental). Ensure to give it the correct permissions (using something like Flatseal).

flatpak install --user flathub org.gnome.Platform//50 org.gnome.Sdk//50
flatpak-builder --install --user build-dir packaging/flatpak/org.jointhefreeworld.lambdock.yaml --force-clean
flatpak run org.jointhefreeworld.lambdock

lambdock is also available as a container, on Podman or Docker. You can pull its images from DockerHub or build it yourself. It's also recommended to see maak.scm for more details on how to use it that way.

In a nutshell, you can run lambdock easily this way, provided you mount necessary devices and files.

podman run -d --rm --name lambdock \
       --network host \
       --userns=keep-id --ipc=host \
       --device /dev/dri \
       -e XDG_RUNTIME_DIR=/run/user/$(id -u) \
       -e WAYLAND_DISPLAY="$WAYLAND_DISPLAY" \
       -e HOME="$HOME" \
       -v /run/user/$(id -u):/run/user/$(id -u):z \
       -v "$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/run/user/$(id -u)/$WAYLAND_DISPLAY:ro" \
       -v "$HOME:$HOME" \
       -v /usr/share/icons:/usr/share/icons:ro \
       -v /usr/share/applications:/usr/share/applications:ro \
       lambdock:latest

;; Enable/disable smooth edge sliding auto-hide
(define dock-auto-hide? #t)

;; Show dock when last window was closed
(define dock-show-when-clear? #t)

;; Dock edge attachment: 'bottom | 'top | 'left | 'right
(define dock-position 'bottom)

;; Default icon pixel resolution
(define dock-icon-size 48)

;; Themes:
;; 'vanilla | 'vanilla-light | 'snow-leopard | 'snow-leopard-dark
;; | 'solarized-light | 'nature | 'unity
;; | 'macos-big-sur | 'macos-ventura | 'macos-mavericks
;; | 'windows-xp | 'windows-10 | 'windows-11
;; | 'none
(define dock-theme 'vanilla)

;; 'all         -> Render dock on every connected monitor
;; "DP-1"        -> Target specific monitor output connector
;; 'default     -> Default compositor monitor assignment
(define dock-monitor 'all)

;; List of app ids to never show in the dock
(define dock-exclude-apps '())

;; Whether to enable the lambdock REPL
(define dock-enable-repl? #f)

;; Location for the REPL unix socket
(define dock-repl-socket-path
  "/tmp/lambdock-repl.sock")

;; Whether to animate dock items when hovering on them with the mouse
(define dock-hover-animate? #t)

;; Whether to keep track of open apps and windows and show indicators and popovers
(define dock-track-windows? #t)

;; Layout mode: 'dock (floating capsule) | 'taskbar (full-width bar)
(define dock-mode 'dock)

;; Show the focused window's title next to running app icons (Windows XP-style)
(define dock-show-window-titles? #f)

;; The dock's glass shelf is described by plain numbers. Everything below has
;; a sensible default (the flat capsule), so write only what you want to move.
(define dock-shelf-tilt 0)       ; tilt of the shelf plane, degrees (0 = flat)
(define dock-shelf-margin 24)    ; glass on the inner side of the icons, px
(define dock-shelf-front 0)      ; glass on the outer side (front face), px
(define dock-reflection 0)       ; reflection band / icon size (0 = off)
;; (define dock-shelf-perspective 400)   ; projection distance for the tilt
;; (define dock-reflection-intensity 0.55)
;; (define dock-reflection-blur 0.05)

;; Application launchers list
(define dock-items
  (list (preset-launcher 'alacritty)
        (preset-launcher 'google-chrome-flatpak)
        (app-item #:name "Spotify"
                  #:exec "flatpak run com.spotify.Client"
                  #:icon "com.spotify.Client")
        (app-item #:name "Files"
                  #:exec "nautilus -w"
                  #:icon (preset-icon 'nautilus))
        (separator-item)
        (app-item #:name "Emacs"
                  #:exec "emacsclient -c"
                  #:icon "emacs")))

Every option below is a top-level definition in your settings*.scm. Writing dock-foo or just foo both work; the defaults are what you get when you say nothing at all.

The same names are also the keyword arguments of the programmatic (configure-dock! ...) procedure, which is what the loader calls after reading your file and what you can call yourself from the REPL:

(configure-dock!
 #:position 'right
 #:theme 'windows-11
 #:icon-size 40
 #:mode 'taskbar
 #:items (preset-launchers-for 'alacritty 'emacs)
 #:auto-hide? #t
 #:enable-repl? #t
 #:repl-socket-path "/tmp/lambdock-repl.sock"
 ;; Shelf parameters (defaults shown): flat capsule
 #:shelf-tilt 0
 #:shelf-perspective 400
 #:shelf-margin 24
 #:shelf-front 0
 #:reflection 0
 #:reflection-intensity 0.55
 #:reflection-blur 0.05
 ;; Launchpad
 #:launchpad-icon-size 64
 #:launchpad-columns 0
 #:launchpad-blur? #f
 ;; Accessibility
 #:reduce-motion? #f)

lambdock provides a small Lisp DSL for defining your dock, based on items and presets.

(list (ram-item)              ; a ring that fills with the used RAM
      (cpu-item)              ; a ring for the CPU load
      (cpu-temp-item)         ; a ring filling from 0 to 100 °C
      (cpu-item #:meter? #f)) ; ... and the old "CPU 42%" text item

(define (get-swap-used)
  (catch #t
         (lambda ()
           (let* ((line (call-with-input-file "/proc/swaps" read-line))
                  (rest (call-with-input-file "/proc/swaps"
                          (lambda (port)
                            (read-line port)
                            (read-line port)))))
             (if rest (string->number (cadr (string-split rest #\space))) #f)))
         (lambda _ #f)))

(define dock-items
  (list (dynamic-item #:name "Swap"
                      #:exec "alacritty -e 'btop'"
                      #:poll-fn get-swap-used
                      #:poll-interval 5000
                      #:meter? #t
                      #:unit "%"
                      #:max 4096)))       ; 4 GiB of swap fills the ring

;; A widget that shows how many days remain in the year
(define (get-days-left)
  (let* ((now (localtime (current-time)))
         (yday (tm:yday now))
         (year (tm:year now))
         (leap? (and (= 0 (modulo year 4))
                     (or (not (= 0 (modulo year 100)))
                         (= 0 (modulo year 400)))))
         (total (if leap? 366 365)))
    (format #f "~a days left" (- total yday))))

(define dock-items
  (list (dynamic-item #:name "Year"
                      #:icon "x-office-calendar"
                      #:exec "gnome-calendar"
                      #:poll-fn get-days-left
                      #:poll-interval 60000
                      #:hover-animate? #f)))

;; Alternatively, construct dock-items procedurally using list operations:
(define dock-items
  (append (preset-launchers-for 'alacritty
                                'google-chrome-flatpak
                                'spotify
                                'nautilus
                                'nyxt)
          (list (separator-item))
          (preset-launchers-for 'emacs
                                'intellij-flatpak
                                'bruno)
          (list (separator-item))
          (preset-launchers-for 'btop
                                'pavucontrol
                                'onepassword)))

(define dock-auto-hide? #t)

(define dock-show-when-clear? #t)

(define dock-position 'bottom)

(define dock-icon-size 48)

(define dock-theme 'vanilla-light)

(define dock-monitor 'all)

(define dock-exclude-apps '("warp-taskbar"))

(define dock-enable-repl? #t)

(define dock-hover-animate? #t)

(define dock-track-windows? #t)

(define dock-items
  (append
   (preset-launchers-for
    'alacritty
    'google-chrome
    'spotify-flatpak
    'nautilus
    'nyxt-flatpak
    'gnome-calendar
    'gnome-calculator
    'zapzap-flatpak)
   (list (separator-item))
   (preset-launchers-for 'emacs 'intellij 'bruno-flatpak)
   (list (separator-item))
   (preset-launchers-for 'btop 'pavucontrol 'onepassword)
   (list (separator-item))
   (preset-launchers-for 'ram 'cpu 'cpu-temp 'battery)))

Since lambdock configuration files are evaluated directly as standard GNU Guile Scheme, you can run any arbitrary Guile code ‼️✨ right inside any ~/.config/lambdock/settings*.scm file. You can import modules, define helper functions, query system state (like time, hostnames, or installed packages), do API calls, and dynamically build your configuration.

(use-modules (ice-9 popen)
             (ice-9 rdelim)
             (srfi srfi-19)
             (srfi srfi-1))

;; Helper to run a shell command and return its output as a clean string
(define (sh-output cmd)
  (let* ((port (open-input-pipe cmd))
         (output (read-line port)))
    (close-pipe port)
    (if (eof-object? output) "" output)))

;; Enable auto-hide only on a specific hostname (e.g., laptop setup)
(define dock-auto-hide?
  (string=? (string-trim-both (sh-output "hostname")) "thinkpad"))

;; Pick the dock edge from the current hour: a sunny-side-up desk by day...
(define dock-position
  (if (< (date-hour (current-date)) 12) 'top 'bottom))

That flexibility is the point: a dock that reads your machine, instead of a dock that only reads a file.

lambdock features built-in multi-dock orchestration. Rather than being limited to a single dock bar, you can run multiple independent docks simultaneously across different screen edges or monitors.

• Automatic Directory Monitoring: lambdock watches ~/.config/lambdock/ for files matching settings.scm or settings-*.scm (e.g., settings-left.scm, settings-bottom.scm).
• Isolated State: Each configuration file defines its own isolated LambdockState, position (dock-position), theme (dock-theme), monitor targets (dock-monitor), and item launcher layout (dock-items).
• Dynamic Spawning: Creating a new settings-2.scm file instantly spawns a new dock bar on screen.
• Dynamic Hot-Reloading: Editing any settings-*.scm file hot-reloads that specific dock instance without flickering or restarting other running instances.
• Dynamic Destruction: Deleting a settings-*.scm file safely tears down and destroys its corresponding dock window, removing Wayland handles and GTK widgets without crashing the application.
• Monitor Hotplug: Docks survive monitors coming and going; layer-shell is unbound from an output before it is disconnected rather than after.

Also, here is a small demo of hot-reload:

Right-click the dock and choose Preferences… to open a GTK4 settings window. It covers the settings people reach for most often, grouped the way the settings file groups them:

• Behaviour: auto-hide, show when no windows, hover magnification, window tracking, window titles, and dock vs taskbar mode.
• Accessibility: reduce motion (see Keyboard and accessibility).
• Layout & material: icon size, item spacing, capsule padding, screen edge and theme.
• Glass shelf: icon overhang, front glass, reflection height/intensity/blur, keystone flare, tilt and perspective.

Every control applies immediately through the same set-dock-*! setters the REPL uses, so the dock redraws as you drag a slider (the apply is debounced so a drag is one edit, not one per pixel). Each slider also has a spin button beside it for typing an exact value – a 53 px icon, a 0.07 blur – and the window closes with Escape.

Your settings file is never modified. GUI changes are written to a separate override file, next to the dock's drag-and-drop layout overrides:

${XDG_STATE_HOME:-~/.local/state}/lambdock/preferences-<settings-stem>.scm

The loader layers that file on top of settings.scm, which is what lets a generated settings file (an OS image, a dotfiles generator) be regenerated without losing the choices made in the window. Deleting the override file – or pressing Reset in the window – restores the settings file exactly.

When several docks run (see multi-config), the menu item carries the settings path of the dock it was opened on, so the window edits that dock and not another one.

lambdock ships with pre-baked themes embedded via build defines, and every one of them is a CSS file you are free to read, copy and argue with.

And here is the same dock wearing WhiteSur icons, over a Niri session:

You can override any GTK style class on the fly without re-compiling C sources. lambdock automatically monitors and loads user styles from:

~/.config/lambdock/styles.css

User styles are loaded with GTK_STYLE_PROVIDER_PRIORITY_USER priority, taking precedence over default app themes.

Make sure you use GTK CSS, not "web-browser CSS". For understanding better what is available and what you can override, you should look at the theme definitions at ./resources/css.

An example override of a theme could look like this:

/* Custom user tweaks in ~/.config/lambdock/styles.css */

.lambdock-window {
    background-image: linear-gradient(180deg, rgba(255, 0, 20, 0.85) 0%, rgba(5, 5, 8, 0.95) 100%);
    border: 1px solid rgba(255, 0, 0, 0.3);
    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.8);
}

Save the file and the change is applied live, just like the Scheme settings.

dock-mode switches between the default floating, content-hugging dock capsule ('dock) and a full-width bar anchored edge-to-edge ('taskbar). In taskbar mode the layer-shell surface is stretched across the monitor, the capsule is squared off, and icons are laid out from the start of the bar.

;; 'dock (default) -> floating capsule sized to its icons
;; 'taskbar        -> full-width (or full-height) bar spanning the monitor
(define dock-mode 'taskbar)

On top of that, dock-show-window-titles? renders the focused window's title next to each running app's icon, like the classic Windows XP taskbar. Pinned apps that are not running stay icon-only, and titles are ellipsized when they get long.

;; Show window titles on running app items (Windows XP-style taskbar buttons)
(define dock-show-window-titles? #t)

Combine either mode with any theme. The 'windows-* and 'macos-* themes include dedicated taskbar styling, and a generic taskbar modifier squares off the capsule and styles the title labels when needed.

Three numbers decide how the row of icons looks:

`dock-capsule-padding` is the end padding, the one that decides how much glass sticks out past the icons on either side. The OS X dock keeps it around ~0.25 × the icon size (12px for 50px icons); with the theme's own button padding on top, 8 at 48px icons lands there.

The visible gap is dock-item-spacing plus whatever the active theme gives its buttons as padding and margins, so it is the knob for the rhythm while the theme keeps control of the clickable area. As a reference, the OS X dock keeps its icons about 0.3 × their size apart: 50px icons with 15px between them. With 48px icons and ~dock-item-spacing 4 that is a 14–16px gap: the 'vanilla and 'macos-mavericks themes keep no horizontal button margin, so their 6px / 10px of padding plus the setting land right there.

;; packed tight, icons almost touching
(define dock-item-spacing 0)

;; the default: the OS X rhythm
(define dock-item-spacing 4)

;; airy, for a big or wall-mounted screen
(define dock-item-spacing 16)

;; end padding: the OS X look (12px of glass past the first and last icon)
(define dock-capsule-padding 8)   ; 8 here + ~4px of theme button padding

;; flush: icons right up against the capsule's ends
(define dock-capsule-padding 0)

Spacing and padding are applied live: change them from the REPL with (set-dock-item-spacing! 8) / (set-dock-capsule-padding! 8) or in settings.scm and the row re-lays out immediately. It is also what makes a dock of many items scroll sooner or later, since the items have to fit on screen either way.

lambdock has one dock implementation. Its shape is described by plain numbers, so a flat capsule, a frosted plinth, a subtle 3D shelf and the Mac OS X 10.9 Mavericks dock are the same code with different values. There are no modes and no presets: every knob is independent, and all of them default to the classic flat capsule, so a dock that says nothing looks exactly like it always did.

 ──────────────────────────────────────────────  inner edge of the glass
                    ↑
      dock-shelf-margin (glass above the icons; make it negative and
                    ↓   the icons overhang past this line)
       [icon]      [icon]      [icon]
 ──────────────────────────────────────────────  the icons' bottom
      mirrored icons, fading out                  ← dock-shelf-front
 ──────────────────────────────────────────────  the screen edge

band    = round(dock-icon-size * dock-reflection)
outer   = max(dock-shelf-front, band)     ; glass in front of the icons
capsule = dock-icon-size + dock-shelf-margin + outer
;; and, across the dock:
bottom edge = top edge + 2 * dock-shelf-flare

(define dock-shelf-margin 18)   ; glass above the icons
(define dock-shelf-front 18)    ; glass below them
(define dock-reflection 0)      ; no mirror

(define dock-shelf-tilt 4)          ; a hint of perspective
(define dock-shelf-perspective 900) ; ... with a long camera distance
(define dock-shelf-margin 8)
(define dock-shelf-front 12)
(define dock-reflection 0.25)
(define dock-reflection-intensity 0.35)

(define dock-theme 'macos-mavericks)   ; platinum slab material

(define dock-icon-size 48)
(define dock-shelf-margin -18)         ; icons overhang by half an icon
(define dock-shelf-front 24)           ; slab = 48px = exactly one icon
(define dock-reflection 0.30)          ; mirror band inside that front glass
(define dock-reflection-intensity 0.70)
(define dock-reflection-blur 0.03)
(define dock-shelf-flare 24)           ; wider at the screen edge: the 3D shelf
(define dock-capsule-padding 8)        ; ~12px of glass past the end icons
;; tilt stays 0 - the real dock is orthographic, the flare does the keystone
(define dock-shelf-tilt 0)

;; ... and the same slab in smoked graphite
(define dock-theme 'macos-mavericks-dark)

(define dock-theme 'vanilla)
(define dock-shelf-margin -18)
(define dock-shelf-front 16)
(define dock-reflection 0.35)
(define dock-reflection-intensity 0.75)  ; brighter mirror on dark glass
(define dock-reflection-blur 0.06)

/* ~/.config/lambdock/styles.css */
.lambdock-window.shelf-mode {
  background-image: linear-gradient(
    0deg,
    rgba(255, 255, 255, 0.55) 0px,
    rgba(96, 108, 130, 0.95) 2px,
    rgba(44, 52, 70, 0.95) 7px,
    rgba(60, 70, 90, 0.92) 8px,
    rgba(24, 29, 40, 0.90) 100%
  );
  border-top: 1px solid rgba(255, 255, 255, 0.28);
  border-bottom: 1px solid rgba(255, 255, 255, 0.16);
  box-shadow: 0 -8px 22px rgba(0, 0, 0, 0.45),
              inset 0 1px 0 rgba(255, 255, 255, 0.22);
}

(define dock-shelf-margin -34)   ; a lot of overhang
(define dock-shelf-front 26)
(define dock-reflection 0.45)    ; a tall mirror in the front face
(define dock-reflection-blur 0.04)

(define dock-reflection 0.4)     ; no margin/front changes at all

(define dock-theme 'vanilla)
(define dock-shelf-front 14)     ; room for the mirror under the icons
(define dock-reflection 0.3)

/* ~/.config/lambdock/styles.css - the "shelf" is only a mirror now */
.lambdock-window.shelf-mode {
  background-image: none;
  border: none;
  box-shadow: none;
}

(define dock-mode 'taskbar)
(define dock-shelf-margin -10)
(define dock-shelf-front 14)
(define dock-reflection 0.2)

(define dock-position 'top)
(define dock-shelf-margin -20)
(define dock-shelf-front 16)
(define dock-reflection 0.3)

.shelf-projected separator {
  margin: 0;
  min-width: 3px;
  background-image:
    linear-gradient(to bottom, transparent, rgba(255, 255, 255, 0.22) 18%,
                    rgba(255, 255, 255, 0.22) 74%, transparent),
    linear-gradient(to bottom, transparent, rgba(112, 126, 146, 0.30) 18%,
                    rgba(112, 126, 146, 0.30) 74%, transparent);
  background-size: 2px 100%, 1px 100%;
  background-position: right, left;
  background-repeat: no-repeat, no-repeat;
}

scheme@(guile-user)> (set-dock-shelf-margin! -22)
scheme@(guile-user)> (set-dock-shelf-front! 18)
scheme@(guile-user)> (set-dock-reflection! 0.28)
scheme@(guile-user)> (set-dock-reflection-intensity! 0.5)
scheme@(guile-user)> (set-dock-reflection-blur! 0.05)
;; one instance only: pass its settings path as the second argument
scheme@(guile-user)> (set-dock-shelf-tilt! 0 "/home/me/.config/lambdock/settings.scm")

/* a flat matte bar: no gloss, no rounded outer corners */
.lambdock-window.shelf-mode {
  background-image: linear-gradient(180deg, #2b3140 0%, #1b2029 100%);
  border: 1px solid rgba(255, 255, 255, 0.10);
  border-radius: 6px;
  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.45);
}

/* a two-tone slab: bright inner strip, darker front face */
.lambdock-window.shelf-mode.shelf-bottom {
  background-image: linear-gradient(
    0deg,
    rgba(255, 255, 255, 0.85) 0px,
    rgba(120, 134, 156, 0.95) 2px,
    rgba(88, 100, 120, 0.95) 6px,
    rgba(232, 238, 246, 0.92) 7px,
    rgba(246, 249, 252, 0.92) 100%
  );
}

lambdock supports loading and specifying icons in different ways. It loads the active GTK 4 Icon theme and proceeds to load the icon.

When you pass an icon string to app-item, the C runtime's create_image_for_icon function checks for the icon in this order:

1. Embedded Resource: A resource:// path, or one under /org/jointhefreeworld/lambdock/, is loaded straight from the GResource bundle.
2. Direct File Path: Checks if the string is a valid file path on disk.
3. Theme Icon: Queries GtkIconTheme for the icon name in your active GTK icon theme (e.g., Papirus, Adwaita, Yaru), otherwise through DConf.
4. System Pixmaps: Searches pixmaps/<name>.png in each XDG system data directory (usually /usr/share/pixmaps/).
5. Symbolic Fallback: Appends -symbolic to try a monochrome fallback.
6. Generic Fallback: Displays the standard application-x-executable icon if no match is found.

The pipeline lives in create_image_for_icon (src/ui/icon_resolver.c); HACKING.org lists the same stages from the C side.

You can also find available icons already in many ways, see some examples below:

grep -R -i "^Icon=" /usr/share/applications/
# or using ripgrep which is nicer
rg -i "^Icon=" /usr/share/applications/

# or flatpaks
rg -i "^Icon=" /var/lib/flatpak/exports/share/applications/*.desktop

# or (user) flatpaks
rg -i "^Icon=" ~/.local/share/flatpak/exports/share/applications/*.desktop

# or icons from scalable SVG
find /usr/share/icons/Adwaita/ -name "*.svg" | xargs -n1 basename | sed 's/\.svg$//' | sort -u

If you use Emacs with Geiser:

1. Run M-x geiser-connect-local.
2. Select guile as the Scheme implementation.
3. Enter the socket path: /tmp/lambdock-repl.sock.

You can connect directly from your terminal using different tooling, like nc, ncat or socat wrapped with rlwrap, and others:

socat - UNIX-CONNECT:/tmp/lambdock-repl.sock
ncat -U /tmp/lambdock-repl.sock
nc -U /tmp/lambdock-repl.sock
rlwrap socat - UNIX-CONNECT:/tmp/lambdock-repl.sock

Tracking a window means answering one question: which dock item is this? The only thing the compositor gives you is an application id (xdg_toplevel.app_id), and that id is whatever the toolkit set – org.gnome.Nautilus, org.gnome.SystemMonitor, wezterm, google-chrome, jetbrains-idea, Freebuff, or sometimes nothing at all. It is not a name, and it is not an icon name either. lambdock resolves it against the applications actually installed on the machine, so the answer comes from the desktop file rather than from string guessing.

• Clean and powerful abstractions to batch-generate config dynamically and without boilerplate.
• S-Expression Templating: Use meta-programming, quasiquoting and macro expansion for Lisp super powers (quasiquote, macros).
• Code that writes code for a deep system integration with your OS, as demonstrated in my Heks GNU/Linux lambdock config.

Guile is engineered from the ground up as the official GNU extension language. Through the libguile API, execution flows seamlessly in both directions. This gives many interesting advantages, and it is what allows the same process to own both the rendering and the language you control it with.

lambdock uses Maak, a Scheme task runner, so the build recipes are readable Lisp rather than opaque Makefiles. Run maak <task> from the repository root:

If you use ccls or another LSP client, generate your local .ccls configuration using maak. Otherwise read that code a bit and you can copy the solution.

# Generate .ccls with correct Guix package flags
maak add-libs

# Run lambdock inside time-machine environment
maak run

The suite has two halves, and both run under Meson:

meson setup build
ninja -C build test

• C tests (tests/test_*.c): dock items, dock window, Guile bridge, popover menu, theme engine, icon resolver, the glass shelf, the desktop-entry parser, stacks and drag and drop. These build and exercise real GTK widgets through Meson (test_dock_item, test_dock_window, test_popover_menu, test_theme_engine, test_icon_resolver, test_shelf, test_guile_bridge, test_desktop_entry, test_stack, test_dock_dnd, test_meter, test_trash), so they catch GTK behaviour, not just arithmetic. The trash tests build throwaway trash directories and cover the freedesktop.org layout, the count, emptying (including read-only directories and orphans), moving dropped files and folders in with GIO (including name collisions) and the item's full/empty states; the stack tests cover the directory listing (dot-files, ordering, missing folders) and the fan's rotation maths; the drag and drop tests cover the drop-position arithmetic, the list reordering and the item identity that the layout overrides are built on.
• Scheme unit tests (tests/scheme/lambdock_tests.scm, driven by tests/run_scheme_tests.sh): the pure-Guile configuration engine – state, items, presets, loader, layout overrides and core – with no display server and no C runtime needed, so they are fast and easy to run in a loop.

The Nix package runs exactly this suite under Xvfb with a private D-Bus session and a controlled font configuration.

The Guix side does the same through maak test: it rebuilds =build/ inside the pinned environment and runs the suite on a virtual X server with the X11 backend and an icon theme, so a CI runner with no compositor runs the real GTK tests instead of skipping them. That is why the Guix manifest carries xvfb-run and adwaita-icon-theme alongside the compiler and Meson.

See Translation status above. po/ is the place to be, and maak i18n-update keeps the template in step with the source.

Open an issue on the repository's homepage, or bring it up on Zulip first if you are not sure yet whether it is a bug.

A report is easiest to act on when it says what you did, what you expected, and what happened instead – plus your compositor and its version, your GTK, Guile and (if you use it) Guix versions, whether you are on a released tag or trunk, and the contents of your ~/.config/lambdock/settings.scm. If the dock crashes or misbehaves, the output of lambdock from a terminal, plus ninja -C build && ./build/lambdock if you can reproduce it on trunk, saves a round trip.

You can also mail me <jjbigorra@gmail.com> to chat, discuss or send feedback.

The branch is trunk. Small, focused commits are the easiest to review.

• Build and test before you send: maak test should pass (it rebuilds build/ and runs everything on a virtual display), and the C compiler is configured with -Werror for things like implicit conversions, so a warning is a build failure.
• New behaviour wants a test. C behaviour goes in tests/, the configuration engine in tests/scheme/, and both are cheap to extend.
• New user-visible strings should be wrapped in (G_ "...") in C so they can be translated, and the .po files refreshed with maak i18n-update.
• New themes are a CSS file in resources/css plus a build define; new presets are an entry in presets.scm.
• Documentation counts as code here: if this README, HACKING.org or NEWS.org no longer matches what the program does, that is a bug worth a patch.

Everything here is meant to be read and run. Clone it, run maak run, change a theme symbol in your settings file, watch the dock change under you, then open M-x geiser-connect-local and ask the running dock what it thinks its theme is. If something in this document does not match what the code does, tell us.