Features

Because Ghostboard is a Ghostty fork, TermSurf inherits Ghostty’s terminal features. This page is an overview of the ones available on macOS today; for the exact configuration options, see the config reference.

Color themes

The theme option selects a color theme — a built-in theme, a custom theme name, or a path to a theme file. You can also set different themes for light and dark mode. TermSurf ships with a large collection of built-in themes; run termsurf +list-themes to browse them, and drop your own theme files in ~/.config/termsurf/themes.

# ~/.config/termsurf/config
theme = TokyoNight

A theme file is just another config file, so it can set any color option. See the theme option for the full details and the light/dark syntax.

Shell integration

Shell integration auto-injects support for bash, fish, elvish, nushell, and zsh. It enables a number of conveniences:

• New tabs and splits inherit the previous pane’s working directory.

• Prompt marking, which powers the jump_to_prompt keybinding.

• Closing a pane at the prompt doesn’t ask for confirmation.
• Cleaner redraws when resizing with a complex prompt.

It’s controlled by shell-integration (default detect) and shell-integration-features, which toggles individual features such as cursor, title, sudo, and path. See the shell-integration options for the full list and syntax. Prompt-related actions can also be bound — see Keybindings.

SSH integration

Two shell-integration features smooth out SSH sessions: ssh-env keeps environment variables compatible with remote hosts (adjusting TERM so remote programs behave even when they don’t know TermSurf’s terminfo), and ssh-terminfo installs the terminal’s terminfo entry on remote hosts automatically. Once installed on a host, it’s cached; the termsurf +ssh-cache CLI action manages that cache. Enable them via shell-integration-features — see the config reference.

AppleScript automation (macOS)

TermSurf ships an AppleScript scripting dictionary, so you can automate it from AppleScript or osascript. The dictionary exposes application, window, tab, and terminal objects, plus commands to open and arrange the terminal — including new window, new tab, split, focus, and close — and to drive it: input text, send key, the mouse commands, and perform action (which runs any keybind action by name).

# Open a new TermSurf window from the shell
osascript -e ‘tell application “TermSurf” to new window’

Because perform action accepts any keybind action, scripts can trigger the same operations you bind to keys — see the Keybind Actions reference.