Configuration
Tsumiki uses TOML for configuration.
Config Files
Section titled “Config Files”config.toml: widgets, layout, modules, runtime behavior.tsumiki.schema.json: schema source of truth.
Quick Start Example
Section titled “Quick Start Example”"$schema" = "./tsumiki.schema.json"
[general]debug = falseauto_restart = truemulti_monitor = false
[layout]left_section = ["workspaces", "window_title"]middle_section = ["date_time"]right_section = ["@group:0", "system_tray", "volume", "battery"]
[[widget_groups]]widgets = ["updates", "battery"]spacing = 4style_classes = ["bordered"]
[[collapsible_groups]]widgets = ["ocr", "screenshot", "recorder"]spacing = 4label_format = ""tooltip = "Utility Tools"style_classes = ["utility-tools"]
[modules.bar]layer = "top"location = "top"auto_hide = falseauto_hide_timeout = 3000
[widgets.workspaces]count = 10hide_unoccupied = true
[widgets.date_time]date_format = "%b %d %H:%M"
[widgets.volume]tooltip = truestep_size = 5
[widgets.battery]label = truetooltip = trueMain Sections
Section titled “Main Sections”general
Section titled “general”Global behavior such as debug mode, auto reload, and multi-monitor controls.
| Key | Type | Default | Description |
|---|---|---|---|
debug |
bool | false |
Enable verbose logging |
auto_restart |
bool | true |
Automatically restart on crash |
restart_delay |
int | 1500 |
Delay before restart (ms) |
multi_monitor |
bool | false |
Per-monitor bar instances |
tooltips |
bool | true |
Enable widget tooltips |
check_updates |
bool | false |
Check for Tsumiki updates |
monitor_styles |
bool | true |
Watch and reload SCSS changes |
layout
Section titled “layout”Controls widget placement in bar sections:
left_sectionmiddle_sectionright_section
Each value is a list of widget IDs. Use @group:N (zero-based index) for widget groups:
[layout]left_section = ["@group:0", "window_title"]middle_section = ["date_time"]right_section = ["@group:1", "system_tray", "power"]Available reference types:
| Reference | Example | Description |
|---|---|---|
| Widget name | "workspaces" |
Direct widget reference |
@group:N / @group:id |
"@group:0" / "@group:workspaces-group" |
Widget group by index or string id |
@collapsible:N / @collapsible:id |
"@collapsible:0" / "@collapsible:utility-tools" |
Collapsible group by index or string id |
@custom_widget:N / @custom_widget:id |
"@custom_widget:0" / "@custom_widget:volume" |
Custom widget by index or string id |
modules
Section titled “modules”Enables and configures larger UI modules such as:
| Module | Key | Description |
|---|---|---|
| Bar | modules.bar |
Panel bar position and layer |
| Notification | modules.notification |
Desktop notification system |
| Dock | modules.dock |
Application dock with intellihide |
| Overview | modules.overview |
Workspace exposé view |
| OSD | modules.osd |
On-screen display for volume, etc. |
| Launcher | modules.launcher |
Application search & launch, slash commands (/calc, /translate) |
| Desktop Clock | modules.desktop_clock |
Decorative desktop clock |
| Desktop Quotes | modules.desktop_quotes |
Inspirational quote overlay |
| Desktop Notes | modules.desktop_notes |
Sticky notes on the desktop |
| Screen Corners | modules.screen_corners |
Hot corners |
| Cheatsheet | modules.cheatsheet |
Keybinding reference |
| Activate Linux | modules.activate_linux |
Window activation hint |
Example dock configuration:
[modules.dock]enabled = truebehavior = "intellihide"show_when_no_windows = falseicon_size = 40See the Modules Reference for complete options.
widgets
Section titled “widgets”Per-widget settings (icons, labels, thresholds, polling intervals, behavior flags).
Over 45 widgets are available. See the complete Widgets Reference for every option.
Common widgets include:
| Widget | Description |
|---|---|
workspaces |
Virtual desktop switcher |
window_title |
Active window title |
date_time |
Date/time display |
system_tray |
System tray icons |
volume |
Audio volume control |
battery |
Battery status |
cpu |
CPU usage monitor |
memory |
Memory usage monitor |
network_usage |
Network speed monitor |
weather |
Weather conditions |
power |
Power menu (shutdown, etc.) |
quick_settings |
Quick settings panel |
Workspace Styles
Section titled “Workspace Styles”The workspace widget supports six display styles:
[widgets.workspaces]style = "numbered" # "numbered" | "pill" | "icon" | "minimal" | "underline" | "bubble"- numbered — Numbers with pill-shaped active indicator (default)
- pill — Minimal pill indicators without text
- icon — Custom Nerd Font icons per workspace
- minimal — Clean, understated with subtle background
- underline — Active workspace gets a bottom border accent, no background
- bubble — Circular bubble containers
See the Workspaces Widget page for full details.
Widget Groups & Collapsible Groups
Section titled “Widget Groups & Collapsible Groups”Group widgets together with shared spacing and styling:
[[widget_groups]]widgets = ["updates", "battery"]spacing = 4style_classes = ["bordered"]Groups can optionally use a hover-revealer that hides children until hovered:
[[widget_groups]]widgets = ["updates", "battery"]spacing = 4style_classes = ["bordered"]hover_reveal = truereveal_duration = 300revealer_icon = ""| Key | Type | Default | Description |
|---|---|---|---|
hover_reveal |
bool | false |
Hide children behind a revealer that expands on hover |
reveal_duration |
int | 500 |
Transition duration in milliseconds |
revealer_icon |
string | |
Nerd Font icon shown when the group is collapsed |
Collapsible groups hide widgets behind a toggle:
[[collapsible_groups]]widgets = ["ocr", "screenshot", "recorder"]spacing = 4label_format = ""tooltip = "Utility Tools"style_classes = ["utility-tools"]The toggle button is one label, driven by label_format like every other panel widget, with the glyph written straight into the string: literal text is kept, so " Tools" puts a caption next to the glyph. The old show_icon / label keys are no longer read.
Reference groups in layout with @group:N (numeric index) or @group:id (string id).
Each group entry can include an optional id field for human-readable references:
[[widget_groups]]id = "workspaces-group"widgets = ["workspaces", "window_title"]spacing = 2style_classes = ["compact"]
[[collapsible_groups]]id = "utility-tools"widgets = ["ocr", "screenshot", "recorder"]spacing = 4label_format = ""tooltip = "Utility Tools"style_classes = ["utility-tools"]
[layout]left_section = ["@group:workspaces-group"]right_section = ["@collapsible:utility-tools"]Matugen Theme Generation
Section titled “Matugen Theme Generation”Auto-generate color palettes from your wallpaper:
[matugen]enabled = truewallpaper = "~/Pictures/wallpaper.jpg"scheme = "scheme-tonal-spot"mode = "dark"contrast = 0.0See Theming with Matugen for details.
Recommended Workflow
Section titled “Recommended Workflow”- Start from
example/config.toml. - Keep your custom file small and focused.
- Change one section at a time.
- Restart with
./tsumiki.sh -startto validate behavior.
Reference Source
Section titled “Reference Source”This page is a practical overview.
For complete key definitions and defaults, see the Widgets Reference and Modules Reference.
For the complete schema, use tsumiki.schema.json in the project root.