Badges

A badge is a large text label that appears in the top right of a terminal session to provide dynamic status, such as the current host name or git branch. Its initial value is defined in Settings>Profiles>General>Badge and it can be changed by an iTerm2-proprietary escape sequence. This value is an interpolated string, which means the badge can expose it can display the value of variables.

Here is an example of a session with a badge indicating the current user and host name.

Escape Sequences

The badge may be set with the following control sequence:

OSC 1337 ; SetBadgeFormat=Base-64 encoded badge format ST

Here's an example that works in bash:

# Set badge to show the current session name and git branch, if any is set.
printf "\e]1337;SetBadgeFormat=%s\a" \
  $(echo -n "\(session.name) \(user.gitBranch)" | base64)

Color

The badge's color may be set in Settings>Profiles>Colors. The font and size can be adjusted by selecting Settings>Profiles>General>Edit… next to the Badge field.