[DOCS] Missing tmux configuration for terminal notifications (iTerm2/Kitty/Ghostty popups, progress bar)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

Terminal notification and progress bar settings (near terminalProgressBarEnabled)

Current Documentation

The terminalProgressBarEnabled setting mentions Windows Terminal and iTerm2 as supported terminals. The keybindings page mentions tmux only as a keyboard shortcut conflict. No page documents how to configure tmux to pass through terminal notifications or progress bar sequences.

What's Wrong or Missing?

Changelog v2.1.78 states that terminal notifications (iTerm2/Kitty/Ghostty popups, progress bar) now reach the outer terminal when running inside tmux, but only when set -g allow-passthrough on is configured.

Users running Claude Code inside tmux will not receive terminal notifications unless they add this tmux configuration. This requirement is not documented anywhere, so tmux users have no way to discover why notifications don't work or how to enable them.

Suggested Improvement

Add a tmux configuration note near the terminal notification or progress bar settings:

tmux users: Terminal notifications and the progress bar require passthrough mode. Add set -g allow-passthrough on to your ~/.tmux.conf and reload with tmux source-file ~/.tmux.conf. This allows escape sequences from Claude Code to reach the outer terminal (iTerm2, Kitty, Ghostty).

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/settings | terminalProgressBarEnabled setting and terminal config |
| https://code.claude.com/docs/en/keybindings | Mentions tmux as a shortcut conflict but not notification passthrough |

Total scope: 2 pages affected

Source: Changelog v2.1.78

Terminal notifications (iTerm2/Kitty/Ghostty popups, progress bar) now reach the outer terminal when running inside tmux with set -g allow-passthrough on