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 = "toowl_moonlight"
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`	`toowl_ink`	16 built-ins — see Themes for names.
`cursor_style`	`block`	`block`, `underline`, or `beam`.
`inactive_pane_dim`	`0.65`	Dim factor for unfocused split panes.
`tab_bar_placement`	`top`	`top` or `left`. A horizontal strip divides its width among the tabs, so pills shrink as more open; `left` gives each a fixed height and keeps labels readable. Toggle live with `Ctrl+Alt+V` (`⌘⌥V` on macOS).
`tab_bar_width`	`220`	Thickness of the vertical tab bar in logical px, clamped to 140–400. Ignored when the bar is on top.
`perch_side`	`auto`	`auto`, `left` or `right`. `auto` follows the tab bar — tabs on the left move the Perch right so the two never share a gutter.
`screenshot_button`	`true`	Show the `⎙` camera chip in the tab strip (captures the whole window to PNG). The screenshot keybinding still works when off.
`screenshot_destination`	`both`	`file`, `clipboard`, or `both`.
`screenshot_dir`	`~/Desktop`	Folder for `file`/`both` captures. `~` expands; created on demand. Editable inline in Settings (focus the row, `Enter` to edit, `Enter` to save, `Esc` to cancel).
`screenshot_sound`	`true`	Play a shutter sound on capture. Set false for a silent shot.

[scrollback]

Key	Default	Notes
`capacity`	`10000`	Off-screen rows retained. Mouse-wheel scrolls back into this buffer.

Tab groups

A tab group is a named, coloured band around a run of related tabs — collapse it and the whole run folds into one pill. Groups are not configured in config.toml; they're created from the running window and persist with the rest of your workspace state.

Action	Linux	macOS
Group the current tab	`Ctrl+Alt+G`	`⌘⌥G`
Collapse / expand the group	`Ctrl+Alt+Shift+C`	`⌘⌥⇧C`

A new group takes its name from the tab's current title and picks the next colour in the theme's group palette. Because the colour is stored as a palette index rather than a literal value, groups retint when you switch themes instead of clashing with the new one.

Membership is contiguous: a group is always one unbroken run of tabs, so it draws as a single band rather than a striped mess. Moving a tab into a group moves it next to that group's other tabs.

[paste]

Pasting into a terminal is the one place where clipboard content becomes an executed command. If a copied snippet ends in a newline, the shell runs it the instant it lands — no keypress, no chance to read it. toowl strips that trailing newline on pastes worth a second look, so the command sits on your prompt and waits for you to press Enter.

Key	Default	Notes
`strip_trailing_newline_on_dangerous`	`true`	Strip the trailing newline when the paste matches `dangerous_patterns`.
`strip_trailing_newline_on_multiline`	`true`	Same scrub for any paste containing an embedded newline — i.e. one that would run several commands without confirmation.
`dangerous_patterns`	see below	Case-sensitive substrings that flag a paste. Your entries are appended to the defaults, not a replacement for them.

The default pattern list:

[paste]
dangerous_patterns = [
  "sudo ", "rm -rf", "rm -fr", "curl ", "wget ",
  "| sh", "| bash", "chmod +x", "dd if=", ":(){:|:&};:",
]

This delays auto-execution; it does not block anything. The unstripped text still reaches the shell and Enter still runs it. It buys you the second needed to notice that what you pasted is not what you copied — which is the actual attack.

[recording]

Controls session recording — capturing the focused pane to an asciinema cast v2 .cast file.

Key	Default	Notes
`dir`	`~/Desktop`	Folder for `.cast` files. `~` expands; created on demand. Set empty (`""`) to fall back to `<data_dir>/toowl/recordings` (e.g. `~/.local/share/toowl/recordings` on Linux).

[search]

URLs for the right-click Web Search and Look Up actions on a text selection (also available in the command palette). {} is replaced with the URL-encoded selection.

Key	Default	Notes
`web_search_url`	`https://www.google.com/search?q={}`	Search-engine template for Web Search. Swap in DuckDuckGo, Kagi, etc.
`dictionary_url`	`https://en.wiktionary.org/wiki/{}`	Web dictionary for Look Up on Linux/Windows. macOS ignores this and opens the native Dictionary.app (`dict://`).

 [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.