What's the safe way to detect the terminal's current background colour?

Use OSC 11 query (\x1b]11;?\x07) — it returns the foreground colour as an rgb:RRRR/GGGG/BBBB reply. DECRQSS itself queries SGR / mode state, not RGB. The query/reply pattern: write the query, set a 100–200 ms read timeout on stdin, parse the reply (\x1b]11;rgb:1e1e/1e1e/1e1e\x07 or \x1b\\ terminated), then derive luma to pick a contrasting foreground for your output. Terminals that don't support OSC 11 — older xterm, Apple Terminal.app pre-2021, Linux console — silently drop the query and your timeout fires; in that case fall back to $COLORFGBG (set by some shells / terminals) or assume dark.

Which terminals respond to DECRQSS?

xterm (the originator), kitty, WezTerm, foot, Alacritty, Ghostty and Windows Terminal ≥ 1.21 respond to DECRQSS for the standard subset: SGR (\x1bP$qm\x1b\\), cursor shape (\x1bP$q q\x1b\\), DECSTBM scroll-region, and a handful of DEC private modes. Apple Terminal.app, gnome-terminal, konsole, Linux console / fbcon, and screen 4.x do *not* implement DECRQSS — the query is silently dropped. Always set a read timeout (100–200 ms is standard) and have a hardcoded $TERM-based fallback table; never assume the reply will arrive.

DECRQSS — Request Selection or Setting (DCS $ q ... ST)

Ask the terminal to report the current value of any SGR / mode / margin / cursor-shape setting — the catch-all DCS query.

Byte forms

Every common string-literal form so you can paste-and-search either direction.

\\x1b[\x1bP$q\x1b\\

\\033[\033P$q\033\\

\\e[\eP$q\e\\

ESC [ESC P $ q ESC \

hex1b 50 24 71 ... 1b 5c

Description

Request Selection or Setting. A DCS frame whose intermediate is $ (0x24) and final is q (0x71); the body  names the setting whose value the application wants reported. Common probes: \x1bP$qm\x1b\\ asks for the active SGR attributes (terminal replies \x1bP1$rm\x1b\\ listing the current colour/style stack), \x1bP$q r\x1b\\ (the literal sequence $ q SP r) reports DECSTBM scroll-region margins, \x1bP$q" p\x1b\\ reports the DECSCL conformance level, \x1bP$q" q\x1b\\ reports DECSCA character protection, and \x1bP$q q\x1b\\ ( SP q) reports the active DECSCUSR cursor shape. The reply uses the same DCS shape — leading byte 1 (valid + supported) or 0 (invalid request), then $r, the requested-setting bytes, and ST. Modern apps use DECRQSS in startup probes so they can restore the terminal's pre-existing state when they exit — vim's t_RV autodetection, bat's syntax-theme picker, and kitty kitten themes all rely on it.

Spec citation: xterm-ctlseqs (DECRQSS, DCS $ q Pt ST)

Examples

bash

# Ask for the current SGR attributes; reply lands on stdin in raw mode.\nstty -echo raw min 0 time 5\nprintf '\033P$qm\033\\'; IFS= read -r -t 1 -d '\\' REPLY; stty sane\necho "DECRQSS m reply: $REPLY"

python

import sys; sys.stdout.write('\x1bP$qm\x1b\\\\')   # reply arrives on stdin

fmt.Print("\x1bP$qm\x1b\\\\")   // request current SGR

javascript

process.stdout.write('\x1bP$qm\x1b\\\\')   // request current SGR; read process.stdin

printf("\x1bP$qm\x1b\\\\"); fflush(stdout); /* read DCS reply from stdin */

Used in

Real-world tools that emit this sequence — anchors the bytes to commands you've already used.

vim, neovim — terminal capability probe (`t_RV`, `&background` detection)on startup vim emits `\x1bP$qm\x1b\\` to read the current SGR state and `\x1bP$q q\x1b\\` (` SP q`) to read the cursor shape — so when you `:q!` vim, the cursor returns to the exact bar / block / underline you had before, not vim's hard-coded default
kitty `kitten themes` and `kitten icat` probethe `themes` kitten queries DECRQSS to read the current SGR palette and the cursor-shape parameter before mutating the live config — so a `kitten themes solarized-light` swap inverts SGR mappings cleanly without clobbering a custom blinking-block cursor
bat — auto-theme picker for `--theme=auto``bat --theme=auto` probes `\x1bP$qm\x1b\\` to read the active SGR, then if no clear default-bg signal arrives, falls through to OSC 11 + DECRQSS `" p` (conformance level) to decide between the light and dark syntax theme rather than guessing from `$TERM`
tmux passthrough wrapper (`allow-passthrough on`)tmux strips DCS by default — enabling `allow-passthrough on` lets vim inside tmux pass `\x1bP$qm\x1b\\` to the outer terminal and route the reply back, so the inner editor sees the *outer* terminal's state instead of tmux's synthesised one (which has no cursor-shape concept)
Ghostty / WezTerm / xterm feature-detection scriptsshell helpers like `terminal-capabilities.sh` and `vim-terminfo-probe` walk DECRQSS for every SGR / DECSCUSR / DECSTBM setting at session start, write the answers into `~/.cache/terminal-state.json`, and downstream apps read that file instead of re-probing — turns a noisy multi-roundtrip handshake into a single cached read

Frequently asked

Short answers to the questions developers actually search for this sequence.

What's the safe way to detect the terminal's current background colour?: Use OSC 11 query (\x1b]11;?\x07) — it returns the foreground colour as an rgb:RRRR/GGGG/BBBB reply. DECRQSS itself queries SGR / mode state, not RGB. The query/reply pattern: write the query, set a 100–200 ms read timeout on stdin, parse the reply (\x1b]11;rgb:1e1e/1e1e/1e1e\x07 or \x1b\\ terminated), then derive luma to pick a contrasting foreground for your output. Terminals that don't support OSC 11 — older xterm, Apple Terminal.app pre-2021, Linux console — silently drop the query and your timeout fires; in that case fall back to $COLORFGBG (set by some shells / terminals) or assume dark.
Which terminals respond to DECRQSS?: xterm (the originator), kitty, WezTerm, foot, Alacritty, Ghostty and Windows Terminal ≥ 1.21 respond to DECRQSS for the standard subset: SGR (\x1bP$qm\x1b\\), cursor shape (\x1bP$q q\x1b\\), DECSTBM scroll-region, and a handful of DEC private modes. Apple Terminal.app, gnome-terminal, konsole, Linux console / fbcon, and screen 4.x do *not* implement DECRQSS — the query is silently dropped. Always set a read timeout (100–200 ms is standard) and have a hardcoded $TERM-based fallback table; never assume the reply will arrive.

Common typos / look-alikes

Wrong forms developers commonly paste from Stack Overflow that look right but aren't — with the canonical correction inline.

\x1bP$qm\x1b (only ESC, missing the \\ of ST)\x1bP$qm\x1b\\ (ESC \\ = ST, the proper DCS terminator)
Every DCS frame must terminate with ST — \x1b\\ (ESC followed by \, hex 1b 5c) — not bare ESC. Without the trailing \\, the terminal keeps the DCS parser in string state and silently appends the next bytes (your shell prompt, next program's output, anything) onto the DCS payload until it sees ST. Symptoms: terminal appears frozen / unresponsive for one keystroke, then a chunk of text vanishes (consumed as the never-finished DCS body). xterm-strict and Ghostty enforce ST rigidly; kitty / wezterm tolerate bare BEL as a fallback terminator for OSC but NOT for DCS. Always emit the full 2-byte ST.
read DECRQSS reply with a fixed read(fd, buf, 16) and bailread until ST is seen — typical reply lengths range 8–64 bytes (SGR state stack can be longer); use a timeout-bounded incremental read
DECRQSS replies are variable-length DCS frames: \x1bP1$r<body>\x1b\\. The <body> for SGR ($qm query) lists the current SGR stack — 0 after a reset, or 0;1;38;5;196;48;2;30;30;30 after stacking truecolour and palette colours, etc. A fixed 16-byte read truncates the middle of the stack, your parser sees a malformed frame, and the *next* application's stdin starts with the orphan tail bytes. Worse, the reply can take 100–1000 ms to arrive (network-attached terminals, tmux DCS-passthrough). Robust pattern: set stdin non-blocking with a 200–500 ms timeout, read in 64-byte chunks, accumulate until you see ST (\x1b\\) or hit the timeout — same shape as XTGETTCAP and DECRQM reply handling.
\x1bP+qm\x1b\\ (intermediate + from XTGETTCAP) to request current SGR\x1bP$qm\x1b\\ (intermediate $, hex 0x24)
DCS intermediate byte distinguishes the request *family*: $ (0x24) is DECRQSS (request the current value of a setting, reply body is $r<value>); + (0x2b) is XTGETTCAP (request a terminfo capability by hex-encoded name, reply body is +r<hexname>=<hexvalue>). The two have different reply shapes, different payload encodings, and different terminal support — kitty / wezterm / ghostty support both, alacritty supports XTGETTCAP but not DECRQSS, screen supports neither. Sending \x1bP+qm\x1b\\ makes the terminal try to look up a terminfo cap literally named m (which doesn't exist) and reply \x1bP0+rm\x1b\\ — "unknown cap" — not the SGR state you wanted.

Terminal support

xterm: yes
Linux console (fbcon): no
macOS Terminal.app: no
iTerm2: partial
Windows Terminal: partial
cmd.exe / ConPTY: no
kitty: yes
alacritty: no
WezTerm: yes
Ghostty: yes
GNOME Terminal: partial
Konsole: partial
tmux: partial
GNU screen: no

xterm	Linux console (fbcon)	macOS Terminal.app	iTerm2	Windows Terminal	cmd.exe / ConPTY	kitty	alacritty	WezTerm	Ghostty	GNOME Terminal	Konsole	tmux	GNU screen
yes	no	no	partial	partial	no	yes	no	yes	yes	partial	partial	partial	no

Related sequences

In the family cookbook

DCS cookbook · 3. Asking the terminal questions — DECRQSS, terminfo cap, DECRQTSR, DECRQUPSS, cursor-style