Bookmark the directories and files you use for a project under its tmux window name. Jump back with cdh, switch to a related directory with cd1, or open a saved file with f0.

Built for engineering workflows where project files, reports, and shared resources live across the filesystem.

• 10 directory and 10 file slots per window name, numbered 0–9.
• Shell shortcuts for navigating, editing, listing, swapping, and clearing bookmarks.
• Persistent local storage, backed by Python's standard library with no runtime Python dependencies.

Quick start

Use Linux or macOS with tmux on your PATH, uv, and Python 3.11 or later.

Install from PyPI:

uv tool install tmux-path-store

git clone https://github.com/smprather/tmux-path-store.git
cd tmux-path-store
uv tool install .

Enable shortcuts in your current Bash session; see shell setup for other shells and permanent configuration:

eval "$(tmux-path-store --bash)"

Inside tmux, give your window a project name and try these commands with your own project paths:

tmux rename-window board-rev-a
cd /work/board-rev-a

shd                       # Save this project's home directory in slot 0
sd1 ./reports             # Save a related directory in slot 1
sf0 ./constraints.sdc      # Save an existing file in file slot 0

cd1                       # Jump to the reports directory
cdh                       # Return to the project's home directory
f0                        # Open the saved file in your editor

Shell setup

Add the matching initialization command to your shell's startup file, then reload it or open a new shell.

--dash, --ksh, and --mksh select the same hooks as --sh; --tcsh is an alias for --csh.

mkdir $nu.default-config-dir
let hook = ($nu.default-config-dir | path join 'tmux-path-store.nu')
tmux-path-store --nu | save --force $hook
print $"source '($hook)'"

tmux-path-store --pwsh | Out-String | Invoke-Expression

exec($(tmux-path-store --xonsh))

Commands

In the table below, replace N with a slot number from 0 to 9. Directory and file slots are independent.

Directory arguments are made absolute when saved. File arguments are stored as absolute paths; files that do not exist yet are allowed. Each new window name needs a saved directory or file before you can navigate or edit its slots.

Editors

File shortcuts use EDITOR, falling back to vi. For example, in Bash or Zsh:

export EDITOR='code --wait'

Arguments follow POSIX quoting rules in every shell. Quote executable paths containing spaces inside the value, for example EDITOR='"/opt/My Editor/bin/editor" --wait'. Shell operators and variable references in the value are not evaluated.

ef warns about empty slots and opens the defined ones; it fails if none are defined. Missing files are opened anyway after a warning, so an editor can create them. Editor exit codes are preserved. In PowerShell, inspect $LASTEXITCODE.

Storage and scripting

Bookmarks persist across tmux restarts in ${XDG_STATE_HOME:-~/.local/state}/tmux_path_store/db.json. Writes are atomic, coordinated with file locks, and use file permissions 0600. The file is a versioned object; unset slots are simply absent, and stored slots record when they were saved and last used:

{"version": 2, "windows": {"board-rev-a": {"dirs": {"0": {"path": "/work/board-rev-a", "saved_at": 1790000000000000000}}, "files": {}}}}

Older list and version-1 formats are migrated on the next write. recent ranks the current window's entries by last_used, then saved_at.

The CLI also works without the shortcuts:

tmux-path-store set-dir 0 /work/board-rev-a
tmux-path-store set-file 0 /work/board-rev-a/constraints.sdc
tmux-path-store get-dir --json 0
tmux-path-store get-file --null 0
tmux-path-store open-files 0

get-dir and get-file return newline-terminated paths by default; use --json for a JSON string or --null for NUL-terminated output. Check the exit status before consuming output; diagnostics go to stderr.

Set TMUX_WINDOW to select a saved window explicitly in scripts:

TMUX_WINDOW=board-rev-a tmux-path-store get-dir 0

Otherwise, TMUX_PANE identifies the invoking pane's window when available. Commands that only read saved data (lw, ld/lf with explicit windows) work without a reachable tmux server. Resolving the active window outside tmux uses the server's most recently used client, so scripts should set TMUX_WINDOW. open-files launches the editor directly; data commands print data, not shell code. csh/tcsh navigation is the exception: csh-cd returns the path of a private, self-deleting source file.

Development

uv sync --locked
uv run python -m unittest discover -s tests -p 'test_*.py'
uv run ruff check tmux_path_store tests
uv run ty check tmux_path_store tests

Local integration tests exercise installed shells; CI requires all 12 supported shell names. tmux tests use private sockets and clean up only their own sessions. CLI and storage logic live in tmux_path_store/__init__.py; shell hooks live in tmux_path_store/shell_templates/ and are loaded by tmux_path_store/shells.py.

Versions and release tags use CalVer YYYY.M.N, with no v prefix or zero padding. M is the month and N starts at 1 each month; for example, 2026.10.5, then 2026.11.1 at the next month's first release. Run tmux-path-store --version to inspect the installed version.