OCWS Configuration Reference¶

Complete reference for configuring and extending the OCWS Wayland shell platform.

The OCWS Event Bus¶

Background scripts communicate with the zigshell-cairo-pango UI via ocws-emit.sh. This is the sanctioned way to push state updates into the shell.

ocws-emit.sh <Namespace.Key> <Value>

Full Namespace Reference¶

Audio¶

ocws-emit.sh System.Volume 75          # 0-100 integer
ocws-emit.sh System.VolumeMuted 1      # 1 = muted, 0 = unmuted

Display¶

ocws-emit.sh System.Brightness 80      # 0-100 integer

Power¶

ocws-emit.sh System.Battery 65         # percentage 0-100
ocws-emit.sh System.BatteryState "Charging"   # Charging / Discharging / Full

Hardware Monitors¶

ocws-emit.sh System.Cpu 23             # CPU usage percentage
ocws-emit.sh System.Memory 45          # RAM usage percentage
ocws-emit.sh System.Disk 60            # Disk usage percentage
ocws-emit.sh System.Temperature 52     # CPU temperature C

Media¶

ocws-emit.sh Media.Title "Song Name"
ocws-emit.sh Media.Artist "Artist Name"
ocws-emit.sh Media.Album "Album Name"
ocws-emit.sh Media.Status "Playing"    # Playing / Paused / Stopped
ocws-emit.sh Media.Art "/tmp/cover.jpg"

Network¶

ocws-emit.sh Network.WiFi "Connected"
ocws-emit.sh Network.WiFiSSID "MyNetwork"
ocws-emit.sh Network.Bluetooth "Disconnected"

System¶

ocws-emit.sh System.DND 1              # Do Not Disturb: 1 = on, 0 = off

How It Works Internally¶

ocws-emit.sh writes the key-value pair to zigshell-cairo-pango's scanner socket. zigshell-cairo-pango updates any widget whose expression reads that variable (via Val(), RegEx(), Extract(), etc.).

dotfiles/ocws/ocws-daemon.sh is the background daemon that listens to system events (ALSA, udev, playerctl) and calls ocws-emit.sh continuously.

Variable Contract¶

All IPC variable names are defined in contracts/variables.ini as the single source of truth. The emit script and all widgets must use these exact names. See docs/events.md for the full mapping table.

The Plugin Autoloader¶

OCWS supports drag-and-drop widget extensibility without editing the core config.

Adding a Plugin¶

Create a widget file, e.g. my-weather.widget
Place it in ~/.config/ocws/plugins/
Reload the shell (restart zigshell-cairo-pango or log out/in)

cp my-weather.widget ~/.config/ocws/plugins/
pkill zigshell-cairo-pango && zigshell-cairo-pango -f ~/.config/ocws/ocws.config &

ocws-plugin-loader.sh scans plugins/ at startup and generates plugins.config, which is included by ocws.config automatically.

# ~/.config/ocws/plugins/my-widget.widget
#Api2

scanner {
  step = 5000
  exec("my-script.sh") {
    MyWidgetData = Grab(First)
  }
}

export button "my-widget" {
  style = "module_pill"
  class = "module"
  tooltip = "My Widget"
  action = Exec("my-script.sh action")

  grid {
    style = "pill_grid"
    image { value = "my-icon-symbolic" }
    label { value = MyWidgetData }
  }
}

User Overlay Config¶

Personal customizations go in ~/.config/ocws/user.config. This file is never overwritten by the installer. It is loaded after all platform configs, so anything here overrides the defaults.

# ~/.config/ocws/user.config
#Api2

# Override terminal
# Exec("foot")  ->  Exec("kitty")

# Custom CSS
# #CSS
# button.module { min-height: 20px; }

Visual Configuration¶

OCWS renders its aesthetics via standard GTK3 CSS.

Theme Files¶

File	Role
`~/.config/ocws/ocws.css`	Generated by theme-engine — panel CSS
`~/.config/ocws/theme.css`	Static structural CSS (layout, widget geometry)
`themes/*.ini`	Color palette profiles
`templates/ocws.css.tmpl`	Template used by theme-engine to generate ocws.css

Adjusting Transparency¶

In ~/.config/ocws/ocws.css, locate window#zigshell-cairo-pango:

window#zigshell-cairo-pango {
  background-color: rgba(30, 30, 46, 0.92);  /* last value = opacity 0.0-1.0 */
  border-radius: 12px;
}

Increase the alpha (4th value) toward 1.0 for a more opaque panel, decrease toward 0.0 for more transparency.

Applying a Color Theme¶

# List available themes
theme-engine.sh list

# Apply a theme (regenerates all CSS and config files)
theme-engine.sh apply themes/catppuccin-mocha.ini

# Preview without committing (Ctrl+C to revert)
theme-engine.sh preview themes/tokyo-night.ini

Theme .ini files live in themes/ and contain color variables. The theme-engine writes them into the CSS templates and regenerates ocws.css, fuzzel.ini, and foot.ini.

Window Management (labwc)¶

Window management, keybindings, and compositor rules are in ~/.config/labwc/rc.xml.

Keybinding Syntax¶

<keybind key="Super+d">
  <action name="Execute">
    <command>fuzzel</command>
  </action>
</keybind>

<!-- Run an action script -->
<keybind key="Print">
  <action name="Execute">
    <command>~/.local/bin/actions/screenshot.sh region</command>
  </action>
</keybind>

Default Keybindings¶

Key	Action
`Super+Enter`	Launch `foot` terminal
`Super+D`	Launch `fuzzel` app launcher
`Super+V`	Open clipboard history
`Super+Q`	Close focused window
`Super+F`	Toggle fullscreen
`Super+1-9`	Switch workspace
`Super+Shift+1-9`	Move window to workspace
`Alt+Tab`	Cycle windows
`XF86AudioRaiseVolume`	Volume up
`XF86AudioLowerVolume`	Volume down
`XF86AudioMute`	Toggle mute
`XF86MonBrightnessUp`	Brightness up
`XF86MonBrightnessDown`	Brightness down
`Print`	Screenshot region to file
`Shift+Print`	Screenshot region to clipboard
`Super+Print`	Screenshot fullscreen to file

Window Rules¶

OCWS shell windows are excluded from the taskbar and pager:

<applications>
  <application class="zigshell-cairo-pango">
    <skip_taskbar>yes</skip_taskbar>
    <skip_pager>yes</skip_pager>
    <layer>top</layer>
  </application>
</applications>

Do not remove this rule or OCWS panels will behave like normal movable windows.

Reload Config¶

Apply rc.xml changes without restarting the session:

labwc --reconfigure

C Helper Binaries¶

OCWS ships a suite of compiled C utilities in zig-out/bin/, installed to ~/.local/bin/.

CLI Tools¶

Binary	Purpose
`ocws-brightness`	Smooth backlight control with easing animation
`ocws-volume`	Smooth PulseAudio volume control with easing
`ocws-clip`	Clipboard manager (cliphist + fuzzel picker)
`ocws-shot`	Screenshot tool (grim + slurp + annotation)
`ocws-lock`	Screen lock wrapper (swaylock)
`ocws-kv`	Key-value persistent store (flat file)
`ocws-emit`	Event Bus IPC emitter (maps namespaces to zigshell-cairo-pango vars)
`ocws-ocr`	Screen OCR via Tesseract/Leptonica
`ocws-sysmon`	System metrics (CPU/mem/net/bat/bt/brightness/temp)
`ocws-color`	Wallpaper palette extraction (median-cut)
`ocws-recorder`	Screen recording (wf-recorder wrapper)
`ocws-network-bandwidth`	Network bandwidth monitor (/proc/net/dev)
`ocws-player`	Media player controller (playerctl wrapper)
`ocws-search`	Multi-engine web search
`ocws-state`	Persistent state manager (JSON state files)
`ocws-validate`	System validator (dependencies, config, binaries)
`ocws-style`	Theme engine CLI (INI → CSS generation)
`ocws-tooltip`	GTK3 tooltip row builder

Daemons¶

Binary	Purpose
`ocws-notify`	D-Bus notification daemon (replaces mako)
`ocws-osd-notify`	Glassmorphic notification popup (GTK Layer Shell)
`ocws-wallpaper`	Time-of-day wallpaper transitions (Cairo crossfade)
`ocws-live-bg`	Animated live background (GTK Layer Shell)
`ocws-hypertile`	Dynamic tiling for labwc (wlr-foreign-toplevel)

GUI Apps¶

Binary	Purpose
`ocws-settings`	11-tab control center (Shell, Appearance, Bar, Widgets, etc.)
`ocws-welcome`	First-run setup wizard
`ocws-workspace-mgr`	Kanban-style workspace/window manager
`ocws-dock-mgr`	Dock pinned apps manager
`ocws-dotdesktop-mgr`	.desktop file manager
`ocws-pkgmgr`	Dependency resolver and build tool

Build all binaries:

zig build
# Output in zig-out/bin/

Action Scripts¶

All scripts in scripts/actions/ are installed to ~/.local/bin/actions/ and can be called directly from labwc keybindings or zigshell-cairo-pango widget actions.

Script	Usage
`audio.sh up/down/mute/get`	Volume control + `ocws-emit`
`brightness.sh up/down/get`	Backlight control + `ocws-emit`
`screenshot.sh full/region/region-copy`	grim + slurp screenshot capture
`clipboard.sh`	cliphist + fuzzel clipboard picker
`launcher.sh`	Launch fuzzel app picker
`power-menu.sh`	fuzzel power menu (shutdown/reboot/suspend/lock)
`workspace.sh`	Workspace switching helpers
`workspace-actions.sh`	Advanced workspace management
`network.sh`	WiFi/network status and control
`wifi-menu.sh`	Fuzzy WiFi connection menu
`bluetooth-menu.sh`	Fuzzy Bluetooth pairing menu
`vpn.sh`	VPN connection control
`display.sh`	Multi-monitor layout manager
`dnd.sh`	Do Not Disturb toggle
`mic.sh`	Microphone control
`window.sh`	Window snap, maximize, float helpers
`fuzzel-emoji.sh`	Emoji picker via fuzzel dmenu
`fuzzel-calc.sh`	Calculator via fuzzel dmenu + bc
`maintenance.sh`	System maintenance tasks
`dock.sh`	Application dock management
`menu-system.sh`	System submenu for right-click menu
`menu-hardware.sh`	Hardware submenu
`menu-aesthetics.sh`	Theme/aesthetics submenu
`menu-tools.sh`	Tools submenu
`menu-windows.sh`	Window management submenu
`dotfiles-menu.sh`	Dotfiles management submenu
`quick-settings.sh`	Quick settings toggles

State Management¶

OCWS persists state using the ocws-kv binary (flat file store).

# Set a value
ocws-kv set theme catppuccin-mocha

# Get a value
ocws-kv get theme

# List all keys
ocws-kv list

# Delete a key
ocws-kv del old-key

State is stored at ~/.config/ocws/state.kv (plain text, human-readable/editable).

scripts/ocws-state.sh is the higher-level state coordinator used by ocws-daemon.sh. dotfiles/ocws/ocws-daemon.sh is the background daemon that bridges system events to zigshell-cairo-pango.

Theme Engine Internals¶

The theme engine (scripts/theme-engine.sh) reads INI profiles from themes/ and expands {{VAR}} placeholders in templates/*.tmpl files.

INI Profile Sections¶

Each theme .ini file contains sections for every config surface:

Section	Generates
`[meta]`	Theme metadata (name, author, description)
`[colors]`	Color palette (single source of truth)
`[labwc]`	Window manager theme colors
`[gtk3]`	GTK3 settings (theme, icons, cursor, fonts)
`[gtk4]`	GTK4 settings
`[fonts]`	Font family and size
`[zigshell-cairo-pango]`	Panel CSS colors
`[rofi]`	Rofi launcher colors
`[mako]`	Notification colors
`[foot]`	Terminal colors
`[qt6ct]`	Qt6 theme colors
`[cursor]`	Cursor theme

Variable Expansion¶

The engine maps ${section.key} in INI files to {{VAR}} in templates:

# themes/catppuccin-mocha.ini
[colors]
bg = #1e1e2e
fg = #cdd6f4

/* templates/zigshell-cairo-pango.css.tmpl */
window#zigshell-cairo-pango {
  background-color: {{COLOR_BG}};
  color: {{COLOR_FG}};
}

The engine reads the INI, looks up colors.bg, and replaces {{COLOR_BG}} with #1e1e2e.

Generated Output Files¶

11 config surfaces are generated from templates:

~/.config/ocws/ocws.css (from templates/ocws.css.tmpl)
~/.config/ocws/theme.css (from templates/zigshell-cairo-pango.css.tmpl)
~/.config/fuzzel/fuzzel.ini (from templates/fuzzel.ini.tmpl)
~/.config/foot/foot.ini (from templates/foot.ini.tmpl)
~/.config/labwc/environment (from templates/environment.tmpl)
~/.config/labwc/themerc-override (from templates/themerc-override.tmpl)
~/.config/gtk-3.0/settings.ini (from templates/gtk3-settings.ini.tmpl)
~/.config/gtk-4.0/settings.ini (from templates/gtk4-settings.ini.tmpl)
~/.config/mako/config (from templates/mako.ini.tmpl)
~/.config/qt6ct/qt6ct.conf (from templates/qt6ct.conf.tmpl)
~/.config/gtk-3.0/gtk.css (from templates/gtk.css.tmpl)

Modular Config System¶

OCWS uses a modular configuration architecture in dotfiles/ocws/modes/. Each mode is composed from reusable config and CSS modules.

Mode Files¶

Mode	Description
`doublepanel.mode`	Dual-panel: top status bar + bottom dock/taskbar
`zigshell-cairo-pango.mode`	Single status bar + external zigshell-cairo-pango
`minimal.mode`	Minimal bar: clock, volume, battery, tray only

Config Modules¶

Module	Purpose
`modes/base.config`	Common settings (ImagePath, ThicknessHint, plugin autoloader)
`modes/topbar.config`	Top status bar definition
`modes/bottombar.config`	Bottom bar with dock + taskbar
`modes/statusbar.config`	Single status bar (zigshell-cairo-pango mode)
`modes/desktop.config`	Desktop layer for floating widgets

CSS Modules¶

Module	Purpose
`modes/css-glassmorphism.config`	Glassmorphism tokens and base styles
`modes/css-bars.config`	Bar-specific panel styles
`modes/css-widgets.config`	Widget button and pill styles
`modes/css-taskbar.config`	Taskbar item styles
`modes/css-dock.config`	Dock icon grid styles
`modes/css-popups.config`	Popup and menu styles

Using Modular Configs¶

# Start with a specific mode
zigshell-cairo-pango -c ~/.config/ocws/modes/doublepanel.mode

# Or use the mode selector
zigshell-cairo-pango-mode start doublepanel
zigshell-cairo-pango-mode start zigshell-cairo-pango
zigshell-cairo-pango-mode start minimal

Exposed Settings¶

settings.config exposes all user-configurable options:

# ~/.config/ocws/settings.config
#Api2

# Bar sizes
Set OCWS_TOP_BAR_SIZE = "32"
Set OCWS_BOTTOM_BAR_SIZE = "40"
Set OCWS_STATUS_BAR_SIZE = "34"

# Launcher command
Set OCWS_LAUNCHER_COMMAND = "rofi -show drun"

# Clock format
Set OCWS_CLOCK_FORMAT = "%H:%M"

# Taskbar
Set OCWS_TASKBAR_ICONS = "true"
Set OCWS_TASKBAR_LABELS = "false"
Set OCWS_TASKBAR_ICON_SIZE = "28"

# Visual settings
Set OCWS_BG_ALPHA = "0.92"
Set OCWS_TRANSITION_DURATION = "0.15s"

# Feature toggles
Set OCWS_FEATURE_DOCK = "true"
Set OCWS_FEATURE_TASKBAR = "true"
Set OCWS_FEATURE_DESKTOP_WIDGETS = "true"

Config Validation¶

OCWS includes validators to catch config errors before deployment:

# Validate zigshell-cairo-pango configs
scripts/validate-zigshell-cairo-pango.sh

# Validate widget files
scripts/validate-widgets.sh

# Validate variable contract
scripts/validate-contract.sh

zigshell-cairo-pango Config Validator¶

Checks for: - #Api2 header presence - Brace and quote matching - Include file references - Duplicate bar names - Widget references - CSS token usage

LLM Runner¶

ocws-llm-runner is a local-first LLM chat and OCR assistant with GTK3 GUI.

Architecture¶

ocws-llm-runner/
├── main.py              # Entry point
├── server/
│   ├── app.py           # Flask REST API
│   ├── llm.py           # LLM inference (llama-cpp-python)
│   ├── ocr.py           # OCR processor (Tesseract/ocws-ocr)
│   └── sessions.py      # Session persistence
├── gui/
│   └── app.py           # GTK3 glassmorphic GUI
└── utils/
    └── __init__.py

API Endpoints¶

Endpoint	Method	Description
`/api/health`	GET	Health check
`/api/models`	GET	List available models
`/api/model/load`	POST	Load a GGUF model
`/api/model/eject`	POST	Unload current model
`/api/model/switch`	POST	Switch to different model
`/api/model/download`	POST	Download model from URL
`/api/chat`	POST	Send message
`/api/chat/stream`	POST	Stream response
`/api/sessions`	GET/POST	List/create sessions
`/api/sessions/<id>`	GET/PUT/DELETE	Session CRUD
`/api/ocr`	POST	OCR uploaded image
`/api/ocr/region`	POST	Capture region and OCR

Usage¶

# Start GUI + server
ocws-llm-runner

# Start server only
ocws-llm-runner --server-only

# OCR an image
ocws-llm-runner --ocr image.png

Recommended Models¶

Category	Model	RAM
Coding	Qwen2.5-Coder-1.5B	~2GB
Coding	DeepSeek-Coder-V2-Lite	~3GB
Vision	Llama-3.2-1B-Vision	~2GB
Lightweight	TinyLlama-1.1B	~1GB