Skip to main content
Otter Shell is a Wayland desktop in Zig. Apps share the same libraries for rendering, Wayland, config, and desktop services.

​
Repository structure

The otter-shell organization has one git repo per component. The monorepo folder on disk is a checkout layout, not one repo. Commit and push per component.
RepositoryType
otter-bar, otter-launcher, otter-term, …Applications
otter-ui, otter-render, otter-wayland, …Shared libraries
otter-zenithDebian packaging and release assembly
otter-zenith clones tagged component releases and builds .deb packages for PikaOS.

​
Architecture

┌─────────────────────────────────────────────┐
│  Applications (otter-bar, otter-launcher,   │
│  otter-term, otter-settings, …)             │
├─────────────────────────────────────────────┤
│  otter-ui (Surface Description, widgets)    │
├──────────┬──────────┬──────────┬────────────┤
│ otter-   │ otter-   │ otter-   │ otter-     │
│ render   │ wayland  │ desktop  │ theme      │
├──────────┴──────────┴──────────┴────────────┤
│  otter-conf, otter-config-types,           │
│  otter-tools-core, otter-vte,              │
│  otter-geo, otter-utils                    │
└─────────────────────────────────────────────┘
UI apps share one rendering path:
  1. Describe layout with otter-ui Surface Description nodes
  2. Emit draw commands into a CommandList (otter-render)
  3. Rasterize with quad_renderer to Wayland SHM buffers (otter-wayland)

​
Requirements

  • Zig 0.16.0: required by all Otter packages
  • System dev libraries: libwayland-dev, libfontconfig-dev, libfreetype-dev, libxkbcommon-dev
  • Optional: libpam0g-dev (lock/greeter), libghostty-vt-dev-git (terminal), FFmpeg dev (recorder)
  • A wlroots-based compositor with zwlr_layer_shell_v1 for most UI apps

​
Config convention

Apps read ~/.config/otter-shell/<app>.conf. Shared styling is in ~/.config/otter-shell/theme.conf. See Configuration overview.

​
Workspace-only components

In the source tree but not packaged in otter-shell or otter-shell-extras:
  • otter-dock: application dock with magnification
  • otter-hypr: Hyprland layout and titlebar companion
  • otter-theme-gen: wallpaper-reactive theme generator

​
Next steps