Developer overview - Otter Shell

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-ui`, `otter-render`, `otter-wayland`, …	Shared libraries
`otter-zenith`	Debian 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:

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), 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 Assistant packages (otter-assist, otter-assistant, otter-assist-data) ship in otter-shell-extras.

Next steps

Building from source: compile any component locally
Creating an app: start a new app with Otter libraries
Libraries overview: stack diagram and compile flags
Individual library pages under Libraries in the sidebar

​Repository structure

​Architecture

​Requirements

​Config convention

​Workspace-only components

​Next steps