Home

wam-shell configuration

Everything lives in one TOML file. The shell looks for it in this order (first hit wins):

1. $XDG_CONFIG_HOME/wam-shell/config.toml
2. ~/.config/wam-shell/config.toml
3. config-override.toml in the repo
4. config.toml in the repo

An empty file is valid — every option falls back to its documented default, and an invalid value is reported on stderr and replaced with the default. Section keys can also be set flat at the top level; the section wins when both are set.

Credentials never go in this file: one .env file per service in ~/.config/wam-shell/ (github.env, todoist.env, protonmail.env, google.env, harvest.env, chmod 600), or the matching environment variables. Each page below that needs credentials says so.

Pages

Panels and bar widgets

• Panels — bar_monitors, panel geometry, [[panel]] blocks
• Workspaces
• Tray
• Media
• Screen share — ignore-list for the media/Harvest privacy mask
• Net stats — cumulative bandwidth totals
• Prayer times — local prayer times pill on the bar
• Harvest — time tracking widget (needs a token)

Quick settings

• Quick settings — popup layout, audio meters, battery, avatar, Bluetooth
• Sleep timer
• Idle inhibit (keep awake)
• Night light — hyprsunset, hyprland only

Notifications and service integrations

• Notifications — banners and the center
• GitHub — needs a token
• Todoist — needs a token
• ProtonMail — needs ProtonMail Bridge
• YouTube — Google OAuth
• Calendar — Google Calendar in the clock popover

Look and feel

• General — instance name, session override, OS icon, theme
• Appearance — dark/light themes, density
• OSD — on-screen display