A modern, native Wayland desktop pet — lightweight, GPU-accelerated, and built in Rust.
Tux the penguin walks, runs, sleeps, and follows your cursor on KDE Plasma 6 and COSMIC, with zero desktop interference.
Status Badges:
| Desktop Support | Status |
|---|---|
| KDE Plasma 6 | ✓ Working |
| COSMIC | ✓ Working (new) |
| GNOME | Planned (help wanted) |
| Hyprland | Planned |
| Sway | Planned |
| Project Status | Value |
|---|---|
| Version | v0.3.0 |
| Maturity | Alpha |
| Language | Rust (edition 2021) |
| License | MIT |
- Native Wayland — wlr-layer-shell overlay, no XWayland, no X11
- Click-through — never steals focus, never blocks input
- AI-driven — Tux sleeps when idle, wakes on cursor movement, runs when you move fast
- Multi-screen — detects all outputs and moves across them
- HiDPI — respects output scale factors
- Lightweight —
< 20 MB RAM,< 1% CPU, no Electron, no Qt, no GTK - Procedural asset — Tux is generated in code; no external files needed
- Backend abstraction — KDE Plasma and COSMIC work now; GNOME, Hyprland, Sway are prepared
Screencast_20260712_164251.webm
# Build and run the daemon on (Wayland session)
cargo run --bin waypenguin-daemonwaypenguin-daemon [OPTIONS]
| Flag | Short | Default | Description |
|---|---|---|---|
--count <N> |
-n |
5 |
Number of pets to spawn (1–50) |
--pack <id> |
-p |
(built-in default) | Pet pack to use, by pack ID |
--data <path> |
-d |
(XDG data dir) | Custom path to the pets directory |
--scale <N> |
-s |
(pack default) | Pet size multiplier (0.1–3.0) |
--list |
-l |
— | List all discovered packs and exit |
# Spawn 1 pet using the ladybug pack
waypenguin-daemon --count 1 --pack ladybug-classic
# List all available packs (built-in and user-installed)
waypenguin-daemon --list
# Use a custom pets folder
waypenguin-daemon --data ~/.local/share/my-pets --pack my-custom-pack
# Spawn pets at 50% smaller scale
waypenguin-daemon --scale 0.5
# Spawn pets at 2x size
waypenguin-daemon --scale 2.0Use --pack <id> to select a theme. Run --list to see all packs installed on your system.
Drop a directory containing a pack.toml and SVG pose files into your pets folder (~/.local/share/waypenguin/pets/ by default, or the path set with --data). The walker activity is required; all others are optional. Run --list to confirm the pack is discovered.
# pack.toml — minimal example
[pack]
id = "my-pet"
name = "My Custom Pet"
author = "You"
license = "CC-BY-4.0"
version = "1.0.0"
description = "A custom desktop pet."
[activities]
walker = "walker.svg"Download a pre-built executable for your architecture and add it to your PATH.
TAG="v0.1.0"
ARCH="x86_64" # or aarch64 for arm64
curl -fLO "https://github.com/<owner>/<repo>/releases/download/${TAG}/waypenguin-daemon-linux-${ARCH}"Make executable and move to a directory in your PATH:
chmod +x waypenguin-daemon-linux-${ARCH}
sudo mv waypenguin-daemon-linux-${ARCH} /usr/local/bin/waypenguin-daemonOr use your home directory PATH:
mkdir -p ~/.local/bin
mv waypenguin-daemon-linux-${ARCH} ~/.local/bin/waypenguin-daemon
export PATH="$HOME/.local/bin:$PATH"waypenguin-daemonMost modern Linux distributions include these. If you encounter missing libraries:
# Debian / Ubuntu
sudo apt install -y libwayland-client0 libwayland-cursor0 libxkbcommon0
# Fedora / RHEL / Rocky
sudo dnf install -y wayland libxkbcommonDownload the new executable and repeat steps 2-3.
- Linux with a KDE Plasma 6 (KWin) or COSMIC Wayland session
- Rust toolchain (edition 2021)
libwayland-client,libwayland-cursor,libxkbcommon
waypenguin-core/ # Types, AI engine, animation state machine
waypenguin-renderer/ # Pixel rendering & frame compositing
waypenguin-backends/ # DesktopBackend / DesktopWindow traits
kde/ # KDE/KWin backend (functional)
cosmic/ # COSMIC backend (functional)
gnome/ # GNOME/Mutter backend (stub, ready for implementation)
hyprland/ # Hyprland backend (stub, ready for implementation)
waypenguin-assets/ # Procedural spritesheet generation (Tux)
waypenguin-daemon/ # Main loop: backend, AI, render, present
waypenguin-cli/ # CLI tool (placeholder)
waypenguin-settings/ # Settings GUI (placeholder)
Every compositor backend implements DesktopBackend + DesktopWindow:
pub trait DesktopBackend {
fn get_screens(&self) -> Vec<ScreenInfo>;
fn get_cursor_position(&self) -> (i32, i32);
fn create_window(…) -> Result<Box<dyn DesktopWindow>, BackendError>;
}Adding a new compositor = impl the trait. No core changes needed.
See ROADMAP.md for details.
The GNOME backend crate exists (waypenguin-backends/gnome/) but requires runtime validation and fixes. If you use GNOME Wayland, we need help with:
- Skeleton in place — basic layer-shell, pointer, and output handling
- Testing on real GNOME sessions — verify cursor tracking, window positioning, layer-shell anchoring
- Debugging — layer-shell protocol differences between GNOME/Mutter and KWin
- Compositor flags — document any special Mutter properties or environment variables needed
- Edge cases — multi-monitor setups, HiDPI scaling, Wayland protocol version differences
To help: Open an issue describing your GNOME version, Wayland session details, and any errors you encounter. Patches welcome.
| Concern | Choice | Why |
|---|---|---|
| Language | Rust | Performance, memory safety, zero-cost abstractions |
| Windowing | smithay-client-toolkit | Idiomatic Wayland in Rust, layer-shell support |
| Rendering | SHM + software | Zero GPU deps for MVP; Vulkan/Metal planned |
| Config | serde + JSON | Portable, human-editable, well-known |
Please read CONTRIBUTING.md and AGENTS.md before submitting PRs.
MIT — see LICENSE.