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`	`JetBrains Mono`	Bundled with the binary on every platform, so the default looks identical everywhere. Override with any installed 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`	`beam`	`block`, `underline`, or `beam`.
`cursor_blink`	`true`	Pulse the cursor's opacity. Set false for a steady cursor. Also on First Light's Small comforts step and in Settings.
`inactive_pane_dim`	`0.50`	Dim factor for unfocused split panes. 1.0 = no dim, 0.85 subtle, 0.55 strong.
`tab_bar_placement`	`top`	`top` or `left`. Full layout behaviour — chrome, scrolling, previews, window drag, keys — is on Layouts. Toggle live with `Ctrl+Alt+V` (`⌘⌥V` on macOS) or Settings → Tab layout.
`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.
`tab_hover_preview`	`true`	Show a live preview when hovering a background tab. Vertical layout parks the card to the right of the rail. Also in Settings.
`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.

[hints]

Key	Default	Notes
`enabled`	`true`	Occasional one-line tips in the bottom-right about commands you have not used yet. At most three per session, minutes apart, and only while the terminal is quiet and that corner is empty — a hint never covers output or lands on top of a running command. Each one appears once ever, not once per launch, so they retire on their own. Click a hint or start typing to send it away early. The chord shown is read from your live keymap, so a rebind is reflected immediately. Set false to turn them off — the same switch as Settings → Hints.

[onboarding]

Key	Default	Notes
`completed`	`false`	Set true once First Light has been offered — whether you walked to the end or pressed `Esc`. Set it back to false (or run Run setup again in Settings) to see the flow again.

[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`
Ungroup the current tab	`Ctrl+Alt+Shift+G`	`⌘⌥⇧G`
Collapse / expand the group	`Ctrl+Alt+Shift+C`	`⌘⌥⇧C`

Pressing the group chord on a tab that sits beside an existing group adds it to that group — this is how you build a group of more than one tab from the keyboard. Only a tab with no grouped neighbour starts a new group, and that is when the name and colour are chosen: the name comes from the tab's current title, the colour is the next one 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.

While a group is collapsed it shows a single pill, and tab switching treats it as one stop — Ctrl+Tab steps onto the group rather than through its hidden members, and arriving expands it. You never land on a tab you cannot see.

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