Skip to content

Configuration Reference

Jump to bottom
P3DROVFX edited this page Oct 12, 2026 · 7 revisions

Configuration Reference

Everything the Settings app touches — and a fair amount it doesn't — lives in one JSON file. This page maps the configuration system: where things are stored, how persistence works, what protects your config from corruption, and what every top-level section covers.

Three ways to change a setting

  1. The Settings app (Super + I) — the normal path. Don't browse for the right page; use the search bar: it jumps to and highlights the exact configuration card.
  2. Edit the file — open ~/.config/illogical-impulse/config.json in any editor; saved changes apply live, no restart needed. This is also the only path for experimental options that don't have a UI control yet.
  3. Ask the AI — with the AI assistant set up, "make my bar transparent" is a valid way to configure your desktop; you get a diff card showing exactly what it changed.

The files

Path What it holds
~/.config/illogical-impulse/config.json The config file — every persistent preference (Config.options.*)
~/.local/state/quickshell/states.json Durable state (Persistent.states.*): remembered tabs, layout memory, search aliases, Google Drive settings, tablet home-screen icons — survives preset changes and config resets
~/.local/state/quickshell/user/notes/ The Notes store: index.json plus one document per note, with assets and revisions (the old user/notes.json is migrated once and kept as notes.json.migrated)
~/.config/illogical-impulse/presets/ Saved [[Presets
~/.config/illogical-impulse/preset-store/ Git clones behind installed and published [[store presets
~/.config/illogical-impulse/workspace_profiles/ [[Workspace Profiles
~/.config/illogical-impulse/widget_extensions.json Third-party [[widget extension
~/.local/state/quickshell/user/generated/ Generated Material colors (colors.json, lockscreen colors, backups) — the wallpaper-theming output
~/.config/quickshell/ii/.env API credentials fallback (Gmail, TickTick) — see .env.example; the preferred store is the system keyring
~/.config/hypr/custom/*.lua Your Hyprland overrides. Settings → Hyprland writes into a fenced block at the end of these — see [[Hyprland Settings
~/.local/state/quickshell/hyprland-backups/ Backups taken before every write to custom/*.lua

How persistence works

modules/common/Config.qml is a singleton wrapping the JSON file with Quickshell's JsonAdapter: every option is a typed QML property, changes are debounced (~75 ms) and written back automatically, and edits you make to the file by hand are picked up live. The Settings app is just a pretty way of setting Config.options.<category>.<key>.

Two sibling singletons complete the picture: Persistent.qml (internal state that should survive restarts but isn't a "preference") and GlobalStates.qml (runtime state — what's open right now — deliberately not persisted).

Config protection

The fork added a proper safety net around the file:

  • Schema versioning — the file carries a configVersion; when an option changes shape between releases, migrateRaw() upgrades old files in place instead of misreading them.
  • Type-drift repair — if a value in the file doesn't match the expected type (a string where a number should be), it's repaired from defaults rather than silently mangled.
  • Enum validation — options with a fixed set of valid values (corner styles, color engines, privacy modes…) are checked and repaired if out of range.
  • Malformed-JSON recovery — a corrupted file no longer gets silently overwritten with defaults; writes are blocked until you decide, and a health banner in Settings reports what happened: malformed, recovered, migrated, repaired, unknownKeys or reset.

So yes — hand-editing is safe and survivable.

The top-level map

Config.options.* sections, grouped by theme. (Settings pages in parentheses where the mapping isn't obvious.)

Appearance & theming

Key Covers
appearance Rounding & sharp mode, fonts, transparency/blur, wallpaper theming + Matugen palette, themed icons, color engine, animation multiplier, app-launch animation, OpenRGB, fake screen rounding
background Wallpaper paths (desktop/lock/light-mode), Wallpaper Engine, parallax, transitions, blur, zoom animations, desktop widgets (activeWidgets + per-widget blocks, widgets.tintOpacityEnabled), [[Media Mode
light Dark-mode schedule, Night Light, Anti-Flashbang, keyboard-backlight auto-off
wallpapers, wallpaperSelector Online wallpaper browser (Wallhaven/Unsplash), selector directories & sorting
panelFamily "ii", "tablet" or "waffle" — the active panel family
waffles Waffle-family options (bar, action center, calendar tweaks)
tablet [[Tablet family

Interface surfaces

Key Covers
bar Everything Bar: position, sizes, corner/group/background styles, expressive colors, layouts, auto-hide (autoHide.mode), per-widget styles (styles) & options (each widget's colorMode), tooltips/popups, Dynamic Island (floatingNotch, dynamicIsland)
sidebar Dashboard: position, shell mode (sidebarStyle), header, quick toggles (+ Android pages, quickToggles.androidTablet for the tablet family), quick sliders, corner-open, dashboardEntranceAnimations, bottomGroup.notesTab, AI/translator/booru sidebar modules
notes The Notes app: enable, defaultPaper, paperStrength, autosaveDelay
todo Task provider (local, ticktick, googleTasks), refresh interval, Google Tasks list
dock, dockToPanel Dock behavior, content, appearance, icon shapes
overview Overview: scaling, rows/columns, animations (animationStyle incl. none), previews, scrolling style, useAppDrawer
search, launcher Launcher: prefixes (prefix.*, incl. fileContent, typingTest, speedTest, ai), search modules and tools (modules.*), the [[typing test
cheatsheet Cheat Sheet tabs (keybinds, timetable, periodic table, amino acids, commands, Gmail)
overlay, osd, osk Widget overlay, on-screen display, on-screen keyboard (+ auto-show)
notifications Popup position/timeout/zoom, auto-DND on fullscreen, monitor pinning
lock Lock screen effects, security, notifications (privacy modes, filters)
crosshair, oledSaver, conflictKiller, windows, hacks Odds and ends: gaming crosshair, OLED blackout, conflict dialogs, titlebars, workaround delays

System & services

Key Covers
audio, sounds, soundcore Volume protection, UI sound events (+ custom sounds), Soundcore earbuds
battery, idle Thresholds, auto-suspend; Keep-awake durations & persistence
networking, vpn, tailscale, dnsOverTls User agent; VPN providers; Tailscale; DNS-over-TLS resolver
localsend, googleDrive LocalSend sharing; Google Drive integration
phone KDE Connect, contacts, scrcpy (+ App Mode), webcam, microphone
resources, appStats Resource-monitor polling; per-app usage & energy sampling
modes Modes & Routines: the definitions themselves plus banner, pills, grace period and game detection — see Modes & Routines
hyprland, interactions, tiling Hyprland options managed by the shell; scrolling behavior & touch gestures; Tiling Assistant zones/detection/co-resize
screenRecord, screenSnip, regionSelector Recorder backend & encoding; snip save path; selection hints, Circle-to-Search, annotation editor
media, lyricsService, musicRecognition, mediaDownloader Player filtering/priority, lyrics, songrec, yt-dlp downloader
ai AI assistant configuration ([[AI Integration
apps Default applications used by shell actions (terminal, task manager, update command…)
policies Which left-sidebar modules exist (AI / weeb / wallpapers / translator / player / phone)
time, calendar, language Clock/date formats, Pomodoro & alarms; calendar locale; UI language & translator
updates, update, settingsApp, tray Package update checking; fork updates (update.autoCheckInterval, update.aiSummary, aiSummaryMinCommits); settings-app behavior; tray options
userProfile Avatar, name, greeting
workSafety The public-network wallpaper/clipboard guard

The definitive, always-current reference is modules/common/Config.qml itself — every property is declared there with its default and, usually, a comment. When Settings doesn't expose something yet, it still works from the file.

The Settings app

30+ pages, registered in modules/common/SettingsPageRegistry.qml: Colors & Themes, Bar, Background, Interface & Fonts (which also holds the Shell family choice), Presets, Sidebars, Dock, Workspaces, Overview, Desktop Widgets, Dynamic Island, Overlays & OSD (the Notes app switch lives here), Modes & Routines, Screenshots & Recording, Notifications, Launcher, Dictation, Cheat Sheet, Windows, Window Tiling, Displays, Hyprland, Touch & Gestures, Tablet (listed only while the tablet family runs; Dock, Dynamic Island, Modes & Routines, Cheat Sheet and Window Tiling are hidden there), Media & Music, Language & Time, Weather, AI Assistant, Accounts & Backup, Sound & Alerts, Power & Battery, App Usage, Network, Devices & Phone, Privacy & Content, Lock Screen, About & Updates. User Profile (opened from the profile button in the Settings window) and Clipboard (opened from Privacy & Content) are hidden pages outside the sidebar.

The Settings search indexes all of it and jumps straight to (and highlights) the matching card — usually faster than remembering which page a toggle lives on.

Credentials

API keys and tokens (TickTick, Gmail, AI providers) belong in the system keyring, managed through the shell's keyring integration — with ii/.env as a plain-text fallback (see .env.example for the expected keys). Nothing secret is ever written into config.json, so your presets and exports stay shareable.

Related pages

← Back to Home

Clone this wiki locally