Panama/docs/settings.md

Settings reference

Generated from config/dot/quickshell/config/PreferenceSchema.qml. Do not edit this file. Run quickshell/scripts/panama-settings-docs after changing the schema; a contract fails when this copy is stale.

183 settings across 37 groups. 77 of them are applied to the compositor and confirmed by reading the value back.

accessibility

Found on Accessibility.

Setting	Default	What it does
Magnifier magnifierFactor cursor:zoom_factor	1.0 ×	Magnifies the screen around the pointer. 1.00 × is off. Range 1.0–5.0.
Magnifier follows in steps magnifierRigid cursor:zoom_rigid	false	Moves the magnified view in increments rather than gliding with the pointer
High contrast highContrast	false	Increases contrast in applications that support it. Modern GTK applications read this from the desktop portal and restyle themselves; older ones need a high-contrast theme, which is not installed here.
Dim inactive windows dimInactive decoration:dim_inactive	false	Darkens every window except the focused one, so the active window is unmistakable
Dim amount dimStrength decoration:dim_strength	0.5	How much darker unfocused windows are. Range 0.05–0.9.
Color filter colorFilter	none	A whole-screen filter rendered by the compositor — grayscale, or a correction for one kind of color blindness. Costs nothing when off. Choices: None, Grayscale, Protanopia, Deuteranopia, Tritanopia.
Flash the screen for notifications visualAlerts	false	A single flash at the edges of every screen when a notification arrives that would ring the bell
Pointer size cursorSize	24 px	Applies to the compositor and to applications. Range 16–64.
Text size textScale	1.0	Scales interface text everywhere; 1.00 is the design size. Range 0.75–2.0.

agents

Found on System › Agents.

Setting	Default	What it does
Preferred agent preferredAgent	none	Who answers when the desktop offers to investigate something Choices: None, Claude Code, Codex.
Offer to diagnose crashes crashDiagnoseOffer	true	When a program dumps core, the notification carries a click that opens the preferred agent mid-investigation with the crash details in hand
Offer help when the shell fails to reload reloadFailureOffer	true	A broken change to the shell's own configuration offers the failing log to the agent
System Health hands off unrepairable checks healthAgentHandoff	true	A red check with no repair, or whose repair failed, grows an Ask-the-agent button carrying the check's snapshot
Launched agents approve their own tools agentAutoApprove	true	Investigations run without permission prompts. The diagnose skill still holds agents to reading rather than fixing, and root still goes through panama-sudo, reason and all
Collect Claude Code usage agentUsageClaude	true	Limits from Anthropic's usage endpoint, tokens from the local transcripts
Collect Codex usage agentUsageCodex	true	Limits over the Codex app-server, sessions from its local files
Refresh interval agentUsageRefreshMinutes	15 min	How often the usage collectors ask for fresh numbers, in minutes. Range 5–60.

appearance

Found on Appearance.

Setting	Default	What it does
Appearance colorScheme	dark	Light and dark share one identity, not two themes Choices: Dark, Light.
Accent color accentName	blue	Drives the focused window border, the bar hairline, and every active state Choices: Prism blue, Orchid, Teal, Green, Amber, Orange, Rose, Slate.

bar

Found on Shell › Bar.

Setting	Default	What it does
Bar text barTextTone	theme	Follow the theme, or force a light or dark tone for the wallpaper you actually use Choices: Follow theme, Light, Dark.
Bar text shadow barTextShadow	false	A soft dark halo under every glyph and label in the bar
Bar backdrop barBackdrop	false	A subtle scrim fading down from the top edge
Weather in the bar showWeatherWidget	true	Beside the clock, once a forecast has been fetched
Media in the bar showMediaWidget	true	Now playing, click to pause
Clipboard button showClipboardButton	true	The history stays on Super+V either way
Calendar countdown showCalendarCountdown	true	Appears in the bar fifteen minutes before an event

battery

Found on Power & Lock.

Setting	Default	What it does
Warn at batteryLowPercent	20 %	Mention the battery once it drops this low. Range 5–50.
Urgent at batteryCriticalPercent	5 %	Interrupt at this level, even during Do Not Disturb. Range 1–25.
At the urgent level batteryCriticalAction	suspend	What happens when the battery reaches the urgent threshold while discharging Choices: Suspend, Only warn.
Stop charging at batteryChargeLimit	100 %	Charging to less than full is easier on the battery over years. Range 50–100.

capture

Found on Applications › Screen Intelligence.

Setting	Default	What it does
Screenshot folder screenshotDir	Pictures/Screenshots	Where screenshots are saved. Relative to your home folder unless it starts with /
Recording folder recordingDir	Videos/Screencasts	Where screen recordings are saved. Relative to your home folder unless it starts with /
Recording audio recorderAudio	none	What screen recordings capture alongside the video Choices: No audio, System audio, Microphone.
Recording encoder recorderArgs	-c h264_vaapi -d auto	Hardware encoding keeps recording off the processor while gaming Choices: VAAPI H.264, VAAPI HEVC, CPU x264.

clock

Found on Shell › Bar.

Setting	Default	What it does
Show seconds showSeconds	true	Keep a precise clock in the center of the bar
Show weekday showWeekday	true	Include the abbreviated weekday before the date

controlCenter

Found on Shell › Control Center.

Setting	Default	What it does
Focus in Control Center ccShowFocus	true	The session row at the top of the panel
Home in Control Center ccShowHome	true	Your accessory shelf
Phone in Control Center ccShowPhone	true	Vitals and reach-it actions

datetime

Found on System › Date, Time & Region.

Setting	Default	What it does
24-hour time use24Hour	false	Use 18:30 instead of 6:30 PM

display

Found on Displays.

Setting	Default	What it does
Workspaces on the primary display only workspacesOnPrimaryOnly	false	Other screens keep one workspace of their own rather than switching along with it
Game-aware HDR autoHdr render:cm_auto_hdr	true	Hand HDR to fullscreen games while the desktop stays SDR
Variable refresh rate vrrPolicy misc:vrr	3	Matches the display's refresh rate to what is on screen Choices: Off, Always on, Fullscreen only, Fullscreen games.
Direct scanout directScanoutPolicy render:direct_scanout	2	Lets fullscreen content bypass compositing Choices: Off, Always on, Automatic.

dock

Found on Shell › Dock.

Setting	Default	What it does
Automatically hide the Dock dockAutohide	true	Reveal it at the bottom edge when a workspace is occupied
Position dockPosition	bottom	Which edge the Dock lives on Choices: Bottom, Left, Right.
Screens dockScreens	[]	Which displays show the Dock
Icon size dockIconSize	48 px	How large the Dock's application icons are drawn. Range 32–80.
Reveal delay dockRevealDelayMs	0 ms	Zero reveals the Dock the instant the pointer reaches the edge. Range 0–1000.
Hide delay dockHideDelayMs	250 ms	Prevents flicker when crossing between icons. Range 0–2000.
Pinned applications dockPinned	—	Applications that stay in the Dock whether or not they are running

edges

Found on Shell › Tiling.

Setting	Default	What it does
Resize by dragging the border resizeOnBorder general:resize_on_border	true	Drag a window's edge to resize it, instead of only with the keyboard
Border grab area borderGrabArea general:extend_border_grab_area	15 px	How far outside the border still counts as grabbing it. Larger is easier to hit. Range 0–40.
Show the resize cursor hoverIconOnBorder general:hover_icon_on_border	true	Change the pointer when it is over a resizable border
Snap distance between windows snapWindowGap general:snap:window_gap	10 px	How close two floating windows must be before they snap together. Range 0–60.
Snap distance to screen edges snapMonitorGap general:snap:monitor_gap	10 px	How close a floating window must be to an edge before it snaps to it. Range 0–60.
Snapping respects gaps snapRespectGaps general:snap:respect_gaps	false	Snapped windows keep the configured gap instead of touching

effects

Found on Appearance.

Setting	Default	What it does
Blur blurEnabled decoration:blur:enabled	true	Blur the desktop behind translucent surfaces
Blur radius blurSize decoration:blur:size	8	Larger is softer and costs more frame time. Range 1–20.
Blur passes blurPasses decoration:blur:passes	3	More passes look smoother and cost more frame time. Range 1–5.
Window shadows shadowEnabled decoration:shadow:enabled	true	Lift windows off the wallpaper with a soft shadow
Shadow size shadowRange decoration:shadow:range	20 px	How far the shadow spreads from the window edge. Range 0–60.
Hard-edged shadow shadowSharp decoration:shadow:sharp	false	A crisp shadow instead of a soft falloff
Shadow falloff shadowRenderPower decoration:shadow:render_power	3	How sharply the shadow fades out. Higher is tighter to the window. Range 1–4.
Focus glow glowEnabled decoration:glow:enabled	true	A faint halo behind the focused window
Glow size glowRange decoration:glow:range	8 px	Kept small deliberately: the gradient border is the signature. Range 0–30.
Animations animationsEnabled animations:enabled	true	Window, workspace, and panel motion

focus

Found on Notifications & Focus › Focus.

Setting	Default	What it does
Focus modes focusModes	—	What quiets this machine, and what turns it on
Focus session length focusDurationMinutes	45 min	How long a focus session runs before it ends itself. Range 5–180.

gaming

Found on Applications › Gaming.

Setting	Default	What it does
Use the performance power profile gamingPerformanceProfile	true	Switches while a game runs and switches back when it exits
Say when Game Mode engages gamingNotifyOnStart	false	A notification when a game requests it, which is otherwise invisible

idle

Found on Power & Lock.

Setting	Default	What it does
Turn the screen off after screenBlankMinutes	5 min	Blanks the display; nothing is locked yet. Range 0–120.
Lock the screen after lockMinutes	10 min	Counted from when the session went idle, not from blanking. Range 0–240.
Suspend after suspendMinutes	0 min	This is a desktop, so Panama ships with automatic suspend off. Range 0–480.
Lock before sleeping lockOnSleep	true	Requires your password when the machine wakes

idleBattery

Found on Power & Lock.

Setting	Default	What it does
Turn the screen off after screenBlankMinutesBattery	2 min	On battery. Blanks the display; nothing is locked yet. Range 0–120.
Lock after lockMinutesBattery	5 min	On battery. Requires your password to get back in. Range 0–240.
Suspend after suspendMinutesBattery	20 min	On battery, sleeping is what makes the charge last. Range 0–480.

input

Found on Input › Keyboard.

Setting	Default	What it does
Keyboard layout keyboardLayout input:kb_layout	us	XKB layout name, or a comma-separated list to switch between
Layout variant keyboardVariant input:kb_variant	—	XKB variant, such as dvorak or colemak. Empty for the standard layout
Keyboard options keyboardOptions input:kb_options	caps:escape_shifted_capslock	XKB options, such as compose:ralt to make right Alt a compose key
Num Lock on login numlockByDefault input:numlock_by_default	true	Turn Num Lock on when the session starts
Repeat delay keyRepeatDelay input:repeat_delay	500 ms	How long a key is held before it starts repeating. Range 150–1000.
Repeat rate keyRepeatRate input:repeat_rate	33 /s	How many characters a second a held key produces. Range 5–100.

lockAppearance

Found on Appearance.

Setting	Default	What it does
Background lockBackgroundMode	screenshot	What appears behind the lock screen Choices: Blurred desktop, Current wallpaper, Solid color.
Background blur lockBlurLevel	3	Softens what is behind the password field. Range 0–5.
Show clock lockShowClock	true	Use the desktop's 12 or 24-hour format
Show date lockShowDate	true	Show the weekday and full date
Show user name lockShowUser	true	Identify the signed-in account
Hide password field until typing lockFadeOnEmpty	false	Keep the empty field out of the way

master

Found on Shell › Tiling.

Setting	Default	What it does
Master area size masterFactor master:mfact	0.55	How much of the screen the master window takes. Range 0.1–0.9.
Master area position masterOrientation master:orientation	left	Which side of the screen the master window occupies Choices: Left, Right, Top, Bottom, Center.
New windows become masterNewStatus master:new_status	slave	Whether a new window takes the master area or joins the stack Choices: The master window, Part of the stack, Whatever the focused window is.
Add new windows at the top masterNewOnTop master:new_on_top	false	New stack windows go above the others rather than below

multitasking

Found on Shell › Tiling.

Setting	Default	What it does
Tiling layout windowLayout general:layout	dwindle	Dwindle splits the focused window; master keeps one large window beside a stack Choices: Dwindle, Master and stack.
Keep split direction preserveSplit dwindle:preserve_split	true	New windows follow the split of the window they replace, instead of always halving the longer side
New windows open forceSplit dwindle:force_split	0	Where a new window lands relative to the one that was focused Choices: Where the pointer is, Always left or above, Always right or below.
Snap floating windows windowSnapping general:snap:enabled	true	Floating windows stick to screen edges and to each other as you drag them

nightLight

Found on Displays.

Setting	Default	What it does
Night Light nightLightEnabled	false	Shift the display warmer to reduce blue light
Schedule automatically nightLightAutomatic	false	Turn Night Light on and off at the scheduled hours
Color temperature nightLightTemperature	3500 K	Lower is warmer. Range 2000–6500.
Turns on at nightLightFrom	17.0	Only used when Night Light follows a schedule. Range 0–23.5.
Turns off at nightLightTo	10.0	A time earlier than the start simply means the next morning. Range 0–23.5.

notices

Found on Shell › Tiling.

Setting	Default	What it does
Hyprland wallpaper hyprlandLogo misc:disable_hyprland_logo	false	The stock background Hyprland draws when no wallpaper is set
Splash text hyprlandSplash misc:disable_splash_rendering	false	The line of text Hyprland renders over the stock background
Update announcements hyprlandUpdateNews ecosystem:no_update_news	false	The window Hyprland opens after an update to describe what changed
Donation reminders hyprlandDonationNag ecosystem:no_donation_nag	false	The prompt Hyprland shows twice a year asking for support

notifications

Found on Notifications & Focus › Notifications.

Setting	Default	What it does
Notification duration notificationTimeoutMs	5000 ms	How long ordinary notification banners remain visible. Range 1000–30000.
Critical notification duration notificationTimeoutCriticalMs	0 ms	Zero keeps critical notification banners visible until dismissed. Range 0–60000.
Notification history notificationHistoryLimit	100	Maximum notifications retained in the notification center. Range 10–500.
Visible banners maxVisibleToasts	4	Maximum notification banners shown at once. Range 1–8.
Critical alerts break through criticalBreaksThrough	false	Show critical notifications as banners even while Do Not Disturb is on

pointer

Found on Input › Mouse & Touchpad.

Setting	Default	What it does
Pointer focus followMouse input:follow_mouse	1	What moving the pointer does to which window is focused Choices: Click to focus, Focus follows pointer, Pointer detached, Pointer fully separate.
Pointer speed pointerSensitivity input:sensitivity	0.0	Zero is flat, unaccelerated response. Range -1.0–1.0.
Hide pointer after cursorInactiveTimeout cursor:inactive_timeout	4 s	Seconds of stillness before the pointer fades out; 0 never hides it. Range 0–60.
Natural scrolling naturalScroll input:natural_scroll	false	Content follows the direction of your fingers, as on a phone
Acceleration accelProfile input:accel_profile	flat	Flat moves the pointer the same distance however fast you move Choices: Flat, Adaptive.
Scroll speed scrollFactor input:scroll_factor	1.0	Multiplies how far one notch of the wheel scrolls. Range 0.1–4.0.
Left-handed leftHanded input:left_handed	false	Swap the primary and secondary buttons
Middle-click paste middleClickPaste misc:middle_click_paste	true	Paste the primary selection in GTK and native Wayland applications
Focus after closing focusOnClose input:focus_on_close	0	Which window takes keyboard focus when the focused one goes away Choices: Next in the stack, Under the pointer, Most recently used.
Scroll method scrollMethod input:scroll_method	—	How a pointing device turns movement into scrolling Choices: Two fingers, Along the edge of the touchpad, While a button is held, Never scroll.
Scroll button scrollButton input:scroll_button	0	Which button is held to scroll, as an evdev code; 0 lets the device choose. Range 0–300.
Hide pointer while typing cursorHideWhileTyping cursor:hide_on_key_press	false	The pointer vanishes on the next keystroke and returns when you move it
Jump pointer to the focused display cursorWarpOnWorkspaceChange cursor:warp_on_change_workspace	false	Moves the pointer to the last focused window after switching workspace

power

Found on Power & Lock.

Setting	Default	What it does
Pressing the power button powerButtonAction	menu	The system ignores the key; Panama decides — so a bumped button never yanks the plug Choices: Shows the power menu, Suspends, Powers off (two-press), Does nothing.

search

Found on Applications › Applications.

Setting	Default	What it does
Web search engine webSearchUrl	https://duckduckgo.com/?q=	Where the launcher's web search sends a query; the search text is appended

sound

Found on Sound.

Setting	Default	What it does
Over-amplification overAmplification	false	Lets the volume slider go to 150% — louder, at the cost of distortion on some hardware
Volume-change blip volumeChangeBlip	true	A short click each time the volume keys move the output level

themes

Found on Appearance.

Setting	Default	What it does
Pointer theme cursorTheme	oreo_blue_cursors	The pointer design used by applications and Hyprland
Application icons iconTheme	Adwaita	The icon set used by GTK applications

titlebar

Found on Appearance.

Setting	Default	What it does
Button side titlebarButtonSide	right	Place application titlebar buttons on the left or right Choices: Left, Right.
Titlebar on Panama windows panamaTitlebar	true	Hide it and the window is pure Hyprland — Super+Q closes, Super+drag moves

touchpad

Found on Input › Mouse & Touchpad.

Setting	Default	What it does
Tap to click touchpadTapToClick input:touchpad:tap-to-click	true	A tap counts as a click without pressing down
Natural scrolling touchpadNaturalScroll input:touchpad:natural_scroll	true	Content follows the direction of your fingers
Disable while typing touchpadDisableWhileTyping input:touchpad:disable_while_typing	true	Ignore the touchpad briefly after a keystroke, so a palm cannot move the pointer
Scroll speed touchpadScrollFactor input:touchpad:scroll_factor	1.0	Multiplies how far a two-finger scroll travels. Range 0.1–4.0.
Drag lock touchpadDragLock input:touchpad:drag_lock	0	Keeps a tap-and-drag active when you lift a finger mid-drag Choices: Off, On, On, until you tap again.
Middle-click by pressing both buttons touchpadMiddleButtonEmulation input:touchpad:middle_button_emulation	false	Pressing left and right together acts as a middle click
Two-finger right-click touchpadClickfinger input:touchpad:clickfinger_behavior	false	One, two, or three fingers pressing down give left, right, and middle click, instead of clicking by which part of the pad you press
Tap and drag touchpadTapAndDrag input:touchpad:tap-and-drag	true	A tap followed straight away by a tap-and-hold starts a drag, with nothing pressed down
Swipe distance swipeDistance gestures:workspace_swipe_distance	300 px	How far a three-finger swipe must travel to change workspace. Range 100–800.
Natural swipe direction swipeInvert gestures:workspace_swipe_invert	true	Swiping left moves to the workspace on the right, as content follows your fingers

typography

Found on Appearance.

Setting	Default	What it does
Interface font interfaceFont	Adwaita Sans	Used for every piece of text in the shell
Icon font iconFont	VictorMono Nerd Font	Draws the shell's glyphs, so it must be a Nerd Font
Interface text size interfaceFontSize	13 px	The base size the rest of the shell's type scales from. Range 10–18.
Application font applicationFont	Adwaita Sans	Used by menus, controls, and labels in applications
Application text size applicationFontSize	11 pt	The base text size used by applications. Range 6–32.
Document font documentFont	Adwaita Sans	Used for document content when an application follows the system choice
Document text size documentFontSize	12 pt	The default text size for document content. Range 6–32.
Monospace font monospaceFont	VictorMono Nerd Font	Used by terminals, editors, and code fields that follow the system choice
Monospace text size monospaceFontSize	10 pt	The default text size for terminals and code. Range 6–32.
Font hinting fontHinting	slight	How strongly text aligns to the pixel grid Choices: None, Slight, Medium, Full.
Text smoothing fontAntialiasing	rgba	How application text softens its edges Choices: None, Grayscale, Subpixel.

vitals

Found on Shell › Bar.

Setting	Default	What it does
Processor showCpu	true	Show processor usage beside the workspace indicator
Memory showMemory	true	Show memory usage beside the workspace indicator
Graphics showGpu	true	Show graphics usage beside the workspace indicator
Battery showBattery	true	Show the charge level in the bar, on machines that have a battery
Battery percentage showBatteryPercent	false	Show the exact number beside the battery icon
Agent usage showAgentUsage	false	Show how much of the busiest agent subscription has been used, beside the other vitals
Vitals refresh vitalsIntervalMs	2000 ms	How often processor, memory, and graphics usage update. Range 500–10000.

wallpaper

Found on Appearance.

Setting	Default	What it does
Wallpaper folder wallpaperDir	Pictures/Wallpapers	Where the picker looks. Relative to your home folder unless it starts with /
Wallpaper wallpaperPath	—	Shown on every output
Wallpaper mode wallpaperMode	single	Use one image, rotate a collection, or choose per display Choices: Single, Slideshow, Per display.
Change background every wallpaperIntervalMinutes	30 min	Time between slideshow images. Range 5–1440.
Shuffle wallpaperShuffle	true	Show every selected image before repeating
Video wallpaper folder videoWallpaperDir	Videos/Wallpapers	Where the picker looks for videos. Relative to your home folder unless it starts with /
Pause video wallpaper on battery videoWallpaperPauseOnBattery	true	Freezes on the current frame and resumes on wall power

weather

Found on Home › Overview.

Setting	Default	What it does
Temperature unit temperatureUnit	fahrenheit	Choose Fahrenheit or Celsius for the weather card Choices: Fahrenheit, Celsius.
Weather refresh weatherRefreshMinutes	20 min	How often Panama updates the current conditions. Range 5–120.

windows

Found on Appearance.

Setting	Default	What it does
Inner gaps gapsIn general:gaps_in	5 px	Space between neighboring tiled windows. Range 0–40.
Outer gaps gapsOut general:gaps_out	10 px	Space between the tiled area and the screen edge. Range 0–80.
Border width borderSize general:border_size	2 px	Thickness of the gradient border on the focused window. Range 0–10.
Corner radius windowRounding decoration:rounding	18 px	Matches the shell's popover radius so windows and panels agree. Range 0–40.
Unfocused window opacity inactiveOpacity decoration:inactive_opacity	1.0	Fade windows that do not have focus. Range 0.5–1.0.
Focused window opacity activeOpacity decoration:active_opacity	1.0	Fade even the focused window; 1.0 is fully opaque. Range 0.5–1.0.
Fullscreen opacity fullscreenOpacity decoration:fullscreen_opacity	1.0	Applied instead of the focused opacity when a window is fullscreen. Range 0.5–1.0.
Corner shape roundingPower decoration:rounding_power	2.0	2 is a circular corner; higher values approach a squircle. Range 2.0–10.0.

workspaces

Found on Shell › Workspaces.

Setting	Default	What it does
Switch back and forth workspaceBackAndForth binds:workspace_back_and_forth	false	Selecting the workspace you are already on returns you to the previous one
Wrap around at the ends allowWorkspaceCycles binds:allow_workspace_cycles	false	Moving past the last workspace continues from the first
Let applications take focus focusOnActivate misc:focus_on_activate	false	An application asking for attention is switched to, rather than only highlighted
Hide the terminal that launched a window windowSwallow misc:enable_swallow	false	A terminal disappears while an application started from it is open, and returns when it closes
Pointer changes active display mouseMoveFocusesMonitor misc:mouse_move_focuses_monitor	true	Moving the pointer to another display makes it the active one