Terminal Behavior Configuration

Configure terminal behavior, PTY settings, scrollback, and shell integration

Command Configuration

Default Command

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

If not set, Ghostty uses:

1. $SHELL environment variable
2. 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

Requires non-zero exit code.

macOS

Allows any exit code (due to login command behavior).

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

Default determined by OS settings.

Other

Default is 500ms.

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

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

Linux

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