OSC 7

AI-Generated Content

This page was generated with the assistance of AI and may contain inaccuracies. It is intended as a placeholder for future human verification. If you spot issues ahead of its initial review, please report them on GitHub!

Experimental

OSC 7 reports the current working directory of the shell to the terminal emulator. This enables smart features such as opening new tabs or splits in the same directory, and displaying the working directory in the tab title.

Syntax

OSC 7 ; file://hostname/path ST
OSC 7 ; file://hostname/path BEL

Formal syntax

OSC7 = 0x1b, "]", "7", ";", uri, ( 0x07 | 0x1b, "\\" ) ;
uri  = "file://", hostname, path ;
hostname = { character } ;
path     = "/", { character } ;

Parameters

Parameter	Description	Default
`hostname`	The hostname of the machine (can be empty)	(empty)
`path`	The percent-encoded absolute path of the current working directory	(required)

Description

OSC 7 is a shell integration protocol that allows the shell to communicate its current working directory to the terminal. The terminal can then use this information to provide enhanced user experience features.

The URI follows the file:// scheme. The hostname component identifies the machine (relevant for remote sessions), and the path component is an absolute filesystem path. Special characters in the path (spaces, non-ASCII characters) should be percent-encoded per RFC 3986.

This sequence is typically emitted from the shell's prompt hook. Common use cases enabled by OSC 7 include:

New tab/split in same directory — The terminal opens new sessions in the reported working directory instead of the default home directory
Tab title display — The terminal can show the current directory name in the tab bar
File path resolution — Clicking on relative paths in terminal output can resolve against the known working directory

OSC 7 was popularized by the VTE (GNOME Terminal) project and has been adopted by many modern terminal emulators. It is not part of the original XTerm specification.

Examples

# Report CWD from a shell prompt hook
printf '\e]7;file://%s%s\a' "$HOSTNAME" "$PWD"

# Bash: add to PROMPT_COMMAND
PROMPT_COMMAND='printf "\e]7;file://%s%s\a" "$HOSTNAME" "$PWD"'

# Zsh: add to precmd hook
precmd() {
  printf '\e]7;file://%s%s\a' "$HOST" "$PWD"
}

# With percent-encoding for paths containing spaces
printf '\e]7;file://localhost/home/user/my%%20project\a'

Specifications

Specification	Section
XTerm ctlseqs	—

Terminal support

Terminal	Support	Version	Notes
Terminal Emulators
Alacritty	✗	No	Not listed in escape_support.md OSC section
Bobcat	✓	0.9.0	WhenDirectoryChange callback for shell integration added in commit 3d1c706
contour	✓	v0.1.1	Current working directory reporting
foot	✓	Yes	Current working directory via URI, osc.c:1372-1375, 457-476
Ghostty	✓	v1.0.0
iTerm2	✓	v20260216-nightly
Kitty	✓	Yes	CWD reporting for shell integration
Konsole	✓	Yes	CurrentDirectory enum value 7 in src/session/Session.h:415
mintty	✓	Yes	Implemented at termout.c:4734-4765, current working directory reporting
mlterm	✗	No
PuTTY	✗	No	Not implemented in do_osc function
Rio	✓	v0.2.3	Parses file:// URL and extracts path for current working directory
rxvt-unicode	✗	No
st	✗	No
terminology	✗	No
VT100	✗	No
VTE	✓	Yes	OSC 7 (VTECWD) handled in vteseq.cc for CWD reporting
WezTerm	✓	Yes	OSC 7 CurrentWorkingDirectory - see wezterm-escape-parser/src/osc.rs:49,351,466
Windows Terminal	✗	No	Not in OscActionCodes enum; falls through to default case (ignored)
xterm	✗	No	No evidence in documentation or source code
xterm.js	✗	No	Not implemented
Multiplexers
cy	✓	v0.11.0
GNU Screen	✗	No
tmux	✓	3.1	VTE extension for working directory
tuios	✓	v0.0.15
Zellij	✗	No

Syntax​

Parameters​

Description​

Examples​

Specifications​

Terminal support​

See also​