Ambient › Guides

tmux focus events and Claude Code

Updated · 3 min read

Add set -g focus-events on to ~/.tmux.conf and run tmux source-file ~/.tmux.conf. tmux then passes focus changes from your terminal to the program in the pane, which is why Claude Code's docs include the line in their tmux setup. It doesn't change when notifications fire: those depend on when you last typed.

Get Ambient Free for macOS 14 and later.

What focus-events does

Many terminals can tell a program when it gains or loses focus. tmux sits between the two, and the option is off by default in tmux. With it on, tmux requests those events from your terminal, if the terminal supports them, and passes them to the program in the pane.

Claude Code's recommended tmux setup includes the line. One user report says Claude Code shows a notice when it's off.

Turn it on and check it

# in ~/.tmux.conf
set -g focus-events on

Reload the config and confirm the value:

tmux source-file ~/.tmux.conf
tmux show-options -s focus-events

The second command should print focus-events on. If you draw images in a Claude Code mod, the docs also ask you to detach, attach again and restart Claude Code.

It won't fix missing notifications

Claude Code's docs time these alerts by typing. A permission alert arrives once you haven't typed for about six seconds, and an idle alert about 60 seconds after Claude finishes, if you haven't typed since. If notifications don't reach you in tmux, the line to check is allow-passthrough. See notifications in tmux and the troubleshooting checklist.

The side effect: false pane activity

One open Claude Code issue reports that with focus events on, the interface redraws on every focus-out. The redraw writes output, which tmux counts as pane activity. If you use tmux's monitor-activity, or a script that reads pane activity, an idle session can look busy. The reporter turned focus-events off to avoid it, so that's the trade-off if you see the same thing.

Ambient doesn't rely on it

Ambient gets each session's state from agent hooks, not from pane output or focus events, so a redraw doesn't make an idle session look busy. It stays quiet while the app running the agent is in front, and a click selects the exact tmux pane.

Stop babysitting terminals.

Free for macOS 14 and later. Works with Claude Code, Codex and Gemini CLI.

Get Ambient

Common questions

Is tmux focus-events on by default?

No, it's off by default. Add set -g focus-events on to ~/.tmux.conf and reload it.

Does focus-events make Claude Code notifications work in tmux?

No. Notifications need set -g allow-passthrough on. Their timing depends on when you last typed.

Why does an idle Claude Code pane show activity in tmux?

One open issue reports that Claude Code redraws on focus-out when focus events are on, and tmux counts that output as activity.

Sources

More guides: Claude Code in tmux · Claude Code notifications in tmux