Shell Integration

What it buys you

Shell integration is what turns a terminal into something that understands where your prompts are. With it active:

- Closing a terminal sitting at a prompt skips the confirmation dialog. - A new terminal starts in the working directory of the previously focused one. - Complex prompts redraw on resize instead of reflowing, so they do not smear. - ctrl+triple-click (Linux) or cmd+triple-click (macOS) selects the whole output of one command. - The cursor becomes a bar at the prompt, matching text-field behavior. - jump_to_prompt scrolls prompt by prompt through scrollback. - alt+click (option+click on macOS) moves the cursor to the click position at a prompt. - sudo can be wrapped to preserve Ghostty's terminfo, off by default. - ssh can be wrapped to set up the remote environment, off by default.

Supported shells

Ghostty injects integration automatically for bash, elvish, fish, nushell, and zsh. Other shells work fine, they just miss the features above.

shell-integration = detect   # default

Force it when your shell is a supported one under a different name.

Two things to know. The /bin/bash that ships with macOS is too old for automatic injection, so source the script manually or install a current bash. Fish 4.0+ marks prompts natively, so jump_to_prompt, prompt resizing, and prompt selection work there even without Ghostty's integration, and Nushell handles title and cursor itself so its integration focuses on sudo, ssh-env, and ssh-terminfo.

Feature flags

shell-integration-features is a comma-separated list. Prefix a name with no- to turn it off.

# Keep the defaults, add sudo and ssh handling
shell-integration-features = sudo,ssh-env,ssh-terminfo

# Keep everything except the bar cursor
shell-integration-features = no-cursor

Verifying it worked

Look in the Ghostty logs for the injection line.

info(io_exec): shell integration automatically injected
  shell=termio.shell_integration.Shell.fish

These mean something is wrong:

ghostty terminfo not found, using xterm-256color
shell could not be detected, no automatic shell integration will be injected

The usual cause is GHOSTTY_RESOURCES_DIR not pointing at the right place. Automatic injection needs Ghostty to run either from the macOS app bundle or from a location where the contents of zig-out/share sit somewhere above the binary. If you set GHOSTTY_RESOURCES_DIR by hand, validate it by checking that $GHOSTTY_RESOURCES_DIR/../terminfo/ghostty.terminfo exists. Needing to set that variable at all is a sign something else is broken.

Sourcing it manually

Automatic injection only covers the initially launched shell. Run bash, nix-shell, or any other shell inside Ghostty and the integration is lost in that process, though it keeps working in the original shell. Sourcing manually fixes both cases.

GHOSTTY_RESOURCES_DIR is set by Ghostty, so it doubles as the "am I in Ghostty" check. For bash this belongs at the top of ~/.bashrc:

if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
  builtin source \
    "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi

Source it as early as possible. Some bash configurations interfere with the integration if it loads late.

SSH wrapping

ssh-env and ssh-terminfo install a shell function named ssh that routes through Ghostty's +ssh action, which prepares the remote host and then exec's the real ssh.

Because it is a shell function, it is not inherited by child processes. It does not apply to:

- Scripts run as ./script.sh or sh script.sh. Use source script.sh instead. - Tools that spawn ssh themselves: scp, sftp, rsync -e ssh, git over ssh, mosh, gcloud compute ssh, aws ec2-instance-connect ssh. - Non-interactive shells generally, including Makefile recipes and cron jobs.

For those, call ghostty +ssh directly or configure ~/.ssh/config. Note that +ssh itself arrives with Ghostty 1.4.0 and is not in 1.3.x, while the two shell integration features are present in 1.3.x.