Configuration

Most persistent Zshell settings live in one file:

~/.config/zshell/config.toml

The Settings window (Cmd+,) writes this same file. A few macOS-owned settings—language and automatic updates—live elsewhere and are listed at the end of this page.

New configurations enable Vim command hints, session history restoration, and failed-command notifications. Automatic update downloads are also enabled by default. Existing configurations and saved choices are preserved.

How the file behavesCopy link

Worth knowing before you hand-edit:

• Changes are read while Zshell is running. Valid external edits apply automatically; settings marked for new terminals still need a new pane. Unreadable or malformed edits retain the last valid settings. An intentionally empty file restores defaults after a short delay.
• Zshell rewrites it whenever a file-backed setting changes. The file is regenerated from scratch, so your comments and unknown keys are lost the next time you use one of those controls. Pick one editor for the file, or keep an authoritative copy in your dotfiles.
• Most default values are omitted. font-size, terminal.vim-command-hints, terminal.restore-history, and terminal.notify-on-error are always written. Removing one of these three terminal keys disables that feature in an existing file; removing other keys restores their defaults.
• The parser is deliberately small. It supports flat keys, dotted keys, [table] headers, # comments, and string/number/boolean values. It does not support arrays, inline tables, or multi-line strings.
• Bad values fall back safely. An out-of-range size, unknown backend, or misspelled theme does not stop Zshell from launching.

Symbolic links to a file or directory are preserved when Settings saves: Zshell updates the target atomically and keeps its permissions. External edits do not rewrite comments or unknown keys; a subsequent Settings save still regenerates the file as described above.

Application presenceCopy link

app-presenceCopy link

"dock" · "dock-and-menu-bar" · "menu-bar" — default "dock"

Choose Settings → General → Show Zshell in to switch immediately. "dock" shows only the Dock icon. "dock-and-menu-bar" shows both icons. "menu-bar" shows only the menu bar icon.

The menu bar opens the current workspace, Quick Terminal, Settings, and the update checker. With either menu bar mode, closing the last workspace window hides it while its terminals and jobs keep running. Open Workspace returns to that same window, project, and session. Closing another workspace window, a pane, or a project still ends its tasks. Explicit Quit keeps following terminal.preserve-sessions; Quit and End All Sessions ends them. The mode is saved across launches.

AppearanceCopy link

themeCopy link

"system" · "light" · "dark" — default "system"

Chooses the app appearance. "system" follows macOS; the other two pin Zshell to one appearance.

theme-dark and theme-lightCopy link

string — defaults "Default Dark" and "Default Light"

The color theme for each appearance. A theme recolors terminal panes, window chrome, sidebars, the editor, and diffs together. The built-in defaults keep Zshell's translucent sidebar; other themes paint it to match their palette.

Settings lists the curated theme catalog shared by both terminal backends. A hand-written name must match one of those display names exactly, including case, or Zshell falls back to the corresponding default.

toolbar.visibilityCopy link

"hide" · "auto" · "always" — default "hide"

Controls the compact toolbar below the active tab:

• "hide" keeps it out of the window.
• "auto" shows it only when the project directory is a Git repository.
• "always" keeps its Git entry point visible in every project, including a No Git Repository state.

See The Git toolbar for what it shows.

TextCopy link

font-familyCopy link

string — default "", meaning the bundled JetBrains Mono

The terminal, editor, and diff viewer share this Latin family. Give a family name, not a face: "IBM Plex Mono", not "IBM Plex Mono Regular". Unknown or non-monospace families fall back to the bundled default.

Terminal fallback order is the Latin family, the optional CJK fallback below, the bundled Symbols Nerd Font, then the backend's system fallback. The editor and diff viewer continue to use their normal macOS/WebKit fallback.

terminal.font-fallback-familyCopy link

string — default "", meaning backend/system fallback

Adds one installed CJK family to the terminal's ordered fallback chain. The Settings picker includes families containing representative Chinese, Japanese, or Korean glyphs; it does not require them to be strictly monospace because they only supply glyphs missing from the primary Latin face.

font-sizeCopy link

number, 8–32 — default 13

The shared terminal, editor, and diff font size in points. This is the one key Zshell writes even when it has the default value.

interface.scaleCopy link

number, 0.9–1.5 — default 1

Scales tabs, icons, buttons, sidebars, and the rest of the application interface. Terminal, editor, and diff content keep the font size configured separately above.

sidebar.font-sizeCopy link

number, 9–24 — default 14

The base text size for both sidebars. Section headings, rows, metadata, and controls keep their relative hierarchy as the base changes.

terminal.font-thickenCopy link

boolean — default false

Renders terminal glyphs with slightly heavier strokes, similar to classic macOS font smoothing. Both backends honor it, and the Settings preview shows the result. Older font-thicken configs are still read, then rewritten using the current dotted key.

terminal.font-thicken-strengthCopy link

integer, 0–255 — default 255

Controls thickening while terminal.font-thicken is true. Zero is the lightest available thickening, not off. Ghostty uses its native macOS strength; Alacritty maps the same range to a CoreText stroke, so the direction and endpoints match but rasterized pixels can differ.

terminal.line-heightCopy link

number, 0.75–2 — default 1

Multiplies each terminal backend's natural cell height while keeping glyphs vertically centered. It changes terminal rows only, not editor or diff spacing.

Zshell does not expose a base font-weight control. Ghostty selects named styles or variation axes while Alacritty/CoreText resolves regular and bold faces by traits; a single shared value would not preserve regular/bold distinction or fallback weights consistently across static and variable fonts.

editor.wrap-linesCopy link

boolean — default true

Soft-wraps long lines to the pane width in the file editor. When false, long lines scroll horizontally. It does not change wrapping in a terminal or diff.

TerminalCopy link

terminal.preserve-sessionsCopy link

boolean — default false

Keeps shells, coding agents, and development servers in newly opened terminals running after you quit Zshell. Reopening connects to the same live process and restores its terminal screen and input modes with either backend. The daemon keeps bounded screen history in memory; it does not survive a macOS restart. If the PTY is no longer alive, the pane opens a fresh shell instead.

Closing a pane, project, or window still ends its tasks, except for the last workspace window in a menu bar mode. Use Zshell → Quit and End All Sessions, or turn this setting off before quitting, to end every background session, including a hidden Quick Terminal. In reuse mode, hiding the Quick Terminal keeps its shells alive; this setting controls whether newly opened reusable panes also survive quitting Zshell. Fresh workspaces end when hidden.

The CLI in a retained shell reconnects to its original terminal when Zshell reopens. It is unavailable while the GUI is closed. The stable CLI launcher is updated on reconnect; removing a development build can make the CLI unavailable until another build of Zshell reopens the session. Terminal image placements and backend-specific graphics are not restored; applications can redraw them.

terminal.startup-program / terminal.startup-argumentsCopy link

strings — default unset

Choose the executable and argument vector used by terminals created from then on. When terminal.startup-program is absent, Zshell keeps using the account login shell with -l. The program must be an executable absolute path; a missing or non-executable path falls back to the login shell instead of opening a dead pane.

terminal.startup-arguments is split into arguments without invoking a shell. Quotes and backslashes preserve boundaries, including spaces and empty arguments, but variables, globs, and command substitutions are not expanded. Invalid quoting also falls back to the login shell. An explicit argv supplied by the Zshell CLI still takes precedence for that terminal.

terminal.backendCopy link

"libghostty" · "alacritty" — default "libghostty"

Chooses the emulator used by terminals created from then on. Existing panes keep the backend they started with. Both choices are native, GPU-accelerated, support image rendering, and use the same Zshell themes; Alacritty generally has the lower memory footprint.

See Terminal backends for the environment variables and compatibility contract.

terminal.macos-option-as-altCopy link

boolean — default false

When true, Option-key combinations are sent to terminal programs as Alt/Meta shortcuts. The default leaves Option with the active macOS input source so layouts such as Polish Pro can type their composed characters.

terminal.bellCopy link

boolean — default true

Controls the alert sound and macOS visual attention when a terminal program rings the bell. When false, Zshell does not play the sound, post a terminal bell notification, or request attention in the Dock. Accessibility technologies still receive the bell as a semantic announcement. Both terminal backends honor this setting.

terminal.vim-command-hintsCopy link

boolean — default true

Show mode-aware Vim / Neovim commands below the session information in the Info sidebar. Applies immediately on both terminal backends, including recognizable editors over SSH. See Vim command hints for mode detection requirements.

terminal.restore-historyCopy link

boolean — default true

Restores each terminal's previous scrollback above a fresh shell after a relaunch. The restored content is static text, not a surviving process.

Restored scrollback is stored on disk, so any secrets shown in the terminal may be included. Projects, tabs, and pane layout are restored either way.

AutomationCopy link

ai.enabledCopy link

boolean — default true

Lets supported coding agents coordinate background Zshell panes when you ask in plain language, and shows provider-reported lifecycle status in the UI. Zshell does not infer status from terminal text. The Settings toggle is the recommended way to change it because errors are shown inline and conflicting existing setups are left untouched.

The human workflow is described in Working with AI agents.

For shared Codex app-server sessions, Zshell matches verified conversation IDs to the foreground pane. Ambiguous matches remain unbound. Its managed integration adds session-id to Codex’s terminal title while preserving other title items.

ai.resume-conversationsCopy link

boolean — default true

When terminal panes are restored, resumes the exact recorded Claude Code, Codex, Pi, or OpenCode conversation after its original PTY is unavailable. Requires ai.enabled = true. A pane without a verified conversation opens a new shell; Zshell never chooses the latest conversation by directory.

Control it with Settings → Automation → Resume agent conversations. This setting is independent of terminal.restore-history.

Additional settingsCopy link

Backup and migrationCopy link

Use Zshell → Export Settings… to save a TOML file, and Import Settings… to load it. Import asks you to confirm replacement and attempts to back up the current file as config.toml.bak in the same directory.

Import reads every supported configuration key. Omitted keys use the configuration reader’s defaults; omitting ai.enabled preserves the current AI setting. Language and project or tab environment variables are stored separately.

A complete exampleCopy link

theme = "dark"
theme-dark = "Catppuccin Mocha"
theme-light = "Catppuccin Latte"
font-family = "IBM Plex Mono"
font-size = 14
interface.scale = 1.25
sidebar.font-size = 13
toolbar.visibility = "auto"
terminal.font-fallback-family = "PingFang SC"
terminal.font-thicken = true
terminal.font-thicken-strength = 180
terminal.line-height = 1.15
terminal.macos-option-as-alt = false
terminal.bell = false
terminal.startup-program = "/opt/homebrew/bin/fish"
terminal.startup-arguments = "--no-config"
terminal.backend = "alacritty"
terminal.restore-history = true
editor.wrap-lines = true
ai.enabled = true
ai.resume-conversations = true

Every key is optional. Delete a key to return that setting to its default.

Keyboard shortcutsCopy link

Open Settings → Shortcuts to record a new shortcut for a core command. Zshell rejects conflicting combinations and names the command already using them. Restore Default Shortcuts resets all overrides. The keyboard reference lists the shipped defaults.

Settings outside this fileCopy link

• Language. Settings offers System Default and 17 languages, matching the website. Changes apply immediately while terminal sessions keep running. The choice uses macOS's per-app language preference, so it lives in Zshell's preferences rather than TOML. System Default follows the macOS language order.
• Automatic updates. The automatic check, download, and installation switches in Settings → Updates use app preferences outside TOML and remember your choices across launches. Installation is shown only while automatic downloads are enabled. See Installation.
• Window and layout state. Window size, sidebar widths, selected panels, projects, tabs, panes, browser URLs, and diff control preferences live in Zshell's macOS preferences and session snapshot.
• Backend config files. Zshell does not read ~/.config/ghostty or an Alacritty config. Zshell's settings are the supported surface for both.