⚡ Beta v0.1.0

garbar

Async status bar daemon with native gar integration and modular architecture

garbar is the status bar component of the gardesk ecosystem. Built in Rust with async Tokio runtime, Cairo/Pango rendering, and deep integration with the gar window manager. Features include EWMH workspace tracking, multi-monitor support, XEmbed and StatusNotifierItem tray protocols, and unified configuration through gar's Lua config system. Control the bar at runtime via garbarctl CLI or Unix socket IPC.

View on GitHub Download RPM

🎯 RPM Available

Features

✓
Async Tokio Runtime
Non-blocking module updates with tokio::select event loop
✓
9 Built-in Modules
workspaces, window_title, cpu, memory, battery, datetime, tray, script, quick_settings
✓
Cairo/Pango Rendering
Hardware-accelerated text and gradient rendering
✓
Native gar Integration
Shared Lua configuration via gar.bar table
✓
Multi-Monitor Support
Independent bar per monitor with RandR hotplug detection
✓
System Tray
XEmbed (legacy) and StatusNotifierItem (modern D-Bus) protocols
✓
IPC Control
garbarctl CLI and JSON over Unix socket
✓
EWMH Compliant
Real-time workspace and window tracking via X11 properties

Installation

RPM (Fedora/RHEL)

terminal

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garbar garbarctl

From Source

terminal

$git clone https://github.com/espadon/gardesk

$cd gardesk/garbar

$cargo build --release

$sudo cp target/release/garbar /usr/local/bin/

$sudo cp target/release/garbarctl /usr/local/bin/

Dependencies

garbar requires the following runtime dependencies:

cairo - 2D graphics library for rendering
pango - Text layout and rendering
xcb - X11 protocol bindings
dbus - D-Bus for StatusNotifierItem tray protocol

Automatic Startup

When using gar, garbar starts automatically via systemd user services. The gar-session.target pulls in garbar.service, ensuring the bar is available when gar's X11 session is ready.

systemd Service

# ~/.config/systemd/user/garbar.service
[Unit]
Description=garbar status bar daemon
PartOf=gar-session.target
After=gar.service

[Service]
ExecStart=/usr/bin/garbar daemon
Restart=on-failure
Environment="GAR_BAR_CONFIG=%h/.cache/gar/bar-config.json"

[Install]
WantedBy=gar-session.target

When gar starts, it activates gar-session.target, which starts garbar. When gar exits, the target deactivates and garbar stops gracefully.

Manual Startup

If running garbar standalone (without gar), start the daemon directly:

terminal

$garbar daemon

INFO Starting garbar daemon INFO Connected to X11 display INFO Found 2 monitors INFO Entering main event loop

Verbose Logging

terminal

$garbar --verbose daemon

Quick Configuration

Configure garbar directly in your gar init.lua file. When gar starts, it serializes the gar.bar table to JSON and passes it to garbar.

-- ~/.config/gar/init.lua
gar.bar = (
  height = 32,
  position = "top",
  background = "#1e1e2e",
  foreground = "#cdd6f4",

  modules_left = ( "workspaces", "window_title" ),
  modules_center = (),
  modules_right = ( "cpu", "memory", "datetime" ),

  modules = (
    workspaces = (
      show_empty = false,
      focused = (
        foreground = "#ffffff",
        underline = ( width = 2, color = "#89b4fa" ),
      ),
    ),
    datetime = (
      format = "%H:%M",
      format_alt = "%Y-%m-%d %H:%M:%S",
    ),
  ),
)

Verifying Installation

terminal

$garbarctl status

( "visible": true, "width": 1920, "height": 32, "modules_left": ["workspaces", "window_title"], "modules_center": [], "modules_right": ["cpu", "memory", "datetime"] )

File Locations

Config: ~/.config/gar/init.lua (via gar.bar table)
Cache: ~/.cache/gar/bar-config.json (serialized config)
PID file: $XDG_RUNTIME_DIR/garbar.pid
Socket: $XDG_RUNTIME_DIR/garbar.sock
Logs: journalctl --user -u garbar.service

Configuration Reference

garbar configuration is defined in the gar.bar Lua table in ~/.config/gar/init.lua. When gar starts, it serializes this table to JSON and passes it to garbar. This unified configuration approach ensures gar and garbar stay in sync without configuration drift.

Bar Options

Option	Type	Default	Description
`height`	-	32	Bar height in pixels
`position`	-	"top"	Bar position: "top" or "bottom"
`background`	-	"#1a1a1a"	Background color (hex) or gradient config
`foreground`	-	"#ffffff"	Default text color (hex)
`opacity`	-	1.0	Window opacity 0.0 to 1.0
`fonts`	-	JetBrainsMono 10	Font stack array for text rendering
`modules_left`	-	workspaces, window_title	Modules to display on left side
`modules_center`	-	(empty)	Modules to display in center
`modules_right`	-	cpu, memory, battery, datetime	Modules to display on right side

Padding Options

Option	Type	Default	Description
`padding.top`	-	0	Top padding in pixels
`padding.right`	-	16	Right padding in pixels
`padding.bottom`	-	0	Bottom padding in pixels
`padding.left`	-	8	Left padding in pixels

Margin Options

Option	Type	Description
`margin.top`	-	Top margin in pixels
`margin.right`	-	Right margin in pixels
`margin.bottom`	-	Bottom margin in pixels
`margin.left`	-	Left margin in pixels

Border Options

Option	Type	Default	Description
`border.width`	-	0	Border width in pixels
`border.color`	-	""	Border color (hex)
`border.radius`	-	0	Corner radius in pixels

Shadow Options

Option	Type	Default	Description
`shadow.enabled`	-	false	Enable drop shadow
`shadow.color`	-	"#00000080"	Shadow color with alpha (hex)
`shadow.blur`	-	8	Shadow blur radius in pixels
`shadow.offset.x`	-	0	Horizontal shadow offset
`shadow.offset.y`	-	0	Vertical shadow offset

Animation Options

Option	Type	Default	Description
`animations.enabled`	-	true	Enable module transitions
`animations.duration`	-	150	Animation duration in milliseconds
`animations.easing`	-	"ease-out-cubic"	Easing function name

Separator Options

Option	Type	Default	Description
`separator.text`	-	"│"	Separator character between modules
`separator.foreground`	-	"#555555"	Separator color (hex)
`separator.padding`	-	8px horizontal	Separator padding config

Gradient Backgrounds

The background option can be a solid color string or a gradient configuration object.

Option	Type	Default	Description
`type`	-	"gradient"	Gradient type: "gradient" (linear) or "radial"
`direction`	-	"horizontal"	Linear direction: "horizontal", "vertical", "diagonal"
`stops`	-	-	Array of gradient stops with position and color
`center`	-	(0.5, 0.5)	Radial center point (0.0-1.0 normalized)
`radius`	-	1.0	Radial radius (normalized to smaller dimension)

Gradient Example

gar.bar = (
  background = (
    type = "gradient",
    direction = "horizontal",
    stops = (
      ( position = 0.0, color = "#1e1e2e" ),
      ( position = 0.5, color = "#313244" ),
      ( position = 1.0, color = "#1e1e2e" ),
    ),
  ),
)

Radial Gradient Example

gar.bar = (
  background = (
    type = "radial",
    center = ( 0.5, 0.5 ),
    radius = 1.5,
    stops = (
      ( position = 0.0, color = "#45475a" ),
      ( position = 1.0, color = "#1e1e2e" ),
    ),
  ),
)

Module Configuration

Per-module configuration lives under the modules table. Each module has its own set of options.

Workspaces Module

Option	Type	Default	Description
`show_empty`	-	false	Show indicators for empty workspaces
`show_urgent`	-	true	Show urgent workspace state
`pin_workspaces`	-	false	Pin workspaces to specific positions
`focused.background`	-	"transparent"	Focused workspace background
`focused.foreground`	-	"#ffffff"	Focused workspace text color
`focused.underline`	-	2px #33ccff	Underline config for focused state
`unfocused.background`	-	"transparent"	Unfocused workspace background
`unfocused.foreground`	-	"#666666"	Unfocused workspace text color
`urgent.background`	-	"#ff5555"	Urgent workspace background
`urgent.foreground`	-	"#ffffff"	Urgent workspace text color
`font_size`	-	inherit	Override font size for workspace labels

Window Title Module

Option	Type	Default	Description
`max_length`	-	50	Maximum title length before truncation
`ellipsis`	-	"..."	Truncation suffix
`empty_text`	-	"Desktop"	Text when no window focused
`show_icon`	-	true	Show window icon if available
`icon_spacing`	-	8	Space between icon and title

CPU Module

Option	Type	Default	Description
`format`	-	" {usage}%"	Display format with placeholders
`interval`	-	2	Update interval in seconds
`warning_threshold`	-	70	Usage % to trigger warning color
`critical_threshold`	-	90	Usage % to trigger critical color
`warning_foreground`	-	"#ffaa00"	Warning state text color
`critical_foreground`	-	"#ff5555"	Critical state text color
`graph.enabled`	-	false	Show CPU usage graph
`graph.width`	-	50	Graph width in pixels
`graph.style`	-	"bars"	Graph style: "bars", "line", "area"

Memory Module

Option	Type	Default	Description
`format`	-	" {percent}%"	Display format with placeholders
`format_alt`	-	" {used}/{total}"	Alternate format (click to toggle)
`interval`	-	5	Update interval in seconds
`warning_threshold`	-	80	Usage % to trigger warning color
`critical_threshold`	-	95	Usage % to trigger critical color

Battery Module

Option	Type	Default	Description
`device`	-	"auto"	Battery device path or "auto"
`format_charging`	-	" {percent}%"	Format when charging
`format_discharging`	-	"{icon} {percent}%"	Format when discharging
`format_full`	-	" Full"	Format when fully charged
`icons`	-	5 battery icons	Array of threshold/icon pairs
`low_threshold`	-	15	Percentage to trigger low warning
`low_animation`	-	"blink"	Animation when low: "blink" or "none"
`low_foreground`	-	"#ff5555"	Text color when battery low

DateTime Module

Option	Type	Default	Description
`format`	-	" %a %b %d %H:%M"	strftime format string
`format_alt`	-	" %Y-%m-%d %H:%M:%S"	Alternate format (click to toggle)
`interval`	-	1	Update interval in seconds
`tooltip`	-	true	Show tooltip on hover

Tray Module

Option	Type	Default	Description
`icon_size`	-	18	Tray icon size in pixels
`spacing`	-	8	Space between tray icons
`padding.left`	-	4	Left padding for tray area
`padding.right`	-	4	Right padding for tray area

Quick Settings Module

Option	Type	Default	Description
`enabled`	-	true	Enable quick settings trigger
`icon`	-	"gear"	Icon when inactive
`icon_active`	-	"gear"	Icon when panel is open
`foreground`	-	"#abb2bf"	Icon color
`active_foreground`	-	"#61afef"	Icon color when active

Script Module

Option	Type	Default	Description
`exec`	-	-	Command or script path to execute
`interval`	-	30	Update interval in seconds
`tail`	-	false	Tail mode: read continuously
`format`	-	""	Output format string
`click_left`	-	""	Command on left click
`click_middle`	-	""	Command on middle click
`click_right`	-	""	Command on right click
`scroll_up`	-	""	Command on scroll up
`scroll_down`	-	""	Command on scroll down
`font_size`	-	inherit	Override font size

Complete Configuration Example

-- ~/.config/gar/init.lua
gar.bar = (
  height = 32,
  position = "top",
  background = "#1e1e2e",
  foreground = "#cdd6f4",
  opacity = 0.95,

  fonts = (
    "JetBrainsMono Nerd Font:size=10",
    "DejaVu Sans Mono:size=10",
    "monospace:size=10",
  ),

  padding = ( left = 8, right = 16, top = 0, bottom = 0 ),
  margin = ( left = 0, right = 0, top = 0, bottom = 0 ),

  border = ( width = 0, color = "", radius = 0 ),

  animations = ( enabled = true, duration = 150, easing = "ease-out-cubic" ),

  separator = (
    text = "|",
    foreground = "#45475a",
    padding = ( left = 8, right = 8 ),
  ),

  modules_left = ( "workspaces", "window_title" ),
  modules_center = (),
  modules_right = ( "cpu", "memory", "battery", "tray", "datetime" ),

  modules = (
    workspaces = (
      show_empty = false,
      show_urgent = true,
      focused = (
        background = "transparent",
        foreground = "#cdd6f4",
        underline = ( width = 2, color = "#89b4fa" ),
      ),
      unfocused = (
        background = "transparent",
        foreground = "#585b70",
      ),
      urgent = (
        background = "#f38ba8",
        foreground = "#1e1e2e",
      ),
    ),

    window_title = (
      max_length = 50,
      ellipsis = "...",
      empty_text = "Desktop",
      show_icon = true,
    ),

    cpu = (
      format = " (usage)%",
      interval = 2,
      warning_threshold = 70,
      critical_threshold = 90,
      warning_foreground = "#f9e2af",
      critical_foreground = "#f38ba8",
    ),

    memory = (
      format = " (percent)%",
      format_alt = " (used)/(total)",
      interval = 5,
      warning_threshold = 80,
      critical_threshold = 95,
    ),

    battery = (
      device = "auto",
      format_charging = " (percent)%",
      format_discharging = "(icon) (percent)%",
      format_full = " Full",
      low_threshold = 15,
      low_animation = "blink",
      low_foreground = "#f38ba8",
    ),

    datetime = (
      format = " %a %b %d   %H:%M",
      format_alt = " %Y-%m-%d   %H:%M:%S",
      interval = 1,
      tooltip = true,
    ),

    tray = (
      icon_size = 18,
      spacing = 8,
      padding = ( left = 4, right = 4 ),
    ),
  ),
)

Overview

garbar is an async status bar daemon built in Rust for the gardesk desktop environment. It renders a configurable status bar with modules for workspace indicators, window titles, system monitoring, date/time, and system tray icons. garbar integrates deeply with the gar window manager through shared configuration, EWMH property communication, and coordinated lifecycle management.

The bar uses Cairo for rendering and Pango for text layout, providing high-quality antialiased graphics with support for gradients, rounded corners, and shadows. The async Tokio runtime enables non-blocking module updates, ensuring the UI remains responsive even when modules perform I/O operations like reading /proc or querying D-Bus.

Architecture

Daemon State

The DaemonState struct is the central coordinator for garbar. It owns:

X11 Connection: Manages the X11 connection and event handling
Bar Windows: One BarWindow per monitor, positioned via RandR
Render Surface: Cairo ImageSurface sized to the widest monitor
Text Renderer: Pango-based text layout with configurable fonts
Module Registry: Collection of active modules with async update methods
IPC Server: Unix socket server for garbarctl commands
Tray Manager: XEmbed system tray manager
SNI Host: D-Bus StatusNotifierItem host for modern tray icons

Event Loop

garbar uses tokio::select! to multiplex multiple event sources in a single async loop:

while running (
    tokio::select! (
        // Handle Unix signals (SIGTERM, SIGHUP)
        signal = signal_handler.recv() => handle_signal(signal),

        // Handle X11 events (Expose, ButtonPress, PropertyNotify)
        event = conn.next_event() => handle_x11_event(event),

        // Handle SNI D-Bus events (item registered/unregistered)
        event = sni_event_rx.recv() => handle_sni_event(event),

        // Periodic module updates (50ms tick rate)
        _ = update_interval.tick() => (
            poll_ipc_commands(),
            refresh_sni_items(),
            modules.update_all(),
            draw_bar(),
        ),
    )
)

The 50ms tick rate provides snappy workspace updates while keeping CPU usage low. Event-driven modules (workspaces, window_title) subscribe to X11 PropertyNotify events for instant updates.

Rendering Pipeline

Each frame follows this rendering pipeline:

Clear the Cairo surface (Operator::Clear)
Fill background (solid color or gradient)
Collect module outputs (Vec<Block> from each module)
Compute layout positions (left-aligned, centered, right-aligned)
Render each positioned block (background, text, underline)
Render SNI icons at the tray module position
Copy surface to each bar window via XCopyArea

Module System

Modules implement the Module trait with these methods:

trait Module: Send + Sync (
    fn name(&self) -> &'static str;
    fn output(&self) -> ModuleOutput;
    fn interval(&self) -> u64;  // 0 = event-driven only
    fn update(&mut self);
    fn on_click(&mut self, button: u8, block_index: usize, x: i16, y: i16);
    fn on_scroll(&mut self, up: bool, block_index: usize, x: i16, y: i16);
)

The ModuleRegistry manages module instantiation and provides async methods for collecting outputs and dispatching events. Each module runs in the main thread but can spawn background tasks for I/O-heavy operations.

gar Integration

garbar shares configuration with gar through the gar.bar Lua table. When gar starts:

gar parses init.lua and extracts the gar.bar table
The Lua table is serialized to JSON using serde
JSON is written to ~/.cache/gar/bar-config.json
The GAR_BAR_CONFIG environment variable points to this file
garbar's ConfigLoader reads and deserializes the JSON

This approach eliminates configuration drift between components. When you change gar.bar in init.lua and run garctl reload, gar re-serializes the config and signals garbar to reload.

EWMH Communication

gar and garbar communicate through Extended Window Manager Hints (EWMH) X11 properties:

gar → garbar (State Updates)

_NET_CURRENT_DESKTOP: Active workspace number. garbar subscribes to PropertyNotify events on the root window to detect changes instantly.
_NET_DESKTOP_NAMES: Workspace names array. garbar displays these labels in the workspaces module instead of raw numbers.
_NET_NUMBER_OF_DESKTOPS: Total workspace count. garbar uses this to generate the correct number of workspace indicators.
_NET_ACTIVE_WINDOW: Currently focused window XID. The window_title module queries this window's _NET_WM_NAME to display the active window's title.
_NET_CLIENT_LIST: All managed window XIDs. garbar uses this to detect workspace occupancy (which workspaces have windows).

garbar → gar (User Actions)

Workspace clicks: garbar sends i3-IPC commands over gar's socket to switch workspaces when users click workspace indicators.
Window actions: The window_title module can send commands to close, minimize, or toggle floating state for the focused window.

Lifecycle Management

gar manages garbar's lifecycle through systemd user services:

garbar.service is a dependency of gar-session.target
When gar starts, it activates gar-session.target
systemd starts garbar.service as a dependency
When gar exits, the session target deactivates
garbar receives SIGTERM and shuts down gracefully

Multi-Monitor Support

garbar creates independent bar windows for each monitor:

On startup, garbar queries monitors via RandR extension
For each monitor, a BarWindow is created at the monitor's position
The render surface is sized to the widest monitor
Content is rendered once and copied to all bar windows
garbar subscribes to RandR ScreenChangeNotify events
When monitors are hotplugged, garbar recreates bar windows

X11 Details

Window Properties

Each bar window is created with specific EWMH properties:

_NET_WM_WINDOW_TYPE: _NET_WM_WINDOW_TYPE_DOCK (dock window type)
_NET_WM_STATE: _NET_WM_STATE_STICKY, _NET_WM_STATE_ABOVE (visible on all workspaces, above other windows)
_NET_WM_NAME: "garbar" (window title)
WM_CLASS: "garbar\0garbar\0" (instance and class name)
override_redirect: 1 (bypasses window manager decoration)

Strut Configuration

Struts reserve screen space so windows don't overlap the bar:

// _NET_WM_STRUT = (left, right, top, bottom)
// top = y_position + bar_height
strut = (0, 0, y + height, 0)

// _NET_WM_STRUT_PARTIAL includes X range for per-monitor struts
strut_partial = (
    0, 0, y + height, 0,      // left, right, top, bottom
    0, 0, 0, 0,                // left_start_y, left_end_y, right_start_y, right_end_y
    x, x + width - 1, 0, 0,    // top_start_x, top_end_x, bottom_start_x, bottom_end_x
)

Compositing

garbar supports transparency through the _NET_WM_WINDOW_OPACITY property:

// Opacity is a 32-bit cardinal, 0xFFFFFFFF = 100% opaque
let opacity_value = (opacity * u32::MAX as f64) as u32;
change_property32(window, _NET_WM_WINDOW_OPACITY, CARDINAL, opacity_value)

The compositor (like garbg or picom) reads this property and applies alpha blending. Without a compositor, the bar is fully opaque regardless of this setting.

Built-in Modules

garbar ships with nine built-in modules. Each module independently manages its state and provides output as styled text blocks. Modules can respond to click and scroll events for interactivity.

workspaces

Displays workspace indicators with distinct styling for focused, visible, unfocused, and urgent states. Integrates with gar (and i3/sway) via the i3-IPC protocol for real-time workspace state updates.

Data source: i3-IPC GET_WORKSPACES command and workspace event subscription
Socket discovery: I3SOCK, SWAYSOCK, or $XDG_RUNTIME_DIR/gar-i3.sock
Click action: Switch to clicked workspace via i3-IPC command
Scroll action: Cycle through workspaces
Update mode: Event-driven via workspace subscription

modules = (
  workspaces = (
    show_empty = false,
    show_urgent = true,
    pin_workspaces = false,
    focused = (
      background = "transparent",
      foreground = "#ffffff",
      underline = ( width = 2, color = "#89b4fa" ),
    ),
    unfocused = (
      background = "transparent",
      foreground = "#666666",
    ),
    urgent = (
      background = "#f38ba8",
      foreground = "#1e1e2e",
    ),
  ),
)

window_title

Displays the title of the currently focused window. Updates instantly when focus changes by watching the _NET_ACTIVE_WINDOW property on the root window.

Data source: _NET_ACTIVE_WINDOW property and window's _NET_WM_NAME
Truncation: Long titles are truncated with configurable ellipsis
Empty state: Shows configurable text when no window is focused
Update mode: Event-driven via PropertyNotify on root window

modules = (
  window_title = (
    max_length = 50,
    ellipsis = "...",
    empty_text = "Desktop",
    show_icon = true,
    icon_spacing = 8,
  ),
)

cpu

Real-time CPU usage monitoring. Reads /proc/stat to calculate usage percentage with optional exponential moving average smoothing to prevent jittery display.

Data source: /proc/stat (user, nice, system, idle fields)
Format placeholders: (usage) = percentage
Threshold colors: Different colors for warning/critical levels
Optional graph: Visual usage history with bars, line, or area style

modules = (
  cpu = (
    format = " (usage)%",
    interval = 2,
    warning_threshold = 70,
    critical_threshold = 90,
    warning_foreground = "#f9e2af",
    critical_foreground = "#f38ba8",
    graph = (
      enabled = true,
      width = 50,
      style = "bars",
      color = "#89b4fa",
    ),
  ),
)

memory

RAM usage monitoring with percentage and absolute value display options. Click to toggle between formats.

Data source: /proc/meminfo (MemTotal, MemAvailable)
Format placeholders: (percent), (used), (total), (available)
Click action: Toggle between format and format_alt

modules = (
  memory = (
    format = " (percent)%",
    format_alt = " (used)/(total)",
    interval = 5,
    warning_threshold = 80,
    critical_threshold = 95,
    warning_foreground = "#f9e2af",
    critical_foreground = "#f38ba8",
  ),
)

battery

Battery status with charging/discharging indicators, percentage, and time remaining estimates. Automatically selects the first battery device or uses the configured device path.

Data source: /sys/class/power_supply/BAT*/
Format placeholders: (icon), (percent), (time)
Dynamic icons: Icon changes based on charge level thresholds
Low battery animation: Blinks when below low_threshold

modules = (
  battery = (
    device = "auto",
    format_charging = " (percent)%",
    format_discharging = "(icon) (percent)%",
    format_full = " Full",
    icons = (
      ( threshold = 10, icon = "" ),
      ( threshold = 25, icon = "" ),
      ( threshold = 50, icon = "" ),
      ( threshold = 75, icon = "" ),
      ( threshold = 100, icon = "" ),
    ),
    low_threshold = 15,
    low_animation = "blink",
    low_foreground = "#f38ba8",
  ),
)

datetime

Date and time display with strftime format strings. Click to toggle between primary and alternate formats.

Format: Standard strftime specifiers (%H, %M, %S, %a, %b, %d, etc.)
Click action: Toggle between format and format_alt
Update interval: Set to 1 for second precision, 60 for minute precision

modules = (
  datetime = (
    format = " %a %b %d   %H:%M",
    format_alt = " %Y-%m-%d   %H:%M:%S",
    interval = 1,
    tooltip = true,
  ),
)

tray

System tray hosting both XEmbed (legacy) and StatusNotifierItem (modern) icons. XEmbed icons are embedded as X11 child windows; SNI icons are rendered directly via Cairo.

XEmbed: Acquires _NET_SYSTEM_TRAY_Sn selection
SNI: Registers org.kde.StatusNotifierWatcher D-Bus service
Click forwarding: Mouse events forwarded to tray applications

modules = (
  tray = (
    icon_size = 18,
    spacing = 8,
    padding = ( left = 4, right = 4 ),
  ),
)

script

Execute custom shell scripts and display their output. Enables integration with external tools and custom status indicators.

exec: Command or script path to execute
tail mode: Continuously read script output (for streaming data)
Click actions: Run different commands on left/middle/right click
Scroll actions: Run commands on scroll up/down

modules = (
  -- Named script modules use script:name syntax in modules_right
  script = (
    weather = (
      exec = "~/scripts/weather.sh",
      interval = 600,
      format = "",
      click_left = "xdg-open https://weather.com",
    ),
    spotify = (
      exec = "playerctl metadata --format '(artist) - (title)'",
      interval = 5,
      click_left = "playerctl play-pause",
      scroll_up = "playerctl next",
      scroll_down = "playerctl previous",
    ),
  ),
)

-- Reference in modules_right as "script:weather", "script:spotify"
modules_right = ( "script:weather", "script:spotify", "datetime" )

quick_settings

Trigger for the gartray quick settings panel. Displays a gear icon that changes color when the panel is open.

modules = (
  quick_settings = (
    enabled = true,
    icon = "gear",
    icon_active = "gear",
    foreground = "#abb2bf",
    active_foreground = "#61afef",
  ),
)

garbarctl CLI

garbarctl is the command-line control tool for garbar. It communicates with the running daemon over a Unix domain socket using JSON protocol.

Commands

Option	Type	Default	Description
`show`	-	-	Make the bar visible
`hide`	-	-	Hide the bar
`toggle`	-	-	Toggle bar visibility
`reload`	-	-	Reload configuration from disk
`quit`	-	-	Gracefully stop the daemon
`status`	-	-	Get current bar status as JSON
`update MODULE`	-	-	Force update a specific module

Usage Examples

terminal

$garbarctl show

$garbarctl hide

$garbarctl toggle

$garbarctl reload

$garbarctl update cpu

$garbarctl status

( "visible": true, "width": 1920, "height": 32, "modules_left": ["workspaces", "window_title"], "modules_center": [], "modules_right": ["cpu", "memory", "datetime"] )

$garbarctl quit

Keybinding Integration

Bind garbarctl commands to keys in gar's init.lua:

gar.keybinds = (
  -- Toggle bar visibility with Super+B
  ( mods = ( "Mod4" ), key = "b", action = "spawn", args = "garbarctl toggle" ),

  -- Reload bar config with Super+Shift+B
  ( mods = ( "Mod4", "Shift" ), key = "b", action = "spawn", args = "garbarctl reload" ),
)

IPC Protocol

garbar's IPC uses JSON over a Unix domain socket at $XDG_RUNTIME_DIR/garbar.sock. Each message is a single JSON object terminated by a newline.

Socket Location

$XDG_RUNTIME_DIR/garbar.sock
# Typically: /run/user/1000/garbar.sock

Command Format

Commands are JSON objects with a "command" field and optional additional fields:

// Simple commands
("command": "show")
("command": "hide")
("command": "toggle")
("command": "reload")
("command": "quit")
("command": "status")

// Update specific module
("command": "update_module", "module": "cpu")

Response Format

Responses are JSON objects with success status and optional data:

// Success response
("success": true)

// Success with data (status command)
(
  "success": true,
  "data": (
    "visible": true,
    "width": 1920,
    "height": 32,
    "modules_left": ["workspaces", "window_title"],
    "modules_center": [],
    "modules_right": ["cpu", "memory", "datetime"]
  )
)

// Error response
("success": false, "error": "Module not found: invalid_module")

Raw Socket Example

terminal

$echo '{"command": "status"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/garbar.sock

{"success":true,"data":{"visible":true,"width":1920,"height":32,...}}

Python Example

#!/usr/bin/env python3
import socket
import json
import os

sock_path = os.path.join(os.environ.get('XDG_RUNTIME_DIR', '/tmp'), 'garbar.sock')

def send_command(cmd):
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(sock_path)
        sock.sendall((json.dumps(cmd) + '\n').encode())
        response = sock.recv(4096).decode()
        return json.loads(response)

# Toggle bar visibility
result = send_command(("command": "toggle"))
print("Success:", result["success"])

# Get status
status = send_command(("command": "status"))
print("Visible:", status["data"]["visible"])

Signal Handling

garbar responds to Unix signals for lifecycle management:

SIGTERM: Graceful shutdown (cleans up IPC socket and PID file)
SIGHUP: Reload configuration from disk
SIGINT: Graceful shutdown (Ctrl+C when running in foreground)

terminal

$pkill -SIGHUP garbar

# Reloads configuration

$pkill -SIGTERM garbar

# Graceful shutdown

i3-IPC Integration

The workspaces module communicates with gar (and i3/sway) using the i3-IPC protocol over a Unix socket.

Socket Discovery

garbar searches for the i3-IPC socket in this order:

I3SOCK environment variable
SWAYSOCK environment variable
$XDG_RUNTIME_DIR/gar-i3.sock
/tmp/gar-i3.sock

Messages Used

GET_WORKSPACES (1): Query current workspace list
SUBSCRIBE (2): Subscribe to workspace events
RUN_COMMAND (0): Execute commands like "workspace 3"

Troubleshooting

garbar not starting

Check if another instance is running and verify the socket/PID file:

terminal

$pgrep -a garbar

$cat $XDG_RUNTIME_DIR/garbar.pid

$ls -la $XDG_RUNTIME_DIR/garbar.sock

$# If stale files exist, remove them:

$rm $XDG_RUNTIME_DIR/garbar.pid $XDG_RUNTIME_DIR/garbar.sock

Check systemd service status

terminal

$systemctl --user status garbar.service

$journalctl --user -u garbar.service -f

Configuration not applied

After editing gar's init.lua, reload both gar and garbar:

terminal

$garctl reload # Reload gar config (serializes gar.bar to JSON)

$garbarctl reload # Reload garbar config (reads JSON)

$# Or restart garbar service:

$systemctl --user restart garbar.service

Workspace indicators not updating

Verify gar is setting EWMH properties and the i3-IPC socket exists:

terminal

$xprop -root | grep _NET_CURRENT_DESKTOP

_NET_CURRENT_DESKTOP(CARDINAL) = 0

$xprop -root | grep _NET_DESKTOP_NAMES

_NET_DESKTOP_NAMES(UTF8_STRING) = "1", "2", "3", "4", "5"

$ls -la $XDG_RUNTIME_DIR/gar-i3.sock

$echo $I3SOCK

Window title not updating

Check _NET_ACTIVE_WINDOW property and verify garbar is subscribed to root window events:

terminal

$xprop -root _NET_ACTIVE_WINDOW

_NET_ACTIVE_WINDOW(WINDOW): window id # 0x2200001

$xprop -id 0x2200001 _NET_WM_NAME

_NET_WM_NAME(UTF8_STRING) = "Firefox"

Tray icons not appearing

Check if garbar has acquired the system tray selection and D-Bus is working:

terminal

$xprop -root | grep _NET_SYSTEM_TRAY_S0

_NET_SYSTEM_TRAY_S0(WINDOW): window id # 0x1400003

$busctl --user list | grep StatusNotifier

org.kde.StatusNotifierWatcher 12345 garbar ...

$# Check for SNI items:

$busctl --user call org.kde.StatusNotifierWatcher /StatusNotifierWatcher org.kde.StatusNotifierWatcher RegisteredStatusNotifierItems

Bar not visible / no struts

Verify the bar window exists and has correct properties:

terminal

$xdotool search --class garbar

20971527

$xprop -id 20971527 _NET_WM_WINDOW_TYPE

_NET_WM_WINDOW_TYPE(ATOM) = _NET_WM_WINDOW_TYPE_DOCK

$xprop -id 20971527 _NET_WM_STRUT

_NET_WM_STRUT(CARDINAL) = 0, 0, 32, 0

Transparency not working

Transparency requires a compositor. Check if one is running and the opacity property is set:

terminal

$pgrep -a "picom|compton|garbg"

$xprop -id $(xdotool search --class garbar | head -1) _NET_WM_WINDOW_OPACITY

Multi-monitor issues

Check RandR monitor configuration and verify garbar created bars for each monitor:

terminal

$xrandr --query | grep " connected"

DP-1 connected primary 1920x1080+0+0 HDMI-1 connected 1920x1080+1920+0

$xdotool search --class garbar

20971527 20971528

$# Should see one window ID per monitor

High CPU usage

Check for modules with very short intervals or issues with subscription loops:

terminal

$garbar --verbose daemon 2>&1 | grep -i interval

$# Look for modules updating too frequently

$# Increase intervals in gar.bar.modules config

Font rendering issues

Verify the configured fonts are installed and Pango can find them:

terminal

$fc-list | grep -i "JetBrains"

$pango-view --font="JetBrainsMono Nerd Font 10" --text="Test"

$# Install missing fonts:

$sudo dnf install jetbrains-mono-fonts-all

Debug logging

Enable verbose logging to diagnose issues:

terminal

$RUST_LOG=debug garbar daemon 2>&1 | tee garbar.log

$# Or with specific module logging:

$RUST_LOG=garbar::modules::workspaces=debug garbar daemon

Known Limitations

Wayland is not supported - garbar requires X11
Network and PulseAudio modules are not yet implemented
Per-monitor module layouts not yet supported (all monitors show same content)
Custom module development requires modifying garbar source code

Getting Help

GitHub Issues: github.com/espadon/gardesk/issues
Check journalctl logs: journalctl --user -u garbar.service
Run with verbose logging: garbar --verbose daemon

garbar

Features

Installation

RPM (Fedora/RHEL)

From Source

Dependencies

Automatic Startup

systemd Service

Manual Startup

Verbose Logging

Quick Configuration

Verifying Installation

File Locations

Configuration Reference

Bar Options

Padding Options

Margin Options

Border Options

Shadow Options

Animation Options

Separator Options

Gradient Backgrounds

Gradient Example

Radial Gradient Example

Module Configuration

Workspaces Module

Window Title Module

CPU Module

Memory Module

Battery Module

DateTime Module

Tray Module

Quick Settings Module

Script Module

Complete Configuration Example

Overview

Architecture

Daemon State

Event Loop

Rendering Pipeline

Module System

gar Integration

Configuration Sharing

EWMH Communication

gar → garbar (State Updates)

garbar → gar (User Actions)

Lifecycle Management

Multi-Monitor Support

X11 Details

Window Properties

Strut Configuration

Compositing

System Tray

XEmbed Protocol

StatusNotifierItem (SNI)

Built-in Modules

workspaces

window_title

cpu

memory

battery

datetime

tray

script

quick_settings

garbarctl CLI

Commands

Usage Examples

Keybinding Integration

IPC Protocol

Socket Location

Command Format

Response Format

Raw Socket Example

Python Example

Signal Handling

i3-IPC Integration

Socket Discovery

Messages Used

Troubleshooting