Settings and themes

Settings live in ~/.config/insensical/config.toml ($XDG_CONFIG_HOME/insensical/config.toml if that's set; INSENSICAL_CONFIG_DIR overrides both). You don't need to create anything. Without the file, or without the directory, the defaults apply.

isc config prints a complete file. It has every setting at its default, with a note on each and the values it can take. A setting with no default appears as a line to uncomment. Both keymaps are there too, with every key:

isc config > ~/.config/insensical/config.toml

Here's an example:

theme = { light = "paper", dark = "fjord" }   # or "ghostty", or "ghostty:Tokyo Night"
font-family = "JetBrainsMono Nerd Font"
font-size = 12
shell = "fish"
keymap = "leader"

The settings table is in the reference.

When a change applies

• Saved changes apply within a second. You don't need to restart or press a key. The window checks the file once a second.
• The daemon reads shell and keep-scrollback when the next pane starts. A pane that's already open keeps the values it was opened with.
• The window checks that it can find the program shell names, either by its path or on the window's own PATH. If it can't, it says so in the top bar.
• The daemon reads clipboard each time a program asks, so a change applies right away.
• Changing sidebar, pane-header, density or pane-gap changes how much room terminals have, so they're resized.

When the file is wrong

• One unreadable line voids the whole file. A misspelt key, a value of the wrong type or broken TOML shows in the top bar with its line number, and every setting falls back to its default until you fix the line. An unknown key is an error. It isn't ignored.
• A value that can be read but not used is reported, and only that setting falls back. That covers a font size of 500, a theme that doesn't exist, a leader that isn't a key, and a shell that isn't a program.
• The top bar shows only the first problem. All of them are printed to the window's standard error.

Themes

A theme is a terminal's colours: foreground, background, the sixteen named colours, and optionally cursor and selection. The UI's colours are derived from them, so any terminal theme styles the whole application. UI text is always shifted in lightness until it's readable.

A theme name is looked up in this order:

Name	Means
ghostty	The theme named in Ghostty's own configuration for the desktop's current appearance
ghostty:Name	The Ghostty theme with that name
anything else	themes/NAME.toml beside the settings file, then the built-in fjord and ember (dark) and paper (light)

• If theme isn't set, you get fjord when the desktop is dark and paper when it's light.
• A pair, { light = "…", dark = "…" }, follows the desktop's appearance as it changes.
• Ghostty's themes are read from where Ghostty keeps them: ~/.config/ghostty/themes, /usr/share/ghostty/themes, /usr/local/share/ghostty/themes, and inside Ghostty.app on macOS. Nothing is copied.
• Without Ghostty installed, ghostty and ghostty:… are errors.
• When you save a theme file that's in use, it applies within a second.
• Only the theme comes from Ghostty. Its font, font size, font style, padding, opacity, blur, cursor style and command aren't used.
• The UI's colours always come from the terminal theme, and nothing is translucent.

A theme file

~/.config/insensical/themes/<name>.toml:

name = "Fjord"

[terminal]
foreground = "#d0d4dc"
background = "#101216"
cursor = "#d0d4dc"        # optional: the foreground if left out
selection = "#7fd1c7"     # optional: the accent if left out
palette = [               # the sixteen named colours: eight normal, then eight bright
    "#1b1e25", "#f0706a", "#7fd18b", "#f0b35a", "#6fa8ff", "#c58fe8", "#7fd1c7", "#c5cad3",
    "#4c5464", "#ff8f8a", "#9be3a5", "#ffc978", "#93beff", "#d9aef5", "#9fe6dc", "#eef1f6",
]

Whether a theme is light or dark is worked out from its background, unless appearance = "light" or "dark" at the top of the file sets it explicitly.

• A theme only needs [terminal] with foreground, background and palette. You can leave out name, appearance, cursor, selection and all of [interface]. A theme with no name is called "unnamed".
• A colour is six hexadecimal digits, with or without the #. Shorter forms such as #fff are errors, and so are colour names.
• palette must have exactly sixteen colours.
• An unknown key is an error, as in the settings file. If a theme file can't be read, the top bar reports it by name and the default theme is used.

You can set any UI colour yourself instead of having it derived:

[interface]
canvas = "#0a0b0e"       # behind and between panes
raised = "#171a20"       # under the pointer
selected = "#1e222b"     # the current tab, project or pane in a list
border = "#242933"
text = "#d0d4dc"
text-muted = "#767f90"
text-faint = "#4c5464"
accent = "#7fd1c7"       # the focused pane, the current item
running = "#6fa8ff"      # pane states
waiting = "#f0b35a"
done = "#7fd18b"
failed = "#f0706a"

How the rest is derived:

• The canvas is the terminal background, a step darker. Raised, selected and border step from the canvas toward the foreground. Steps are taken in a colour space where equal steps look equal and the tint is kept.
• Muted and faint text sit between the foreground and the canvas.
• The accent is the palette's blue. The state colours are its blue, yellow, green and red.
• UI text that wouldn't stand out enough from the canvas is shifted in lightness until it does. This applies to colours you set too, so no theme can produce a UI you can't read.