OSC 7 — Report current working directory (file:// URL)

OSC 7 ; file://host/path ST tells the terminal the shell's current working directory as a file URL. Terminals use it to open new tabs/splits in the same directory and to resolve relative paths in hyperlinks. Emitted by the shell from a precmd/PROMPT_COMMAND hook. Originated with iTerm2; now broadly supported.

aka: report cwd · current working directory · OSC 7 · ESC ] 7 · cwd reporting

frame

OSC introducer: \x1b] ESC ] (0x1B 0x5D)

terminator (ST|BEL): ST \x1b\ · BEL \x07

parameters / subcommands

id	name	bytes (ST)	meaning
set	Report cwd	\x1b]7;file://myhost/home/user/project\x1b\	OSC 7 ; file://HOST/PATH ST reports the shell's current working directory. HOST is the hostname (so the terminal can tell local vs remote/ssh) and PATH is the absolute, percent-encoded path. The shell emits this from precmd / PROMPT_COMMAND after each directory change.

support matrix

terminal	level	since	notes
iTerm2	full	documented	Origin of OSC 7 cwd reporting; opens new sessions in the reported directory.
VTE / GNOME Terminal	full	VTE 0.38+	Uses the file:// URI to spawn new terminals in the same directory.
WezTerm	full	documented	Reads OSC 7 to spawn tabs/panes in the current directory.
kitty	full	documented	Honors OSC 7 for new-window cwd inheritance.
Windows Terminal	full	documented	Uses OSC 7 to duplicate tabs in the same working directory.

gotchas

The PATH component must be percent-encoded per RFC 3986: spaces become %20, etc. Emitting a raw space or other reserved char yields a malformed URL the terminal may ignore.
Include the hostname so the terminal can distinguish a local cwd from one over ssh; an empty host (file:///path) is interpreted as localhost.
OSC 7 reports the directory; it does NOT mark prompt/command boundaries — that is OSC 133. They are commonly emitted together from the same precmd hook.
OSC 7 is distinct from OSC 8 (hyperlinks) and from OSC 6 (some terminals' 'current file' / document URI); do not conflate.
Emit it from precmd / the PROMPT_COMMAND, after cd, so the terminal's notion of cwd stays in sync with the shell.

provenance

source: https://iterm2.com/documentation-escape-codes.html
version: iTerm2 Proprietary Escape Codes, retrieved 2026-05-29
retrieved: 2026-05-29 · updated: 2026-05-29T00:00:00Z

per-fact attribution:

#summary — https://iterm2.com/documentation-escape-codes.html iTerm2 documents OSC 7 ; file://hostname/path as the way the shell reports its current directory so iTerm2 can open new sessions in the same place.
#set — https://gnome.pages.gitlab.gnome.org/vte/gtk4/group__VteTerminal.html VTE (GNOME Terminal) documents OSC 7 file:// URI as the current-directory / current-file URI used to open new terminals in the same directory.
#set — https://wezterm.org/shell-integration.html WezTerm shell-integration docs describe emitting OSC 7 ; file://HOST/CWD so WezTerm knows the cwd for spawning tabs/panes (second independent source for the file:// form).

agent: curl -H 'accept: application/json' wire.phall.io/terminal-osc/7 or /terminal-osc/7.json