Terminal Behavior Configuration

Command Configuration

Default Command

# Set the command to run (usually a shell)
command = /bin/zsh
command = fish
command = nvim

If not set, Ghostty uses:

$SHELL environment variable
passwd entry (user information)

How do I pass arguments to the command?

Include arguments in the command string:

command = fish --with --custom --args

Ghostty executes this via /bin/sh -c for shell expansion.

Command Execution Modes

# Shell expansion (default)
command = nvim foo  # Executed via /bin/sh -c

# Direct execution (no shell, faster)
command = direct:nvim foo  # Executed directly

# Explicit shell (force shell expansion)
command = shell:nvim foo  # Always wrap in shell

direct mode avoids the /bin/sh roundtrip but doesn’t support shell features like:

Arguments with spaces
Tilde expansion (~)
Globs (*.txt)
Shell variables

Initial Command

# Command for the FIRST terminal surface only
initial-command = tmux attach

Subsequent terminals use the command setting.

Use the -e flag for a convenient shortcut:

ghostty -e nvim file.txt

This automatically:

Disables shell expansion
Sets gtk-single-instance=false
Sets quit-after-last-window-closed=true
Sets shell-integration=detect (if not none)

Environment Variables

# Set environment variables
env = FOO=bar
env = PATH=/custom/path:$PATH

# Clear all environment variables
env =

# Remove a specific variable
env = FOO=

These variables override Ghostty’s automatic variables (like GHOSTTY_RESOURCES_DIR).They do not affect commands run by Ghostty for other purposes (like open or xdg-open for URLs).Available since 1.2.0.

Command Input

Send data to command on startup:

# Send raw text
input = raw:Hello, world!\n
# Read from file
input = path:/path/to/file.txt

# Without prefix (assumed to be raw)
input = "ls -la\n"

Input is sent as-is. Be cautious with control characters - they can execute programs in a shell.Files are limited to 10MB. Don’t use special files like /dev/stdin or /dev/urandom (they’ll block startup).

Repeatable configuration. Data is concatenated directly with no separator.If any input source doesn’t exist, no input is sent at all.Changes only affect new terminals.Available since 1.2.0.

Command Behavior

Wait After Command

# Keep terminal open after command exits
wait-after-command = true

Terminal stays open until any keypress. Useful for scripts and debugging.

Abnormal Exit Detection

# Runtime below which exit is considered abnormal (in milliseconds)
abnormal-command-exit-runtime = 250  # Default

Shows error message when process exits too quickly.

Linux
macOS

Requires non-zero exit code.

Confirm Close

confirm-close-surface = true     # Confirm if process running (default)
confirm-close-surface = false    # Never confirm
confirm-close-surface = always   # Always confirm

When true, Ghostty uses shell integration to detect if a process is running. Without shell integration, always confirms.

Scrollback

Scrollback Limit

# Scrollback buffer size in bytes
scrollback-limit = 10000000  # 10MB (default)
scrollback-limit = 100000000 # 100MB

This is the total memory for scrollback + active screen. Enough memory is always allocated for the visible screen; leftover is scrollback.Scrollback is allocated lazily, so large values don’t immediately consume memory.This is per terminal surface, not application-wide.Changes only affect new terminals.

Unlimited scrollback is not currently possible (planned for future).

Scrollbar Visibility (macOS)

scrollbar = system  # Respect system settings (default)
scrollbar = never   # Never show scrollbar

macOS only. GTK doesn’t yet support scrollbars.With never, you can still scroll via mouse, keybinds, etc.

Scroll to Bottom

scroll-to-bottom = keystroke,no-output  # Default
scroll-to-bottom = keystroke,output
scroll-to-bottom = no-keystroke,output

Options:

keystroke: Scroll to bottom on keypress that sends data to PTY
output: Scroll to bottom on new output (currently unimplemented)

Prefix with no- to disable an option.

Mouse Behavior

Mouse Reporting

mouse-reporting = true   # Allow apps to capture mouse (default)
mouse-reporting = false  # Always use mouse for selection

Toggle at runtime with toggle_mouse_reporting keybind.

Mouse Shift Capture

mouse-shift-capture = false   # Shift extends selection (default)
mouse-shift-capture = true    # Shift is sent to app (if app requests)
mouse-shift-capture = never   # Shift always extends selection
mouse-shift-capture = always  # Shift always sent to app

What's the difference between values?

false/never: Apps can request shift with XTSHIFTESCAPE (or not with never)
true/always: Shift sent by default, apps can toggle with XTSHIFTESCAPE (or not with always)

Use never if you always want shift to extend selection.

Mouse Scroll Multiplier

# Universal multiplier
mouse-scroll-multiplier = 3      # Discrete devices (default)
mouse-scroll-multiplier = 1      # Precision devices (default)

# Device-specific multipliers (since 1.2.1)
mouse-scroll-multiplier = precision:0.1,discrete:3
mouse-scroll-multiplier = precision:1
mouse-scroll-multiplier = discrete:5

Value is clamped to [0.01, 10,000]. Both extremes provide a bad experience.

Hide Mouse While Typing

mouse-hide-while-typing = true

Mouse reappears on movement, button press, etc.

Platform behavior may show mouse in other scenarios (e.g., macOS shows mouse when creating new windows/tabs/splits).

Click to Move Cursor

# Alt/Option+click to move cursor at prompt
cursor-click-to-move = true  # Default

Requires shell integration (specifically prompt marking via OSC 133). Only works in primary screen mode.Works by synthesizing arrow key movements. Some edge cases may behave unexpectedly.

Click Repeat Interval

# Time between clicks for double/triple-click (milliseconds)
click-repeat-interval = 0     # Platform default
click-repeat-interval = 500   # 500ms

macOS
Other

Default determined by OS settings.

Right-Click Action

right-click-action = context-menu   # Show menu (default)
right-click-action = paste          # Paste clipboard
right-click-action = copy           # Copy selection
right-click-action = copy-or-paste  # Copy if selection, else paste
right-click-action = ignore         # Do nothing

Focus Follows Mouse

focus-follows-mouse = false  # Default
focus-follows-mouse = true   # Focus split on hover

Only applies to the currently focused window. Hovering over unfocused windows doesn’t change focus.

Selection

Selection Colors

See Appearance Configuration for selection color options.

Selection Behavior

# Clear selection when typing
selection-clear-on-typing = true  # Default

# Clear selection after copying
selection-clear-on-copy = false   # Default

selection-clear-on-typing is triggered by:

Any non-modifier keypress that sends data to PTY
Preedit/composition start (e.g., Japanese input)

Selection can still be cleared by clicking once or pressing Escape.

selection-clear-on-copy only applies to copy_to_clipboard keybind action, not copy-on-select.

Copy on Select

copy-on-select = true         # Copy to selection clipboard (default Linux/macOS)
copy-on-select = false        # Disabled (default other)
copy-on-select = clipboard    # Copy to both selection and system clipboard

Middle-click paste always uses the selection clipboard, even when copy-on-select = false.

Selection Word Characters

# Characters that mark word boundaries (default: space, tab, quotes, etc.)
selection-word-chars = " \t'\"│`|:;,()[]{}<>$"

Used for double-click word selection. Null character (U+0000) is always a boundary.

How do I make semicolons part of words?

Remove ; from the default value:

selection-word-chars = " \t'\"│`|:,()[]{}<>$"

Only single codepoints supported. Multi-codepoint sequences (emoji) not supported.Available since 1.3.0.

Clipboard

Clipboard Access

clipboard-read = ask     # Prompt user (default)
clipboard-write = allow  # Allow without prompt (default)

# Valid values: ask, allow, deny

Controls program access to clipboard via OSC 52.

Clipboard Paste Protection

# Confirm before pasting unsafe text
clipboard-paste-protection = true  # Default

# Bracketed pastes are safe
clipboard-paste-bracketed-safe = true  # Default

Prevents copy/paste attacks where pasted text contains newlines that execute commands.

Clipboard Trimming

# Trim trailing whitespace when copying
clipboard-trim-trailing-spaces = true  # Default

Only trims trailing whitespace on lines with other characters. Blank lines always trimmed.

Clipboard Codepoint Mapping

# Replace characters when copying to clipboard
clipboard-codepoint-map = U+2500=U+002D  # Box horizontal → hyphen
clipboard-codepoint-map = U+2502=U+007C  # Box vertical → pipe
clipboard-codepoint-map = U+03A3=SUM     # Greek sigma → "SUM"

Does not apply to URL copying (only text copying).Later entries override earlier ones for overlapping ranges.

Shell Integration

Auto-Injection

shell-integration = detect   # Auto-detect shell (default)
shell-integration = none     # Disable auto-injection
shell-integration = bash     # Force bash injection
shell-integration = fish     # Force fish injection
shell-integration = zsh      # Force zsh injection
shell-integration = elvish   # Force elvish injection
shell-integration = nushell  # Force nushell injection

Shell integration enables:

Working directory reporting (for directory inheritance)
Prompt marking (for jump_to_prompt keybind)
No confirmation when closing at a prompt
Better prompt repainting on resize

You can manually source the integration script even with shell-integration = none.

Shell Integration Features

# Enable/disable specific features
shell-integration-features = cursor,sudo,title,ssh-env,ssh-terminfo,path
shell-integration-features = no-cursor,ssh-env

# Or enable/disable all
shell-integration-features = true
shell-integration-features = false

Available features:

cursor

Set cursor to a bar at the prompt.

sudo

Set sudo wrapper to preserve terminfo.

title

Set window title via shell integration.

ssh-env

SSH environment variable compatibility:

Converts TERM from xterm-ghostty to xterm-256color on remote hosts
Propagates COLORTERM, TERM_PROGRAM, TERM_PROGRAM_VERSION

Requires remote sshd_config to accept these variables.(Available since 1.2.0)

ssh-terminfo

Automatic terminfo installation on remote hosts:

Installs Ghostty’s terminfo entry using infocmp and tic
Requires infocmp locally, tic on remote hosts
Automatically cached to avoid repeat installations

Manage cache with ghostty +ssh-cache CLI action.(Available since 1.2.0)

path

Add Ghostty’s binary directory to PATH. Ensures ghostty command is available even if shell init scripts reset PATH.Particularly useful on macOS where PATH is often overridden. Only added if not already present.

SSH features work independently and can be combined:

Both ssh-env + ssh-terminfo: Use xterm-ghostty with terminfo installation, fallback to xterm-256color with env vars if installation fails
Just ssh-env: Always use xterm-256color with env vars
Just ssh-terminfo: Install terminfo and use xterm-ghostty

Command Notifications (GTK)

When to Notify

notify-on-command-finish = never      # Never notify (default)
notify-on-command-finish = unfocused  # Notify if surface unfocused
notify-on-command-finish = always     # Always notify

GTK only. Requires shell integration or OSC 133 sequences.GTK context menu has an option to enable notifications for a single command.Available since 1.3.0.

Notification Action

# How to notify
notify-on-command-finish-action = bell,notify
notify-on-command-finish-action = notify
notify-on-command-finish-action = bell,no-notify

Options:

bell: Terminal bell (enabled by default)
notify: System notification (disabled by default)

GTK only. Available since 1.3.0.

Notification Threshold

# Minimum command runtime before notifying (default: 5 seconds)
notify-on-command-finish-after = 5s
notify-on-command-finish-after = 1m30s
notify-on-command-finish-after = 500ms

GTK only. Available since 1.3.0.

Terminal Features

Image Storage

# Maximum image data per screen (in bytes)
image-storage-limit = 320000000  # 320MB (default)
image-storage-limit = 0          # Disable images

Limit is per screen (primary and alternate), so effective limit per surface is double.Maximum value: 4,294,967,295 (4GiB).

Title Reporting

# Allow terminal title queries (CSI 21 t)
title-report = false  # Disabled (default)

Security risk: Can expose sensitive information or enable code execution with crafted titles. Only enable if you trust all running programs.Available since 1.0.1.

KAM Mode

# Allow keyboard lock mode (ANSI mode 2)
vt-kam-allowed = false  # Default

Rare feature. If you don’t know you need KAM, you don’t need it.

OSC Color Reporting

osc-color-report-format = 16-bit  # Default
osc-color-report-format = 8-bit   # Legacy 8-bit
osc-color-report-format = none    # Disable reporting

Controls format for OSC 4/10/11 color queries.

Working Directory

working-directory = inherit  # Use launching process CWD (default)
working-directory = home     # Use home directory
working-directory = /path    # Use specific path

This is secondary to window-inherit-working-directory. Inheritance takes precedence if a previous terminal exists.Typically only used for the first window.

Platform defaults:

macOS: home if launched from launchd or open
Linux/GTK: home if launched from desktop launcher
Otherwise: inherit

Quit Behavior

Quit After Last Window

quit-after-last-window-closed = false  # macOS default
quit-after-last-window-closed = true   # Linux default

macOS
Linux

Default false matches standard macOS app behavior (app stays running).

Default true matches expected Linux behavior.Can delay quitting with quit-after-last-window-closed-delay.

Quit Delay (Linux)

# Delay before quitting (minimum: 1s)
quit-after-last-window-closed-delay = 5s
quit-after-last-window-closed-delay = 1m

Linux only. Only has effect if quit-after-last-window-closed = true.Minimum value: 1s.

Resources

Shell Integration

Detailed shell integration guide

SSH Configuration

Using Ghostty with SSH

Keybindings

Terminal-related keybind actions

Window Settings

Window and tab configuration

Getting Started

Configuration

Features

Guides

​Command Configuration

​Default Command

​Command Execution Modes

​Initial Command

​Environment Variables

​Command Input

​Command Behavior

​Wait After Command

​Abnormal Exit Detection

​Confirm Close

​Scrollback

​Scrollback Limit

​Scrollbar Visibility (macOS)

​Scroll to Bottom

​Mouse Behavior

​Mouse Reporting

​Mouse Shift Capture

​Mouse Scroll Multiplier

​Hide Mouse While Typing

​Click to Move Cursor

​Click Repeat Interval

​Right-Click Action

​Focus Follows Mouse

​Selection

​Selection Colors

​Selection Behavior

​Copy on Select

​Selection Word Characters

​Clipboard

​Clipboard Access

​Clipboard Paste Protection

​Clipboard Trimming

​Clipboard Codepoint Mapping

​Shell Integration

​Auto-Injection

​Shell Integration Features

​Command Notifications (GTK)

​When to Notify

​Notification Action

​Notification Threshold

​Terminal Features

​Image Storage

​Title Reporting

​KAM Mode

​OSC Color Reporting

​Working Directory

​Quit Behavior

​Quit After Last Window

​Quit Delay (Linux)

​Resources

Shell Integration

SSH Configuration

Keybindings

Window Settings

Command Configuration

Default Command

Command Execution Modes

Initial Command

Environment Variables

Command Input

Command Behavior

Wait After Command

Abnormal Exit Detection

Confirm Close

Scrollback

Scrollback Limit

Scrollbar Visibility (macOS)

Scroll to Bottom

Mouse Behavior

Mouse Reporting

Mouse Shift Capture

Mouse Scroll Multiplier

Hide Mouse While Typing

Click to Move Cursor

Click Repeat Interval

Right-Click Action

Focus Follows Mouse

Selection

Selection Colors

Selection Behavior

Copy on Select

Selection Word Characters

Clipboard

Clipboard Access

Clipboard Paste Protection

Clipboard Trimming

Clipboard Codepoint Mapping

Shell Integration

Auto-Injection

Shell Integration Features

Command Notifications (GTK)

When to Notify

Notification Action

Notification Threshold

Terminal Features

Image Storage

Title Reporting

KAM Mode

OSC Color Reporting

Working Directory

Quit Behavior

Quit After Last Window

Quit Delay (Linux)

Resources