DECSET 1004 — Focus reporting

CSI ? 1004 h enables focus event reporting: the terminal sends CSI I when the window gains focus and CSI O when it loses focus. CSI ? 1004 l disables it. Apps use this to pause animations, refresh on focus, or change cursor styling.

terminal-dec-private-mode kind control-sequence status de-facto verification verified tier B terminal-escape@1

aka: focus reporting · focus events · DECSET 1004 · ?1004h / ?1004l · CSI I · CSI O

frame

DEC-private-mode introducer: \x1b[? ESC [ ? (0x1B 0x5B 0x3F)

terminator (none): ST · BEL

parameters / subcommands

id	name	bytes (ST)	meaning
set	Enable (DECSET)	\x1b[?1004h	CSI ? 1004 h enables focus reporting: on focus-in the terminal sends ESC [ I (CSI I) and on focus-out ESC [ O (CSI O).
reset	Disable (DECRST)	\x1b[?1004l	CSI ? 1004 l disables focus reporting; no focus events are sent.

gotchas

The focus reports arrive on the INPUT stream as CSI I (in) and CSI O (out); your input parser must recognize and consume them or they leak into the application as stray keystrokes.
CSI O (focus-out) shares its final byte 'O' with SS3-style sequences in some contexts; disambiguate by the CSI (ESC [) introducer vs SS3 (ESC O).
Not all terminals/multiplexers forward focus events; feature-detect rather than assume.
Disable focus reporting (?1004l) on exit so the next program doesn't receive unexpected CSI I/O.
Over tmux, focus events require the appropriate passthrough/focus-events setting to reach the inner program.

provenance

source: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
version: xterm ctlseqs, patch #410, 2026/04/19
retrieved: 2026-05-29 · updated: 2026-05-29T00:00:00Z

per-fact attribution:

#summary — https://invisible-island.net/xterm/ctlseqs/ctlseqs.html xterm ctlseqs: Ps = 1 0 0 4 -> Send FocusIn/FocusOut events. The terminal reports focus gained as CSI I and focus lost as CSI O.

DECSET 1004 — Focus reporting

frame

parameters / subcommands

gotchas

provenance

see also