Documentation
Configuration
Edit ~/.config/toowl/config.toml — every field is optional and hot-reloads.
Config lives at ~/.config/toowl/config.toml (or
%APPDATA%\toowl\config.toml on Windows). toowl watches the file
with a 150ms debounce and applies changes without restart. Saves are atomic
(write temp + rename) so the watcher never sees a half-written file.
Minimal example
[appearance]
theme = "tokyo_night"
opacity = 0.88
font_size = 15.0
cursor_style = "block"
[scrollback]
capacity = 10000
[keybindings]
"ctrl+shift+q" = "quit"
[appearance]
| Key | Default | Notes |
|---|---|---|
font_family | monospace | System monospace, or a specific face name. |
font_size | 14.0 | Logical point size; multiplied by display scale factor. |
opacity | 1.0 | Window transparency. 0.85–0.92 is a sweet spot. |
theme | catppuccin_mocha | 17 built-ins — see toowl-theme for names. |
cursor_style | block | block, underline, or beam. |
inactive_pane_dim | 0.65 | Dim factor for unfocused split panes. |
[scrollback]
| Key | Default | Notes |
|---|---|---|
capacity | 10000 | Off-screen rows retained. Mouse-wheel scrolls back into this buffer. |
[keybindings]
Combo strings use + separators. Modifiers:
ctrl, shift, alt, super
(also command, cmd, meta, opt).
Special keys: enter, tab, escape,
pageup, pagedown, home, end,
f1–f12, arrow keys.
Action names match the Action enum in snake_case — see the Keybindings page for defaults.
[plugins.<id>]
[plugins.claude]
enabled = true
[plugins.my-feather]
enabled = false
Toggle Feathers without restart. Interactive enable/disable in the settings UI is planned.
Workspace state
Tab layout and pane tree persist to ~/.config/toowl/state.json
and restore on launch. Legacy config dirs are migrated automatically on first run.