Reference

Configuration

Hyla keeps its settings in one plain-text file. The Settings window (⌘ ,) edits it for you, keeping your comments and order, and Hyla reloads it when you edit it by hand.

Hyla's Settings window, on the General pane: where new sessions start, how they are named, and whether they come back

Settings edits the file for you; General holds where sessions start and whether they come back.

The file

Hyla reads, in order of preference:

  1. $HYLA_CONFIG
  2. $XDG_CONFIG_HOME/hyla/config
  3. ~/.config/hyla/config

It uses Ghostty's syntax: one key = value per line, # for comments, and repeated lines for keys that hold lists. Where a key means what it means in Ghostty, it has Ghostty's name.

ini
# ~/.config/hyla/config
font-size = 14
theme = light:GitHub Light Default,dark:Catppuccin Mocha
cursor-style = bar

env = EDITOR=nvim
env = HOMEBREW_NO_AUTO_UPDATE=1

keybind = cmd+shift+d=pane.split.down

The file only needs what you change. Everything else keeps its default.

sh
hyla config edit              # open it in $EDITOR
hyla config show              # every key with its current value
hyla config check             # report unknown keys and bad values

General

Key Default Description
new-session-directory current Where a new session starts: current, project or home
session-name focused What names a session you haven't: focused, lead or folder (more)
sidebar-rows detailed How the sidebar shows a session: detailed, with its status message, else its branch and changes, on a second line; or compact, on one line
focus-follows-mouse false Focus the pane the pointer moves into
confirm-close true Ask before closing a pane that a program is running in
restore-sessions true Start sessions again after hylad restarts, as after a reboot
resume-agents true As sessions start again, resume the conversation of the agent each pane ran
quit-ends-sessions false Quitting, as with the close button, ⌘Q or the menu, ends this machine's sessions and their programs, and stops hylad, as Quit and End All Sessions does; it asks first, as confirm-close says, while a program runs. Other machines' sessions keep running (more)
session-history false List the agents' ended conversations in the sidebar, to resume or archive (more)
macos-show-app-icon dock-and-menubar Where Hyla's icon shows on macOS: dock-and-menubar, dock or menubar. While it's in the menu bar, closing the window keeps Hyla running there. Windows and Linux always show it in the notification area, where closing the window does the same

Appearance

Key Default Description
window-theme system The app's appearance: system, light or dark
language system The app's language: system, en, ja or zh-Hans
background petal The window's wash: petal, mist, meadow, plain or dock (the Dock's: Liquid Glass under a thin veil)
window-translucent true Let the desktop show through the window
window-opacity 0.82 How much of the window's background the wash covers while translucent, 0 to 1
window-blur true Blur the desktop behind the translucent background; off is plain transparency
window-material sidebar The window's material behind the wash while blurred: sidebar, window, popover, plastic (a frosted content background), glass (Liquid Glass, as the Dock's) or glass-clear
sidebar-image A picture behind the sidebar's sessions: as tall as 80% of the sidebar, centred vertically and against its left edge; empty for none
sidebar-image-opacity 0.35 How much of the sidebar's picture shows, 0 (none) to 1 (whole)
pane-image A picture in the terminals' cards, under their text, in place of the window's background: as wide as the card, from its top; empty for none
pane-image-opacity 0.6 How much of the terminals' picture shows, 0 (none) to 1 (whole)
pane-image-fit fill How the terminals' picture fills a card, as a macOS desktop picture's options: fill, as wide as the card from its top; fit, all of it; stretch, to the card's edges; center, its own size at the middle; or tile
session-switch dissolve How a session shown in place of another comes in, as a slide transition: dissolve fades it in as the one it leaves fades away; slide brings it in from the right; push and cover slide it in from the right; zoom grows it into place; or none shows it at once
pane-opacity 0.82 How much of the window's background shows in a terminal while the window is translucent, 0 to 1, as window-opacity: 0 shows the desktop alone; the text stays opaque
pane-blur false Blur what shows through the terminals; off is plain transparency
pane-material glass The terminal's glass while pane-blur is on: glass (Liquid Glass), plastic (a frosted content background) or glass-clear
pet true Hyla, the tree frog, who follows your sessions from the window's top edge
pet-offset 0.5 Where Hyla stands, 0 to 1 across the window; drag it there
pet-set hyla The pet on the window's edge: hyla the tree frog, codex for the Codex app's active pet, or a pet's directory name in ~/.codex/pets
pet-size 1.5 How tall a Codex pet shows, against the Codex app's size: 0.5 to 3

Terminal

Key Default Description
theme hyla Terminal colors: hyla, any Ghostty theme, or light:<theme>,dark:<theme>
font-family Empty for JetBrains Mono Nerd Font, which Hyla includes; monospace for the system's; or any installed family
font-fallback Fonts for what font-family lacks, such as Chinese, in the order they are tried: PingFang SC, Apple Color Emoji. Empty for the system's choice
font-size 13 In points
font-weight 400 100 to 900; Hyla’s font draws 200 (extra light) and 300 (light) itself
line-height 1.22 A multiple of the font's
font-ligatures true Join characters the way the font draws them
font-thicken false A heavier stroke, as in Ghostty
minimum-contrast 3 The least contrast text keeps with its background, from 1 (none) to 21, so that colors meant for a dark background stay readable on a light one, as in Ghostty
dim-unfocused-terminals true Fade the terminals you're not in, when a session has several panes
cursor-style block block, bar or underline; programs may change it
cursor-style-blink true Blink the cursor
macos-option-as-alt false Option sends Alt (Meta) to programs
copy-on-select false Copy what you select to the clipboard
clipboard-read ask Programs reading the clipboard (OSC 52): ask, allow or deny
right-click-action context-menu context-menu, paste or copy-or-paste
mouse-scroll-multiplier precision:1,discrete:3 How far scrolling goes, as in Ghostty: precision: scales a touchpad's, discrete: is the rows a notch of a mouse wheel scrolls (on Windows, a notch at its 3-line setting); one number sets both, from 0.01 to 10000

Shell

Key Default Description
command The shell of new panes; empty for your login shell
env Added to every pane's environment as NAME=value; repeat it
scrollback-limit 4 The output each pane keeps, in megabytes; 0 for none

Notifications

Key Default Description
notify-on-waiting true When a session needs you
notify-on-done true When an agent finishes
notify-on-error true When a program reports it failed
notify-sound false Play a sound with notifications
dock-badge true Show how many sessions need you on the Dock icon
dock-bounce false Bounce the Dock icon once when a session comes to need you

Agents

Key Default Description
remote-control true Let hyla do and hyla focus drive the app

Hosts

Key Default Description
listen Let Hyla on other machines reach this one: tailcat://:7473, through a relay with a pair code. Repeat it for each

Git

Key Default Description
git-status true Show each session's branch and changes
diff-layout auto Diffs in the changes panel: unified, split (side by side), or auto, side by side once it's wide
worktree-base default What a session's own worktree branches from: default, the repository's default branch, or current, the branch of the session you're in
worktree-dir Where sessions' own worktrees go, each under its repository's name; empty for .hyla/worktrees in the repository

Browser

Key Default Description
browser-block-ads true Block ads and trackers in browser panes
browser-filter-list easylist, easyprivacy A filter list to block with. Repeat it for each list; leave it empty for none

browser-filter-list takes the lists Hyla offers by name, or the https:// URL of any list in Adblock Plus syntax:

Name List
easylist EasyList: ads
easyprivacy EasyPrivacy: trackers and analytics
peter-lowe Peter Lowe's list: ad and tracker servers
easylist-china EasyList China: ads on Chinese sites
fanboy-cookie EasyList Cookie List: cookie notices and consent banners
fanboy-social Fanboy's Social Blocking List: social media buttons and embeds
fanboy-annoyance Fanboy's Annoyance List: pop-ups and prompts, with the two above
ini
browser-filter-list = easylist
browser-filter-list = easyprivacy
browser-filter-list = fanboy-cookie
browser-filter-list = https://example.com/my-filters.txt

Keyboard

keybind rebinds an action, as <keys>=<action>. Repeat it for each binding. Use unbind as the action to free keys.

ini
keybind = cmd+shift+d=pane.split.down
keybind = cmd+k=palette.open
keybind = cmd+b=unbind

Run hyla actions for every action id, and see Keyboard Shortcuts for the defaults.