Working directory¶

Status: Convention (Apple Terminal origin).

A shell tells the emulator where it is so that new tabs open in the same directory, tab titles show the path, and file links resolve. Three incompatible OSCs do this.

Syntax¶

OSC 7¶

OSC 7 ; file://hostname/path ST

The value is a file: URI. hostname should be the machine's hostname so the emulator can tell a local directory from one seen over SSH; an empty host means localhost. The path is percent-encoded: spaces become %20, non-ASCII bytes are encoded per byte.

Apple Terminal introduced OSC 7 (and OSC 6 for the current document). VTE adopted it in 0.34, and most emulators since.

OSC 1337 CurrentDir¶

OSC 1337 ; CurrentDir=/absolute/path ST

iTerm2's form. The path is plain text, not a URI, and has no host.

OSC 9;9¶

OSC 9 ; 9 ; C:\absolute\path ST

ConEmu's form, adopted by Windows Terminal. The path is a Windows path without encoding. It shares the OSC 9 selector with notifications and progress; see Notifications.

Behavior¶

The emulator stores the path per pane. Use is emulator-defined: inherit in new tabs, show in the tab title, or resolve relative file links.
A path from a remote host is still stored. Emulators that check the hostname in OSC 7 refuse to cd into it locally; emulators that ignore the hostname silently open a non-existent directory.
Nothing is reported back; there is no query form.
tmux does not forward OSC 7 without passthrough, but tracks pane_current_path itself from the process table on platforms that support it.

Shell snippets¶

bash:

__tdn_osc7() {
  printf '\033]7;file://%s%s\033\\' "$HOSTNAME" "$(printf '%s' "$PWD" | sed 's/%/%25/g; s/ /%20/g')"
}
PROMPT_COMMAND="__tdn_osc7${PROMPT_COMMAND:+; $PROMPT_COMMAND}"

zsh:

autoload -Uz add-zsh-hook
__tdn_osc7() { printf '\033]7;file://%s%s\033\\' "$HOST" "${PWD// /%20}" }
add-zsh-hook chpwd __tdn_osc7; __tdn_osc7

fish:

function __tdn_osc7 --on-variable PWD
    printf '\033]7;file://%s%s\033\\' (hostname) (string escape --style=url $PWD | string replace -a '%2F' '/')
end

Most emulators ship their own snippets that also emit OSC 133; prefer those where they exist.

Probe¶

tools/sendosc cwd            # current directory
tools/sendosc cwd /tmp
printf '\033]7;file://%s/tmp\033\\' "$(hostname)"

Open a new tab or window afterwards and check its directory.

Sources¶

Compatibility¶

Feature support by terminal. Imported claims have not been reverified; unknown is not unsupported.
Feature / stable ID	Alacritty	Apple Terminal	ConPTY (conhost)	Contour	DomTerm	foot	Ghostty	iTerm2	kitty	Konsole	mintty	mlterm	PuTTY	Revenant	RLogin	st	tmux	rxvt-unicode	VTE	wayst	WezTerm	Windows Terminal	xterm	xterm.js
OSC 7 `osc-7-working-directory`	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	Unknown	Unknown	Partial	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown
OSC 1337 CurrentDir `osc-1337-current-dir`	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown
OSC 9;9 `osc-9-9-working-directory`	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown