Config Reference

Config Reference

Your config lives at ~/.config/tuicc/config.toml. If it's missing, tuicc creates it by copying the packaged default the first time it runs — you always have a real, editable file with sensible defaults, never a hidden in-memory fallback.

If you add or edit sections here and tuicc throws a KeyError on startup, your existing config is probably out of date with a newer packaged default (a new section was added since your config was generated). Delete ~/.config/tuicc/config.toml and run tuicc again to regenerate it with the current defaults, then reapply your customizations. There's no automatic migration yet — this is a known, not-yet-solved gap.

---

[layout]

[layout]
preset = 1

Key	Type	Description
preset	integer	Which layout preset to use. Presets live in src/tuicc/presets/<N>.toml and define where each module sits on screen, as ratios (0..1) of the whole terminal — independent of your actual terminal size.

Presets are plain TOML, not hidden Python constants — open presets/1.toml to see (and copy) the format if you want to build your own layout.

---

[navigation]

[navigation]
tab_order = "columns_first"

Key	Type	Description
tab_order	"columns_first" | "rows_first"	Order Tab cycles through items within a module. columns_first: top-to-bottom within a column, then next column. rows_first: left-to-right within a row, then next row.

---

[wm]

[wm]
provider = "sway"

Key	Type	Description
provider	string	Which WM provider to use. Built in: sway, i3. See Writing a WM Provider to add your own — once registered in providers/registry.py, its name becomes valid here.

---

[theme]

[theme]
background = "inherit"
border = "white"
border_selected = "cyan"
text = "white"
accent = "cyan"
selected = "blue"
warning = "yellow"
urgent = "red"

Every role accepts one of four formats:

Format	Example	Notes
"inherit"	"inherit"	Use the terminal's own color for this role — curses's default color (-1). Typically used for background.
Named color	"cyan"	One of: black, red, green, yellow, blue, magenta, cyan, white.
Hex string	"#7dd3fc"	Approximated to the nearest color in curses's 256-color cube — not exact true-color, since curses doesn't support that directly.
RGB list	[125, 211, 252]	Same approximation as hex, different input format. "#7dd3fc" and [125, 211, 252] resolve to the identical color.

Roles

Role	Used for
background	Overall background. Almost always "inherit".
border	Default box outline color for modules and items.
border_selected	Outline color for the currently active module (the one Shift+Tab last landed on) — see Keybindings.
text	Default, unselected text.
accent	Highlight color — currently used for floating window boxes in the preview.
selected	Text/border color for the currently selected item within a module.
warning	Reserved for non-critical alerts. Not yet used by any built-in module.
urgent	Critical/destructive emphasis — used for the quick-actions confirm prompt.

---

[navigation.keys]

[navigation.keys]
left = "Left"
right = "Right"
up = "Up"
down = "Down"
tab = "Tab"
switch_module = "Shift+Tab"
confirm = "Enter"
quit = "q"

Key	Description
left, right, up, down	Move selection within the active module (predictable left-to-right order for preview windows), or between modules when there's nowhere further to go in the current one.
tab	Cycle through items in the currently active module.
switch_module	Switch which module is "active" (cycles through the modules in your current layout preset).
confirm	Activate the selected item — switch workspace, focus a window, or run a quick action (prompting first if the action has confirm = true).
quit	Exit tuicc without doing anything (or cancel a pending confirm prompt).

Accepted values: named specials (Left, Right, Up, Down, Tab, Shift+Tab, Enter, Escape, Space) or any single character (e.g. "h", "j", "k", "l" for vim-style bindings). Uppercase letters work as an implicit Shift — curses reports "A" and "a" as different key codes on their own.

The confirm dialog's y/n keys are still hardcoded, separate from this table — see Keybindings for the current state of that gap.

---

[[quick_actions.action]]

[[quick_actions.action]]
label = "Lock"
icon = ""
command = "swaylock"
confirm = false

[[quick_actions.action]]
label = "Shutdown"
icon = ""
command = "systemctl poweroff"
confirm = true

Add as many [[quick_actions.action]] blocks as you want — each one is a separate entry in the quick-actions module.

Key	Type	Required	Description
label	string	yes	Shown in the UI.
command	string	yes	Shell command run (via subprocess.Popen(..., shell=True)) when you select the action and press confirm.
icon	string	no (defaults to "")	Shown before the label, if set.
confirm	bool	no (defaults to false)	If true, pressing confirm shows a Y/N prompt in place of the action list instead of running the command immediately. Use this for anything destructive.

Commands run through your shell, so anything you could type in a terminal works — including chained commands, though keep in mind tuicc doesn't wait for or report on the command's success/failure; it exits immediately after launching it.