SERVICES

Services Catalog

70+ QML singletons that handle everything that isn't pure UI. Each service is registered in services/qmldir (or services/deferred/qmldir) and available as a singleton import everywhere.

Only some services expose an IPC handler. The real IPC targets are listed where they exist; if a service has no IPC target: note, it has no IpcHandler and is not callable from the inir CLI. To regenerate the authoritative list: grep -rl IpcHandler services/ | xargs grep -oP 'target:\s*"\K[^"]+'.

Compositor

Service	What it does
NiriService	Niri IPC via Unix socket. Tracks workspaces, windows, outputs, keyboard layouts. Event-driven with reactive properties. IPC target: keyboard (layout switching).
CompositorService	Detects compositor (Niri/Hyprland/GNOME), provides sorted toplevel windows and compositor-agnostic APIs.
HyprlandData	Hyprland window, workspace, monitor, and layer data via hyprctl.
HyprlandKeybinds	Parses Hyprland config for keybind cheatsheet.
HyprlandXkb	Keyboard layout tracking for Hyprland.

Audio and Media

Service	What it does
Audio	PipeWire integration. Default sink/source, volume, mute, per-app mixer. EasyEffects virtual sink detection. IPC target: audio.
MprisController	MPRIS player management. Filters real players, deduplicates YT Music instances, tracks active player with grace period for track transitions. IPC target: mpris.
YtMusic	YouTube Music player. Search, queue, playback via mpv + yt-dlp. IPC target: ytmusic.
SongRec	Music recognition via SongRec (Shazam-like audio fingerprinting).

System

Service	What it does
Network	NetworkManager integration. WiFi networks, connection status, signal strength.
BluetoothStatus	Bluetooth adapter and device status via BlueZ D-Bus.
Battery	UPower integration. Percentage, charging state, charge limit control, low/critical thresholds.
Brightness	Monitor brightness via brightnessctl (laptop) and ddcutil (external monitors). Per-screen control. IPC target: brightness.
PowerProfilePersistence	Restores the user's power profile on startup.
GameMode	Fullscreen detection with auto/manual activation. Suppresses animations, notifications, blur when gaming. IPC target: gamemode.
Idle	Idle management via swayidle. Screen-off, lock, and suspend timeouts. Set idle.onBattery.enable to apply a separate, shorter set of timeouts while a laptop runs unplugged.
ResourceUsage	CPU, RAM, GPU, temperature, disk polling. History arrays for graphs. Auto-stop timer (15s) when no consumers active.
ScreenTime	Optional focused-app usage tracking. Local JSON storage, daily totals, hourly buckets, 3/14 day range aggregation. Disabled unless sidebar.screenTime.enable is true.
SystemInfo	Distro name, username, desktop environment detection.
ShellLayoutController	Validates and persists bar, dock, taskbar and sidebar placement across panel families. IPC target: shellLayout.
Privacy	Mic and screen sharing detection via PipeWire link analysis.

Theming and Appearance

Service	What it does
ThemeService	Theme orchestration. Applies presets, triggers wallpaper-based regeneration, manages auto vs manual mode.
MaterialThemeLoader	Watches colors.json (generated by the color pipeline) and loads Material 3 colors into Appearance tokens.
ThemePresets	46 built-in theme presets (Catppuccin, Gruvbox, Nord, Angel, etc.) with full M3 color definitions.
Wallpapers	Wallpaper management. Multi-monitor support, video wallpapers, backdrop system, auto-cycling.
WallpaperListener	Multi-monitor wallpaper config resolver.
IconThemeService	Icon theme management. Syncs to GTK, KDE, Qt5ct, Qt6ct. Smart Electron app icon resolution.
FontSyncService	Syncs shell fonts to GTK/KDE desktop settings.
AwwwBackend	awww animated wallpaper daemon integration.
GowallService	gowall wallpaper color extraction and palette generation.

Data and Storage

Service	What it does
Notifications	Notification management with persistent storage, popup control, grouping, DND mode, GameMode integration. IPC target: notifications.
Cliphist	Clipboard history with fuzzy search. Uses cliphist backend. IPC target: cliphistService.
Events	Local calendar events with categories, priorities, reminders, recurrence. JSON storage.
CalendarSync	External calendar sync via ICS/iCal URLs. Fetches with curl, parses in JS. Supports Google Calendar, Outlook, Nextcloud, any CalDAV.
Weather	Open-Meteo weather data with GPS, manual coordinates, or city name location.
Todo	Todo list with JSON + markdown sync.
Notepad	Persistent plaintext notepad.
KeyringStorage	Secure API key storage via GNOME Keyring (secret-tool).
DateTime	Date/time formatting, uptime tracking.

Desktop Integration

Service	What it does
Autostart	Autostart manager. Reads/writes the managed section of ~/.config/niri/config.d/50-startup.kdl. Niri's own spawn-at-startup directives are the source of truth, not a Config JSON list. IPC target: autostart.
TrayService	System tray with workarounds for problematic apps (Vesktop, Steam, etc.).
PolkitService	PolicyKit authentication agent for privileged operations.
Hyprsunset	Night light via wlsunset (Niri) or hyprsunset (Hyprland). Scheduled or manual.
EasyEffects	EasyEffects audio effects toggle. Supports native and flatpak.
RecorderStatus	Screen recording status detection (wf-recorder).
MascotMood	Session-long personality mood for the mascot, with time-of-day seeding and jittered changes. IPC target: mascotMood.
SessionWarnings	Detects running package managers before logout.
ConflictKiller	Kills conflicting system trays and notification daemons on startup.
FirstRunExperience	First-run wizard trigger.

Application Management

Service	What it does
AppLauncher	Default app slot manager (terminal, browser, file manager, etc.).
AppSearch	Desktop entry fuzzy search with icon substitution mappings.
AppCatalog	Curated software catalog with multi-distro install support. IPC target: appCatalog.
LauncherSearch	Overview search with prefix routing (apps, actions, calculator, packages).
TaskbarApps	Dock/taskbar app list (merged pinned + open windows).
MinimizedWindows	Niri window minimization via hidden workspace. IPC target: minimize.
WindowPreviewService	Window preview caching for task view.
GlobalActions	Modular action registry for keyboard-driven workflows. User-extensible. IPC target: globalActions.

Content

Service	What it does
Ai	LLM chat. Gemini, OpenAI, Mistral, OpenRouter, Ollama. Tool use, streaming, conversation history. IPC target: ai.
AnimeService	AniList GraphQL API. Anime schedule, seasonal listing.
Wallhaven	Wallhaven.cc wallpaper search with rate limiting.
Booru	Multi-booru image board API (yande.re, konachan, danbooru, etc.).
VoiceSearch	Voice recording + Gemini transcription + web search. IPC target: voiceSearch.
Emojis	Emoji picker data.
PackageSearch	Async package manager search (pacman + AUR). IPC target: packageSearch.

Utilities

Service	What it does
TimerService	Pomodoro timer with persistent state.
Updates	System update checker (Arch only, uses checkupdates).
ShellUpdates	iNiR update checker. Git-based, tracks commits behind remote. IPC target: shellUpdate.
Ydotool	Virtual keyboard input for on-screen keyboard.
LatexRenderer	LaTeX math rendering via MicroTeX.
Translation	i18n string lookup. Auto language detection, 15 languages.
DevNavigation	Deterministic development navigation for loading lazy surfaces and internal settings views. IPC target: dev.
CustomWidgets	User-installed custom widget management (scan/create/list/remove from the widgets dir). IPC target: customWidgets.
MemoryPressureService	Monitors JSGCHeap accumulation (Qt V4 memfd leak); notifies and offers a shell restart. IPC target: memory.
WidgetPowerManager	Pauses desktop-widget rendering on game mode / fullscreen / present windows / edit mode. IPC target: widgetpower.

For contributors

Services are stability boundaries. Changes to a service API affect every module that consumes it.

Before modifying a service:

1. Check consumer count: grep -r "ServiceName\." modules/ services/
2. Prefer add-only changes to public APIs
3. Register new services in services/qmldir
4. Add IPC targets to IPC Reference if applicable