Stable

gargears

Desktop Control Panel

A centralized GUI control panel for the gardesk desktop suite. Configure and control all gardesk components from a single interface with live daemon communication, instant apply mode, and persistent daemon operation.

View on GitHub Install

Features

11 configuration panels for all gardesk components
Real-time daemon communication via Unix socket IPC
Instant apply mode for live configuration changes
Daemon mode with persistent background operation
Visual status indicators for running components
Manages both Lua and TOML configuration files
Cairo/Pango rendering with dark theme
Keyboard-driven with full mouse support
Color picker, sliders, toggles, and dropdowns
Automatic daemon discovery and 5-second reconnection
Multi-instance garterm support (per-PID sockets)
CLI control via gargearsctl for scripting

Quick Start

What is gargears?

gargears is the control center for your gardesk desktop. It provides a unified interface to configure and control all gardesk components including the window manager (gar), status bar (garbar), wallpaper daemon (garbg), terminal (garterm), system tray (gartray), and more.

Changes can be applied instantly to running daemons or saved to configuration files for persistence across sessions.

Installation

Install gargears using the unified installer or build from source:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=gargears # Install via script

$ cd ~/.local/src/gardesk/gargears && cargo build --release # Or build from source

Running gargears

gargears supports two modes: GUI mode for immediate interaction and daemon mode for persistent background operation.

GUI Mode (Default)

Launch gargears directly to open the configuration window:

terminal

$ gargears # Open control panel

$ gargears --panel garbg # Open directly to garbg panel

Daemon Mode

Run gargears as a persistent daemon that can be shown/hidden on demand:

terminal

$ gargears --daemon # Start daemon (window hidden)

$ gargearsctl show # Show the window

$ gargearsctl toggle # Toggle visibility

$ gargearsctl quit # Stop daemon

Basic Usage

The interface consists of a sidebar showing all 11 gardesk components and a content area displaying the selected panel's configuration options.

Panel Actions

Apply - Send changes to the running daemon immediately
Reset - Revert to the last applied values
Save - Persist changes to the configuration file

Instant Apply Mode

Press I to toggle instant apply mode. When enabled, every change is immediately sent to the running daemon without clicking Apply.

Keyboard Shortcuts

Escape / Q - Close window (quit in GUI mode, hide in daemon mode)
I - Toggle instant apply mode
R - Refresh all daemon connections
Tab - Navigate between widgets
Enter - Activate button / confirm input

Configuration

gargears manages configuration files for all gardesk components. It supports both Lua and TOML configuration formats depending on the component.

Managed Configuration Files

Lua Configuration

Shared configuration file for gar, garbar, and garterm:

~/.config/gar/init.lua

• gar: border_width, border_color_focused/unfocused, gap_inner/outer, focus_follows_mouse
• garbar: height, position, font_family, font_size, modules_left/center/right
• garterm: font, colors, scrollback

TOML Configuration Files

Component-specific configuration files:

~/.config/garbg/config.toml - Wallpaper daemon
~/.config/garlock/config.toml - Screen locker
~/.config/garshot/config.toml - Screenshot tool
~/.config/garclip/config.toml - Clipboard manager
~/.config/garlaunch/config.toml - Application launcher
~/.config/garnotify/config.toml - Notification daemon
~/.config/gartray/config.toml - System tray
~/.config/garfield/config.toml - File explorer

Configuration Reload

After saving changes, components reload their configuration automatically or via these methods:

• gar: garctl reload or automatic via IPC
• garbar: kill -SIGHUP $(pidof garbar)
• garbg: Automatic via IPC subscription
• garlock: Reloads on next lock activation
• garshot: Reads config on each invocation

Example: garbg Configuration

The garbg panel manages wallpaper settings. Here's the TOML structure gargears reads and writes:

~/.config/garbg/config.toml

$ [slideshow]

$ enabled = true

$ interval_secs = 300 # 5 minutes

$ shuffle = true

$ [[sources]]

$ type = "directory"

$ path = "/home/user/wallpapers"

$ recursive = true

$ [animation]

$ transition = "fade"

$ duration_ms = 1000

Overview

gargears is a centralized GUI control panel for the gardesk X11 desktop suite. It provides a unified configuration and control interface for all gardesk components with real-time daemon communication, instant apply mode, and persistent daemon operation.

Supported Components

gargears provides configuration panels for 11 gardesk components:

• gar - Window manager
• garbar - Status bar
• garbg - Wallpaper daemon
• garterm - Terminal emulator
• gartray - System tray
• garshot - Screenshot tool
• garlock - Screen locker
• garfield - File explorer
• garclip - Clipboard manager
• garlaunch - App launcher
• garnotify - Notifications

Project Structure

workspace

$ gargears/ # Main GUI application

$ src/app.rs # Application state and event loop

$ src/daemon.rs # IPC server for daemon mode

$ src/config/ # Lua and TOML config management

$ src/ipc/ # Daemon communication adapters

$ src/panels/ # 11 configuration panels

$ src/ui/ # Widget system and rendering

$ gargearsctl/ # CLI control utility

$ gargears-ipc/ # Shared IPC protocol types

Keyboard Shortcuts

Key	Action
`Escape`	Close window (quit GUI / hide daemon)
`Q`	Close window
`I`	Toggle instant apply mode
`R`	Refresh all daemon connections
`Tab`	Navigate to next widget
`Shift+Tab`	Navigate to previous widget
`Enter`	Activate button / confirm input

IPC Protocol

gargears exposes an IPC interface when running in daemon mode. The CLI tool gargearsctl communicates with the daemon via Unix socket.

Socket Location

socket

$ $XDG_RUNTIME_DIR/gargears.sock # Default location

$ /run/user/1000/gargears.sock # Typical path

gargearsctl Commands

terminal

$ gargearsctl show # Show gargears window

$ gargearsctl hide # Hide gargears window

$ gargearsctl toggle # Toggle window visibility

$ gargearsctl status # Get daemon status (JSON)

$ gargearsctl quit # Stop the daemon

JSON Protocol

Commands are sent as JSON objects over the Unix socket:

Request Format

json

$ { "command": "show" }

$ { "command": "hide" }

$ { "command": "toggle" }

$ { "command": "status" }

$ { "command": "quit" }

Response Format

json

$ { "success": true } # Success response

$ { "success": false, "error": "message" } # Error response

$ { "success": true, "data": { "visible": true, "running": true } } # Status response

Keybinding Integration

Bind gargearsctl to a key in your gar configuration for quick access:

~/.config/gar/init.lua

$ -- Toggle gargears with Super+G

$ gar.bind("Super", "g", function()

$ gar.spawn("gargearsctl toggle")

$ end)

Troubleshooting

Daemon not connecting to components

gargears shows red status indicators for components it can't connect to.

• Verify the component is running: pidof gar
• Check socket exists: ls $XDG_RUNTIME_DIR/*.sock
• gargears retries connections every 5 seconds automatically
• Check component logs for IPC errors

Changes not persisting after restart

Apply sends changes to the running daemon but doesn't save to disk.

• Use the Save button to write to config files
• Verify config file permissions: ls -la ~/.config/gar/
• Check that the config directory exists

gargearsctl: connection refused

The daemon is not running or socket doesn't exist.

• Start daemon: gargears --daemon
• Check socket: ls $XDG_RUNTIME_DIR/gargears.sock
• Verify XDG_RUNTIME_DIR is set: echo $XDG_RUNTIME_DIR

Window doesn't appear

In daemon mode, the window starts hidden.

• Run gargearsctl show to display the window
• For immediate display, run without --daemon flag
• Check if another gargears instance is running

Instant apply not working

Changes aren't being applied in real-time.

• Press I to enable instant apply mode
• Check status indicator shows instant apply is active
• Verify the component daemon is connected (green indicator)

Debug logging

Enable debug output to diagnose issues:

terminal

$ RUST_LOG=debug gargears # Full debug output

$ RUST_LOG=gargears=debug gargears # gargears only

$ RUST_LOG=info gargears --daemon --no-fork # Daemon with logs

gargears

Features

Quick Start

What is gargears?

Installation

Running gargears

GUI Mode (Default)

Daemon Mode

Basic Usage

Panel Actions

Instant Apply Mode

Keyboard Shortcuts

Configuration

Managed Configuration Files

Lua Configuration

TOML Configuration Files

Configuration Reload

Example: garbg Configuration

Overview

Supported Components

Project Structure

Architecture

Core Components

Dependencies

Application Modes

GUI Mode (Default)

Daemon Mode

Event Loop

Configuration Panels

gar

garbar

garbg

Others

gar Panel

Appearance

Behavior

Read-Only Information

garbar Panel

Layout

Typography

Colors

Modules

garbg Panel

Current Wallpaper Info

Slideshow Controls

Other Panels

garterm

gartray

garshot

garlock

garfield

garclip

garlaunch

garnotify

Widget System

Button

Toggle

NumberInput

Slider

TextInput

Dropdown

ColorPicker

Label

IPC Adapters

Common Methods

Socket Locations

Config Management

Lua Configuration

Supported Value Types

Example Modifications

TOML Configuration

Config Structures

Instant Apply Mode

Enabling

Behavior

Keyboard Shortcuts

IPC Protocol

Socket Location

gargearsctl Commands

JSON Protocol