quickshell-config/AGENTS.md

Agent Guidance: Quickshell Project

Core Architecture

• Type: Quickshell/QML based UI.
• State Management: Heavily reliant on QML Singletons for global state, configuration, and paths.
• Main Entry: shell.qml.

Key Singletons

• GlobalStates.qml: Manages global UI visibility (e.g., mediaControlsOpen, notificationPanelOpen).
• common/Config.qml: Manages JSON configuration at ${XDG_CONFIG_HOME}/hydro-os/config.json and watches for file changes.
• common/Directories.qml: Defines XDG and repository-specific file paths (e.g., ${XDG_CONFIG_HOME}/hydro-os/color.json).
• common/Appearance.qml: Handles theme, colors, and transparency.

Component Structure

• bar/: Top bar components.
• osd/: On-screen display components.
• background/: Background/Wallpaper components.
• common/: Shared utility and singleton components.
• settings/: Settings/Configuration components.
• settings.qml: Settings view entry point.

Development Workflow

• Logs: Run quickshell log and read only after the last "INFO: Reloading configuration..."
• Config: Configuration files are located in ${XDG_CONFIG_HOME}/hydro-os/ and may be auto-created by the application.