Shell Integration

With shell integration, the command shell running within a terminal reports the username, hostname, current directory, and job information to termy-server via certain escape sequences. This enables a variety of useful features within qtermy and installing it is highly recommended.

termy-server implements the same shell integration escape sequences as the popular iTerm2 terminal emulator. The shell integration scripts provided by that project are compatible with TermySequence.


Shell integration scripts are bundled with termy-server. The termy-setup script provides a convenient way of enabling them. The Setup Tasks dialog displayed by qtermy is a wrapper around this script. The script works by appending code to the user's login scripts, typically .bash_profile, to source the appropriate shell integration script.

It's also possible to skip termy-setup and follow the instructions at iTerm2 shell integration to install shell integration for your shell. See Notes below for shell-specific notes and configuration options.

termy-server defines the environment variable TERMYSEQUENCE within its terminals. Within login scripts, check for this variable before loading or sourcing the shell integration script. This will ensure that it doesn't get loaded by other terminal emulators which might not support the escape sequences. The code written by termy-setup does check for this variable.


Thanks to the iTerm2 project for providing permission to distribute shell integration scripts with TermySequence.


To verify that shell integration is active, open the Terminal Information window using Terminal→View Terminal Information or by clicking the terminal size in the status bar. Check the "Shell Integration Version" property on the Terminal Properties tab as shown in the nearby figure. If it is blank, shell integration is not active.

Picture of Terminal Information window showing shell integration properties on the Terminal Properties tab.

Verifying shell integration in the Terminal Information window.


Shell-specific notes:

The PROMPT_COMMAND environment variable is used to implement bash shell integration. When the shell integration script is sourced, any existing prompt command will be preserved and run as normal. This means that PROMPT_COMMAND should be set before the shell integration script is sourced, not afterward.