Developer overview

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.

Repository	Type
`otter-bar`, `otter-launcher`, `otter-term`, …	Applications
`otter-bench`	Otter Bench / Otter HUD suite
`otter-ui`, `otter-render`, `otter-wayland`, …	Shared libraries
`otter-zenith`	Debian packaging for the desktop shell
`otter-shell-plugins`, `otter-plugin-factory`	Example `.so` plugins + `opf` scaffold CLI
`otter-gaming-utils`	Debian packaging for Otter Bench and HUD

otter-zenith clones tagged shell releases and builds .deb packages for PikaOS. otter-gaming-utils does the same for Otter Bench against a pinned LIB_VERSION of the shell libraries.

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:

Describe layout with otter-ui Surface Description nodes
Emit draw commands into a CommandList (otter-render)
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), 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-hypr: Hyprland layout and titlebar companion
otter-cue: desktop interaction sound library (pinned in zenith for builds; no debian/control package yet)

Otter Assistant packages (otter-assist, otter-assistant, otter-assist-data, otter-assist-model) and speech model packages ship in otter-shell-extras. otter-dock and otter-taskbar ship in the base otter-shell metapackage. Otter Bench and Otter HUD ship in otter-gaming-utils (separate from otter-shell).

Building from source: compile any component locally
Creating an app: start a new app with Otter libraries
Writing plugins: bar widgets and launcher providers as .so files
Libraries overview: stack diagram and compile flags
Individual library pages under Libraries in the sidebar

Getting Started

Libraries

Repository structure

Architecture

Requirements

Config convention

Workspace-only components

Next

​Repository structure

​Architecture

​Requirements

​Config convention

​Workspace-only components

​Next

Repository structure

Architecture

Requirements

Config convention

Workspace-only components

Next