wezterm set-working-directory

Notify the terminal of the current working directory using OSC 7

The set-working-directory command emits an OSC 7 escape sequence to advise the terminal of the current working directory.

Synopsis

wezterm set-working-directory [OPTIONS] [CWD] [HOST]

Description

This command emits an OSC 7 (Operating System Command 7) escape sequence that informs the terminal emulator about the current working directory. This is useful for:

• Enabling semantic terminal features based on directory context
• Allowing new tabs/panes to open in the same directory
• Integration with shell prompts and directory-aware tools
• Working with remote sessions over SSH

Many shells can be configured to automatically emit this sequence, but this command provides manual control when needed.

Arguments

CWD · path

The directory to specify.

If omitted, will use the current directory of the process itself (equivalent to $PWD or $(pwd)).

Example:

wezterm set-working-directory /home/user/projects
wezterm set-working-directory ~/Documents

HOST · string

The hostname to use in the constructed file:// URL.

If omitted, the system hostname will be used. This is particularly useful when working on remote systems via SSH.

Example:

wezterm set-working-directory /home/user server.example.com

Options

--tmux-passthru · enum

How to manage passing the escape sequence through to tmux.

Possible values:

• disable - Don’t use tmux passthrough
• enable - Always use tmux passthrough
• detect - Automatically detect if running in tmux (default)

When running inside tmux, the OSC 7 sequence needs special handling to pass through tmux to the outer terminal.

Example:

wezterm set-working-directory --tmux-passthru enable

Examples

Set to current directory

wezterm set-working-directory

This uses the current working directory ($PWD).

Set to specific directory

wezterm set-working-directory /home/user/projects/myapp

Set with custom hostname

wezterm set-working-directory /var/www production-server

This creates a URL like: file://production-server/var/www

Use in shell prompt

Add to your .bashrc or .zshrc:

# Bash
function set_wezterm_cwd() {
  wezterm set-working-directory
}
PROMPT_COMMAND="set_wezterm_cwd;$PROMPT_COMMAND"

# Zsh
function set_wezterm_cwd() {
  wezterm set-working-directory
}
precmd_functions+=(set_wezterm_cwd)

Use in fish shell

Add to your config.fish:

function __wezterm_set_cwd --on-variable PWD
  wezterm set-working-directory
end

Inside tmux

wezterm set-working-directory --tmux-passthru enable

With directory change

cd ~/projects/myapp && wezterm set-working-directory

Integration with Shells

Bash

Add to ~/.bashrc:

if [ -n "$WEZTERM_EXECUTABLE" ]; then
  function _wezterm_set_cwd() {
    wezterm set-working-directory 2>/dev/null
  }
  PROMPT_COMMAND="_wezterm_set_cwd;${PROMPT_COMMAND}"
fi

Zsh

Add to ~/.zshrc:

if [[ -n "$WEZTERM_EXECUTABLE" ]]; then
  function _wezterm_set_cwd() {
    wezterm set-working-directory 2>/dev/null
  }
  autoload -Uz add-zsh-hook
  add-zsh-hook precmd _wezterm_set_cwd
fi

Fish

Add to ~/.config/fish/config.fish:

if set -q WEZTERM_EXECUTABLE
  function __wezterm_set_user_var_on_cwd --on-variable PWD
    wezterm set-working-directory 2>/dev/null
  end
  __wezterm_set_user_var_on_cwd
end

PowerShell

Add to your PowerShell profile:

if ($env:WEZTERM_EXECUTABLE) {
  function Set-WeztermCwd {
    wezterm set-working-directory 2>$null
  }
  
  # Call on prompt
  function Prompt {
    Set-WeztermCwd
    # Your normal prompt here
  }
}

OSC 7 Sequence Format

The OSC 7 sequence has the format:

\033]7;file://HOSTNAME/PATH\033\\

For example:

\033]7;file://laptop/home/user/projects\033\\

WezTerm automatically:

1. Converts the provided path to an absolute path
2. URL-encodes special characters
3. Constructs the proper file:// URL
4. Emits the OSC 7 sequence

Use Cases

New tabs inherit directory

When you open a new tab in WezTerm, it can automatically use the current working directory of the active pane:

-- In wezterm.lua
return {
  default_cwd = wezterm.home_dir,
}

With OSC 7 properly set, new tabs will open in the actual current directory.

SSH sessions

When working on a remote server via SSH:

ssh user@remote
cd /var/log
wezterm set-working-directory /var/log remote-server

Now WezTerm knows you’re in /var/log on remote-server.

Directory-aware features

Some WezTerm features use the current directory:

• File path completion
• Quick file opening
• Status bar showing current directory

Semantic zones

WezTerm can use directory information for semantic zones, allowing you to:

• Navigate between command outputs
• Select entire commands with their output
• Copy commands without the output

Troubleshooting

OSC 7 not working in tmux

Make sure to use:

wezterm set-working-directory --tmux-passthru detect

Or configure tmux to pass through escape sequences:

set -g allow-passthrough on

Directory not updating in new tabs

1. Check that your shell is calling set-working-directory
2. Verify the escape sequence is being emitted:
   wezterm set-working-directory && echo "Done"
   
3. Check your WezTerm configuration

Spaces in directory names

The command handles spaces automatically:

wezterm set-working-directory "/home/user/My Documents"

Manual OSC 7 Emission

If you prefer not to use the wezterm command, you can emit OSC 7 directly:

# Bash/Zsh
printf '\033]7;file://%s%s\033\\' "$HOSTNAME" "$PWD"

However, using wezterm set-working-directory is recommended as it handles:

• URL encoding
• Hostname detection
• Tmux passthrough
• Path normalization

Related

• wezterm start - Start terminal with specific directory
• wezterm imgcat - Display images in terminal
• WezTerm Shell Integration Documentation