Skip to content

Settings and themes ​

Everything about how insensical looks and behaves lives in one file you can edit by hand or through the settings sheet.

Settings live in ~/.config/insensical/config.toml ($XDG_CONFIG_HOME/insensical/config.toml if that's set; INSENSICAL_CONFIG_DIR overrides both). Without the file, the defaults apply.

The window makes the file the first time it starts, if there isn't one. It explains every setting and shows its default, but sets none: each setting line begins with #. Remove the # to set a line, or use the settings sheet, which writes its line under the one that shows the default.

  • A file that's already there is never written over.
  • isc on its own doesn't make the file; the window and isc config set do.
  • The keymaps aren't in it. isc config prints them.

isc config prints a complete file: every setting at its default with a note and its possible values, the [tui] table, and both keymaps.

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

To read or change one setting without opening the file:

sh
isc config get font-size        # what the file gives it, or its default
isc config set font-size 13
isc config set sidebar tabs,panes
isc config reset font-size      # takes the line out, which leaves the default
  • set changes that one line and keeps the rest of the file. If there's no file, it makes one with that line.
  • A setting shown in a comment, such as # shell = "fish", is written under that comment. reset takes out only that line.
  • A value the setting can't have is refused, and the message says what it can be.
  • colours and mouse, which only the interface in a terminal has, are read, set and reset under [tui].
  • These work for every setting, not for the [keys] tables.

Some settings are the daemon's, and the rest are the interface's. The daemon's are shell, agents-at-once, agents-deep, agents-from-other-machines, term, scrollback, keep-scrollback, tmux-shim, clipboard, notifications, notify-waiting, notify-failed, notify-done, sound, long-command, tray, notify-command, notify-command-when, notify-url, notify-url-when, notify-url-body, notify-url-headers, notify-url-token, notify-url-user and notify-url-password. With a daemon on another machine, its settings are in the file there and the interface's are here:

sh
isc --host build config get scrollback      # what the file on build gives it
isc --host build config set scrollback 50   # written to the file on build
isc --host build config set theme paper     # refused: theme is this machine's

The daemon there makes the change, so it must be running. isc --host build config alone prints the same complete file as without --host.

An example:

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

The meaning and default of every setting are in the reference.

Icons for your own programs ​

Give a program insensical doesn't know its own tile, under [icons], by the name it runs under:

toml
[icons]
gitu = "git"                                    # as git is shown
myagent = "claude"
deploy = { mark = "docker", colour = "#ff8800" }   # Docker's mark on a tile of your colour
  • The value names a program that has a tile (git, nvim, claude, docker) or a mark (agent, activity, remote, shell, terminal).
  • colour is the tile's own, as #rrggbb. Without it the tile keeps the named program's colour.
  • A line here beats what's built in, so you can change a known program too: node = "vite".
  • The name is the one in the pane's header and in isc ls; a name the program reports (States and attention) is tried first.

The settings sheet ​

Press Ctrl+, (⌘, on macOS) or leader ,, or choose "Settings" in the palette. It opens over the window. Nothing is typed as a value: a setting is switched, picked or stepped. A number steps by one, the background's opacity by 0.05, and long-command (up to 3600 seconds) by five.

  • Pages are down the left, under the search field: General, Hub, Interface, Terminal, Shortcuts, Remote Hosts, Notifications and Agents. The sheet opens on the page you last looked at. Arrows by the page's name go back and forward through pages you've visited. Esc or the X at its top right closes it.
  • A change applies at once and is written to that setting's one line in config.toml.
  • Type to find a setting by name or what it does.
  • To reset a setting your file changes, put the pointer on its row and press the small arrow left of the control, or press Ctrl+Backspace. Its line leaves the file.
  • Showing is at the top right of Hub, Terminal, Notifications and Agents once you've named another computer. It says which computer the page is about: press it for the list, or Alt+M to step through them. A computer that can't be reached can be chosen; its page says so and waits.
ControlForChange it
A switchon or offClick, or Enter
Two words on a trackone of two, such as the density or where the tabs areClick one, or Enter for the other
A word with ⌄one of more than two, such as the pane header, motion, or how long a device stays pairedClick or Enter for a menu with the current value ticked. Arrows, Home, End, a letter, Enter to choose, Esc to leave it
Buttons side by side, ✓ on those that are onany of a few, such as what the sidebar listsClick one to tick or untick it, or Enter to go through every combination
A number with − +text size, space between panesClick − or +, or Ctrl+Right and Ctrl+Left
A value with ›a theme, a font, a shellClick or Enter for a list in place of the rows. Type to narrow, Enter chooses, Esc goes back
Key capsthe leaderClick or Enter, then press the key. It needs Ctrl, Alt or Cmd held (⌃, ⌥, ⌘). Esc cancels
KeyDoes
Up, DownMove between rows
EnterChange the marked setting, or open its list
Ctrl+Right, Ctrl+LeftNext or previous value; one more or one less
Ctrl+BackspaceReset the marked setting
Tab, Shift+TabNext or previous control on the page
Space, Enter on a controlPress it
Ctrl+Tab, Ctrl+Shift+TabNext or previous page
EscClose the sheet, or leave a list

The pages:

  • Hub is for this computer's server and who can reach it.
    • Server and Connected: the server's state over the version and protocol of the hub. On a hub that's this computer's own. On a computer that joined a hub, it's what that hub said as it connected, or Version not known when it isn't connected or is older than this. A protocol that isn't this app's is shown as a warning. With no hub running and none joined, it says Version not known too. Then the path of the server's socket with a copy button, and Restart Server, which asks first. Connected lists every window, browser, isc tui and the hub's notifications looking at this computer's terminals, with what each can do and when it connected. Disconnect asks, then ends one; for a named browser or phone, Disconnect and Remove Device also ends its pairing.
    • Access from your other devices: the switch Open in a browser or on your phone runs isc hub start and isc hub stop, and says what keeps the hub running: systemd, insensical when it opens, or a terminal. While it's on, Restart Hub runs isc hub restart (it stands out if the hub is older than the installed version), and you can open a browser here with Open in Browser, copy a sign-in link for another, and turn on Reach it from anywhere on your tailnet. Notifications on your devices counts the devices that asked for them, and Send a Test tries each. See Reaching isc hub from another device.
    • Your devices: each paired device, with its icon, name and when it was last used or ends. Press one for Pair Again or Remove. A guest has End. Add a Device asks for a name, what it may do (Everything, Look and type, or Only look), how long it stays paired and its icon, then shows a QR code and a link. See Pairing a device and Sharing one project or one terminal.
    • Joined machines (on a hub) lists computers joined to it, with Remove and Invite a Machine. Join a hub (on any computer that joined none) has Join a Hub, where you paste the invite line. See Joining another machine to your hub.
    • A computer that joined a hub has the same switch and Restart Hub, then Joined to the hub at with the hub's name, whether it's connected, and Leave. Your devices are managed on the hub: add and remove them in Settings > Hub there. It has no browser link, Tailscale row, notifications row, Joined machines or Add a Device. Guests lists the guests it shared something with.
  • General is the app itself: At login (what insensical does when you log in); Updates, the version you run and the protocol it speaks, such as insensical 0.9.0 · protocol 36, and when it was last checked, with Check Now, Update when a new release is out (see A new version installed underneath), and Check for updates automatically; on a Mac, Power, with Keep this Mac awake (keep-awake), and Menu bar and Dock, with Show in the menu bar and Count on the Dock icon; and the Settings file, which opens when pressed, with a copy button.
  • Interface is the window around your terminals. Look: the interface colours, Neutral or From the terminal theme, the interface font, and motion. Layout: density, space between panes, the pane header, where the tabs are, what the sidebar lists, and whether to show idle agents in Activity. Window: the interface's opacity and blur behind the window. Panes: the panes' opacity. Each opacity shows as a percent; 100% is solid.
  • Terminal is what's inside each pane. Appearance: System, Light or Dark, as three pictures. System follows the desktop; Light and Dark hold the window there. Terminals: Same as the window, Light or Dark. Dark and Light show every theme's dark and light versions as small previews in their own colours, the one in use ringed. Where both are in use, on System or with the terminals on the other side from the window, you see both, each saying what uses it; otherwise only the one. Pick a preview and it's used for that side, written as theme = { light = …, dark = … }. All themes opens a list that also has Ghostty's theme and your own: a theme is shown on the whole window as you move through it, Esc puts back the one you had, and picking one uses it for both sides. Text: the font, text size and ligatures. The font list shows only fonts of one width; name any other in the file. Behaviour: the shell (from /etc/shells), the terminal type, answering as tmux, type ahead, how much each pane keeps and whether it's kept when the server stops, whether programs may write the clipboard, what opens a file, the input method, and Option as Alt.
  • Remote Hosts has one card per computer you've named. The first row shows its state (Connected, Can't be reached, or that its server can't be used) and where ssh goes, with a Check button that meets it and says what's wrong in plain words. Press the row to fold or open the card. Open, it has the icon, whether it's careful (it asks before a paste of more than a line), Rename, the address (Change, type it, Enter keeps it, Esc leaves it) and Forget, which asks once and changes nothing on that computer.
    • A card starts open if it's your only one, just added, or needs you; otherwise folded.
    • A host with an older insensical says so when it connects, with Update There, which brings it to this computer's version. If a check finds insensical missing there, or its server older, a row offers Update There or Restart Its Server. Where a package or Homebrew owns insensical there, the row shows the command to run on that machine, with a copy button. Where the copy there was built from source, the row says to build the new version there the same way. A host with a newer insensical says to update this computer. Where ssh has a question, the row has an Answer button.
    • Add Remote Host, at the top of the page, opens a dialog with the machines of your tailnet and the names in your ssh configuration under two tabs; anything you type is given to ssh.
  • Notifications has three cards: Being told (notifications at all, the tray's icon), What you're told of (a pane that waits, something that fails, something that finishes, and how long a command counts as long) and Light and sound (the glow around a waiting pane, the sound, and a Play for each of the two sounds).
    • When you're away is how you're told on your phone when something needs you and no window or terminal is open. Choose ntfy and give the server (the free https://ntfy.sh unless you change it), a topic, and an access token if your server needs one; or choose Another web address and give the address. Alert me only when I'm away is a switch: off, you're told every time. Send a Test says how it went, and a quiet line says how the last alert went.
    • More options holds how an address is sent, a user and password, a token and a command to run. Secret fields show only dots.
    • An ntfy topic also sets notify-url-body to text. notify-url-headers is set only with isc config set. Every setting behind this page is listed in the reference.
  • Agents starts with how many agents one agent may start and how many levels deep, each a number between − and +, and a switch for whether agents on other machines can use this computer. Under them is each agent it knows and whether it reports what it's doing: it does, it doesn't, its hooks are stale (they name an isc that's gone), or the agent isn't on this system. Set up asks before adding hooks, as in [Agents](/agents).
  • Shortcuts has the keymap and the leader under Keys, and under Every key buttons for the sheet of every key and for opening the file. The [keys] tables and a theme's own file aren't on the sheet.
  • With more than one machine, pages that hold a server's settings say whose they are; see Other machines in the window.

When a change applies ​

  • Saved changes apply within a second. You needn't restart.
  • The daemon reads shell and keep-scrollback when the next pane starts; open panes keep their values. It reads clipboard each time a program asks.
  • 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 or unknown 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 it.
  • A wrongly written command under [commands] or mode under [modes] is reported and left out alone.
  • A value that reads but can't be used (a font size of 500, a theme that doesn't exist, a leader that isn't a key, a shell that isn't a program) is reported, and only that setting falls back.
  • The daemon is more forgiving. A value it can't read leaves only that setting at its default, and a broken file leaves the settings it last read. It reports what it couldn't use in a notification, at the end of isc notify --sinks, and through isc --host NAME config get.

Themes ​

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

Eight themes come with insensical:

NameLooks likeHas
fjordCool blue-grey, with a sky-blue accent; by day, cool paper with a deeper bluedark and light
emberWarm brown, with an amber accentdark
paperWarm off-white, with dark inklight
tidepoolDeep sea-green water, with coraldark and light
heatherA moor at dusk: plum, with a heather-pink accentdark and light
lichenMoss on stone: olive green, with a lichen-yellow accentdark and light
lanternAn indigo night lit by amber; by day, ink on rice paperdark and light
quartzQuiet grey with soft colours and a touch of rosedark and light

A theme with both follows the desktop: theme = "lantern" is dark when the desktop is dark and light when it's light. To hold the window to one side whatever the desktop is, set appearance = "dark" or "light". You then get that side of your theme: the dark or light of a pair, or that version of a single theme. A theme with only one version, such as ember, stays as it is.

The terminals can have their own side. terminal-appearance = "dark" keeps them, and their panes' ground, in your theme's dark version while the window around them follows appearance, for example a light window with dark terminals. The window's greys, accent and state colours stay the window's side; with interface-style = "terminal" the window is worked out from its own side's version. "light" is the other way round, and "interface", the default, has the terminals follow the window.

A theme name is looked up like this:

NameMeans
ghosttyThe theme named in Ghostty's own configuration for the desktop's current appearance
ghostty:NameThe Ghostty theme with that name
anything elsethemes/NAME.toml beside the settings file, then the themes that come with insensical
  • Without Ghostty installed, ghostty and ghostty:… are errors. Only the theme comes from Ghostty; its font, font size, font style, padding, opacity, blur, cursor style and command aren't used.
  • The terminals' colours always come from the theme. The window around them is grey unless you set interface-style = "terminal". A program's tile is always in its own colours.

A neutral interface ​

By default the window around the terminals is grey: near-black on a dark desktop, near-white on a light one. That leaves the colour to the terminals. interface-style = "terminal" (From the terminal theme in the settings) works the window out from the theme instead, so a warm theme gives a warm sidebar. isc tui is the other way round: it's in the theme's colours unless you write interface-style = "insensical".

  • In grey, the sidebar, tabs, headers, borders and sheets are grey; the theme's accent, the state colours and the terminals stay as they are.
  • Surfaces a theme file chose under [interface] aren't used in grey; its accent, running, waiting, done and failed are.

A see-through window ​

By default your desktop shows through the window, blurred: a little through the sidebar, and between the panes. The panes themselves are solid. Two settings set how much shows through, each from 0.2 to 1, or 20% to 100% on Settings > Interface:

toml
interface-opacity = 0.7     # the sidebar
background-opacity = 1      # each pane; 1 is the theme's background, solid
background-blur = true
  • interface-opacity sets the sidebar. The words beside the panes keep a ground thick enough to read on, whatever you set. A light sidebar is never thinner than 0.88, since thinner light glass turns grey over a dark wallpaper.
  • background-opacity sets the panes and nothing else. Text, cells a program coloured, tiles, borders and floating or zoomed panes stay solid.
  • Left out, the panes are solid, and the sidebar is 0.9 with background-blur on and solid with it off, since see-through over a sharp desktop is hard to read. What you set is used either way.
  • While a dialog, the palette, the settings or the overview is open, the window under it is dimmed and keeps the opacities you set.
  • background-blur asks the desktop to blur what shows through the window, as strongly as your desktop blurs. It's one request for the whole window, so it can't differ between the sidebar and the panes. On Hyprland and other compositors that blur by their own rules, turn blur on for the window there (the class and title are both insensical). On a desktop that doesn't blur, turn it off.
  • A waiting pane's glow is left out on a pane thinner than the default: it's too thin to hide it.
  • With no compositor there's nothing to show through, and the window is drawn over black.
  • Both apply as you save. Text over a busy picture is harder to read.

A theme file ​

Put your own theme in ~/.config/insensical/themes/<name>.toml:

toml
name = "Fjord"

[terminal]
foreground = "#d0d4dc"
background = "#101216"
cursor = "#d0d4dc"        # optional: the foreground if left out
selection = "#3aaceb"     # 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",
]

Light or dark is worked out from the background, unless appearance = "light" or "dark" at the top of the file sets it.

One file can hold a theme for both. Write each side under dark and light, and the desktop's appearance picks:

toml
name = "Mine"

[dark.terminal]
foreground = "#d0d4dc"
background = "#101216"
palette = [ … ]

[light.terminal]
foreground = "#2b2a27"
background = "#f6f3ec"
palette = [ … ]

[light.interface]         # optional, as [interface] is
accent = "#1f7a78"
  • A file has either [terminal], or both [dark.terminal] and [light.terminal]. One side alone, or mixing the two forms, is an error.
  • A theme needs only [terminal] with foreground, background and palette. You can leave out name (it's called "unnamed"), appearance, cursor, selection and all of [interface].
  • A colour is six hexadecimal digits, with or without the #. Shorter forms such as #fff and colour names are errors.
  • palette must have exactly sixteen colours.
  • An unknown key is an error. If a theme file can't be read, the top bar reports it by name and the default theme is used.

To set any interface colour yourself instead of having it derived:

toml
[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 = "#3aaceb"       # the focused pane, the current item
running = "#6fa8ff"      # pane states
waiting = "#f0b35a"
done = "#7fd18b"
failed = "#f0706a"

What you leave out is derived from the theme: the canvas is the background a step darker, muted and faint text sit between the foreground and the canvas, the accent is the palette's blue, and the state colours are its blue (cyan if the accent took the blue), yellow, green and red. Text that wouldn't stand out enough is shifted in lightness until it does, colours you set included.