{"id":18827195,"url":"https://github.com/mikedacre/tmux-zsh-vim-titles","last_synced_at":"2026-03-07T19:31:26.344Z","repository":{"id":30624524,"uuid":"125305572","full_name":"MikeDacre/tmux-zsh-vim-titles","owner":"MikeDacre","description":"Unified terminal titles in tmux, zsh, and vim/nvim","archived":false,"fork":false,"pushed_at":"2023-09-05T19:28:16.000Z","size":801,"stargazers_count":29,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-07T23:36:52.866Z","etag":null,"topics":["console","shell","terminal","tmux","tmux-plugins","vim","vim-plugins","zsh","zsh-configuration"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MikeDacre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-03-15T03:10:04.000Z","updated_at":"2025-08-03T08:59:09.000Z","dependencies_parsed_at":"2024-01-03T04:29:55.822Z","dependency_job_id":null,"html_url":"https://github.com/MikeDacre/tmux-zsh-vim-titles","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MikeDacre/tmux-zsh-vim-titles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeDacre%2Ftmux-zsh-vim-titles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeDacre%2Ftmux-zsh-vim-titles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeDacre%2Ftmux-zsh-vim-titles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeDacre%2Ftmux-zsh-vim-titles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MikeDacre","download_url":"https://codeload.github.com/MikeDacre/tmux-zsh-vim-titles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeDacre%2Ftmux-zsh-vim-titles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30227788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["console","shell","terminal","tmux","tmux-plugins","vim","vim-plugins","zsh","zsh-configuration"],"created_at":"2024-11-08T01:13:17.523Z","updated_at":"2026-03-07T19:31:26.307Z","avatar_url":"https://github.com/MikeDacre.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unified Tmux-ZSH-Vim Terminal Titles\n\n\nCreates intelligent terminal titles in tmux, zsh, and vim, that work together\nto give information about session, ssh host, path, and currently edited vim\nbuffer. Each part is modular and must be installed separately.\n\nNote: the ZSH component of this is *heavily* influenced by\n[jreese/zsh-titles](https://github.com/jreese/zsh-titles). The other components\nare inspired by a variety of stack exchange answers.\n\n## How it works\n\nThe three components of this plugin work together to make a useful\ncolon-separated title for any combination of tmux, zsh, and vim. For example, if\nyou are in a tmux session on your home computer with zsh at your home directory,\nyour title will be `t:0:~`, if your tmux session was named fred, it would be\n`t:fred:~`. If you then opened `hi.txt` in vim or nvim, it would be\n`t:fred:v:hi.txt`.\n\nIf by contrast, your did those same things over ssh on your remote machine\nhubble, those would be: `t:hubble:0:~`, `t:hubble:fred:~`, `t:hubble:v:hi.txt`\ninstead. If you were the root user on hubble, the starting `t:` would instead be\n`rt:`.\n\n**Note:** A tmux terminal bell results in the title being prefixed with '!'\nuntil an update event (doing something in vim, pressing return in zsh, waiting\nfor status-interval seconds (default 15)).\n\n![tmux-zsh-vim-titles-demo](./unified-titles-demo.gif)\n\n## Installation\n\n### Tmux\n\nInstall with [tpm](https://github.com/tmux-plugins/tpm) by adding the following\nline to your `.tmux.conf`:\n\n```\nset -g set-titles on\nset -g @plugin 'MikeDacre/tmux-zsh-vim-titles'\n```\n\nYou will then need to source your tmux config (`tmux source ~/.tmux.conf`) and\ninstall the plugin by pressing your prefix key combo (defaults to Ctrl+b)\nfollowed by `I` (shift+i). You can update by running your prefix followed by\n`U`.\n\n### ZSH\n\nThe easiest way to install this plugin with ZSH is to use\n[Antigen](https://github.com/zsh-users/antigen) by adding the following line to\nthe apprpriate spot in your `~/.zshrc` file:\n\n```\nantigen bundle MikeDacre/tmux-zsh-vim-titles\n```\n\nYou will then need to reload your zsh configuration (e.g. by starting a new\nshell or sourcing your `~/.zshrc` to install the plugin. You can update by\nrunning `antigen upgrade`.\n\nAlternatively, if you use\n[oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh), you can clone this into\nyour `oh-my-zsh` custom plugin directory:\n\n1. `mkdir -p ${ZSH}/custom/plugins`\n2. `cd ${ZSH}/custom/plugins`\n3. `git clone https://github.com/MikeDacre/tmux-zsh-vim-titles.git`\n4. Add `plugins+=(unified-titles)` to the right spot in your `~/.zshrc` and\n   reloading zsh\n\nTo update you have to `cd` to the plugin directory and run `git pull`.\n\n### Vim/NVIM\n\nThere are a great many plugin managers for vim/nvim right now, I personally use\n[vim-plug](https://github.com/junegunn/vim-plug), to install with that manager,\njust add the following line to the right spot in your `~/.vimrc` or\n`~/nvim/init.vim`:\n\n```\nPlug 'MikeDacre/tmux-zsh-vim-titles'\n```\n\nYou will then need to open a vim/nvim instance and run `PlugInstall` to install\nthe plugin. To update run `PlugUpdate`. The various other plugin managers work\nsimilarly.\n\n### Bash or another sh shell\n\nIf you also use a non-zsh shell, you can source the `bash-titles.plugin.sh` file\nfrom your `~/.bashrc`. It doesn't do anywhere near as much as the ZSH version,\nit simply sets the terminal title to the path, avoiding the otherwise long\ntitles that bash sometimes sets.\n\nIf anyone wants to port the zsh plugin to bash, that would be awesome. It should\nbe pretty easy, but I can't be bothered as I so rarely use bash.\n\n## Configuration\n\nThe plugins will work right out of the box, but the formats can be configured\nwith a variety of shell variables. For example you could change the tmux prompt,\ndisable setting the window tab names, or change the delimiter from `:` to\nsomething else.\n\nAll variables can be set in the shell, and are specified in the `defaults.sh`\nconfig file. Vim variables may also be set in your vimrc, but must be set before\nthe plugin is loaded, not after. All variables start with `tzvt_`, plugin\nspecific variables are followed by the component name, e.g. `tzvt_vim_\u003coption\u003e`\nor `tzvt_tmux_\u003coption\u003e`. Options that affect more that one component do not have\na component name, e.g. `tzvt_set_tmux_window_status` is used by every component.\n\nI recommend that you create a `~/.tzvt_config` file to store all config\nvariables for the titles. You can create it by just duplicating the\n`defaults.sh` file to that location and editing it. To set the location of this\nconfig file, you can set the `$tzvt_config` shell variable and `@tzvt_config`\ntmux variable to point to whatever config file you would like. This will just be\nsourced prior to running the various components, so you could set it to a\n`.bashrc` or `.zshrc` file if you wanted, but I don't recommend that. This file\nis also not required, you can just set all variables in your `.zshrc` and\n`.vimrc` if you prefer.\n\nNote that in tmux, those config files will not be sourced. The tmux component\nis written in bash and explicitly sources your `~/.bashrc` and `~/.profile` in\naddition to the `$tzvt_config` and `defaults.sh` files.\n\nIdeally, you should copy `defaults.sh` to that location and alter it to git your\npreferences. To do that, do the following:\n\n```shell\ncurl https://raw.githubusercontent.com/MikeDacre/tmux-zsh-vim-titles/master/defaults.sh \u003e\u003e ~/.tzvt_config\necho \"source ~/.tmux/profile.sh \u003e\u003e ~/.zshrc\"\necho \"source ~/.tmux/profile.sh \u003e\u003e ~/.bashrc\"\n```\n\nIf you would like your config to be somewhere else (e.g., your existing\nprofile), add the following line to your `~/.tmux.conf`:\n\n```\nset -gq @tzvt_conf ~/.bash_profile\n```\n\n*Reminder*: for the tmux plugin only, the user's `~/.bashrc` and `~/.profile` are\nalso sourced, but it doesn't make sense to rely on this.\n\n### Tmux window updating\n\nBy default, only the terminal title is set by all parts of this plugin, to also\nset a mini version of the title in the status line window names, set\n`$tzvt_set_tmux_window_status` to `true` in your config.\n\n```shell\nexport $tzvt_set_tmux_window_status=true\n```\n\n### Tmux title configuration\n\nTmux is the first part of the title, the default title is `t:\u003csession\u003e:` on a\nlocal machine, or `t:\u003csession\u003e:\u003chostname\u003e` on a remote machine. The `t:` is\nreplaced with `rt` if you are root.\n\nThese variations are controlled by the following optional variables (dafaults\ndisplayed):\n\n- `tzvt_tmux_title_start='t:'`\n- `tzvt_tmux_title_root='rt:'`\n- `tzvt_tmux_title_format='#S:#T'`\n- `tzvt_tmux_title_format_ssh='#h:#S:#T'`\n- `tzvt_tmux_win_current_fmt='#I:#W#F'`\n- `tzvt_tmux_win_other_fmt='#I:#W#F'`\n- `tzvt_host_dict='{}'`\n\nNote, after altering any of these settings, run `tmux source ~/.tmux.conf` to\nimplement the changes.\n\nThe format strings that start with a `#` are tmux specific and can be found in\nthe tmux man page. `#S` is the session name, `#I` is the window number, `#h` is\nthe short hostname, it is modified by `tzvt_host_dict`. This variable holds a\nJSON dictionary as a string and has hostname replacements, e.g.\n`'{\"fraser-server\": \"lab\"}'`. This will convert the hostname fraser-server to\nlab to shorten the title. For example, add something like this to your\n`~/.profile` file and source it from bash and zsh:\n\n```shell\nexport tzvt_host_dict='{\n    \"fraser-server\": \"lab\",\n    \"esmeralda\": \"esme\",\n    \"fruster\": \"fr\"\n}'\n```\nIf the hosts did not load after sourcing, try running the script directly:\n`bash ~/.tmux/plugins/tmux-zsh-vim-titles/unified-titles.tmux`\n\n`#T` is the terminal title and is set by the zsh and vim plugins, without it\nthose other plugins **will not display their titles**.\n\n#### Status Window Renaming\n\nAdditionally, if `$tzvt_set_tmux_window_status` is set to true, the window status\ntabs will also be updated to include the terminal title, by default the window\nstatus is set to '#F#I:#W', equivalent to\n\n```shell\ntmux set-window-option -g window-status-current-format \"#F#I:#W\"\ntmux set-window-option -g window-status-format \"#F#I:#W\"\n```\n\nTo control these formats if `$tzvt_set_tmux_window_status` is true, update the\n`$tzvt_tmux_win_current_fmt` and `$tzvt_tmux_win_other_fmt` config variables, don't set\nthe tmux window options directly, as they will be overwritten.\n\nNote that the window-name will be also be automatically updated by ZSH and\nVim/NVIM (provided the plugin is also installed there), making the window status\ntitle more useful. **Note though** that this will make `tmux rename-window` not\nwork if ZSH or Vim/NVIM are running, as they will continually change the window\ntitle.\n\n### ZSH title configuration\n\nWithout this plugin, the default ZSH title is just the hostname. This plugin\nreplaces this with the directory path or `command:path` if a command is running\nin the terminal.\n\nThere are two variables to customize the ZSH portion of the title:\n\n- `tzvt_zsh_title_fmt='${cmd}:${path}'`\n- `tzvt_zsh_path_width=40`\n\n`tzvt_zsh_title_fmt` controls the overall formatting of the title. Note the single\nquotes, this is very important to prevent the variable from being expanded to\nearly, you must not use `\"{cmd}:${path}\"`, that will result in the string `:`\nbeing passed to the plugin.\n\n`tzvt_zsh_path_width` controls the maximum width of the path to the current directory in\nthe title, if the path is longer than this, only the last n characters of the\npath will be shown. Note, this uses named paths, so HOME is replaced with `~`\nand any hashed directories are replaced with their name, e.g. with\n[cdbk](https://github.com/MikeDacre/cdbk).\n\nIf `tzvt_set_tmux_window_status` is true, then the window-name will be automatically\nupdated with a shortened version of the tzvt_zsh_title_fmt, where `tzvt_zsh_path_width` is\nreplaced by `tzvt_zsh_win_path_width`, which defaults to 25.\n\nNote, ZSH tries to detect if the tmux plugin is installed. If in tmux, it checks\nif the tmux plugin has been initialized. If not in tmux, it looks in the\n`@tmux_plugins` directory for `tmux_zsh_vim_titles`. If you have a non-standard\nplugin config, you probably should set `tzvt_tmux_plugin_installed=true`\nmanually.\n\n### Vim/NVIM title configuration\n\nFor all other commands, the title will be `command:path`, but for vim or NVIM,\ninstead we use `v:\u003cbuffer\u003e`, e.g. `v:README.md` or `v:[BUFEXPLORER]`. This title\nis updated immediately on any buffer change, which makes it very useful.\n\nIf vim is not updating the titlebar correctly, try setting\n`$tzvt_vim_force_tmux_title_change`. If this variable is set, the plugin will force\nchange the window title to the appropriate vim title and will issue shell title\ninstructions to try to force change the terminal title change. This works in\nalmost all cases, but there is a slight visual defect+overhead as the vim buffer\nis redrawn on buffer change. For that reason it is off by default. If your vim\nis not setting the title properly, try adding the following to the `@tzvt_conf`\nconfig, or your `.bashrc`/`.zshrc`/a sourced profile file (only the environment\nof the calling shell matters):\n\n`export tzvt_vim_force_tmux_title_change=true`\n\nAlternatively, for greater robustness, add `let g:tzvt_vim_force_tmux_title_change =\n1` to your `~/.vimrc`.\n\nThe only format that can be changed for the vim title is the prefix, currently\nset as `v:` to keep it out of the way:\n\n- `$tzvt_vim_title_prefix=\"v:\"` OR `let g:tzvt_vim_title_prefix = 'v:'`\n\nNote, you can chose not to install the vim plugin, in which case either you will\nend up with `vim:\u003cpath\u003e` in the title, or another title produced internally by\nvim, depending on your settings.\n\nFinally, if you want to add the path to the terminal and window title also, you\ncan do so with `tzvt_tzvt_vim_include_path`, if this variable equates to `long`, the whole\npath will be included, which can make your titles very large (unless you use ZSH\nnamed dirs, see below), if it is just `true`, then any directories between you\nand the file are included. To set, either edit the config file to include\n`export tzvt_tzvt_vim_include_path='long'` or add the following line to your `~/.vimrc`:\n\n```vim\nlet g:tzvt_tzvt_vim_include_path = 1 \" OR 'long'/'zsh'\n```\n\nOtherwise the path follows the format elsewhere: `t:session:v:file.txt:~/code/`\n\nTo explicily disable the path (the default), set:\n\n```vim\nlet g:tzvt_tzvt_vim_include_path = 0\n```\n\nTo make the path go before the filename (more traditional), add this command to\nyour `~/.vimrc`:\n\n```vim\nlet g:tzvt_vim_path_before = 1\n```\n\n### Long Paths on ZSH, Plus ZSH Named Directories\n\nIf you are using ZSH and Vim, the maximum length of the 'long' path will be set\nat `path_width`, which defaults to *40* chars (this can be overriden just for\nvim by adding `let g:tzvt_vim_pth_width = \u003clen\u003e` to your `~/.vimrc`, or for both vim\nand ZSH by adding `export path_width=\u003clen\u003e` to your `~/.zshrc`.\n\nFurthermore, if you use named directories (specified with `hash -d name=path`),\nthese will be included in the short path. These must be specified in a ZSH\nconfig file, which is defined by `$ZSH_BOOKMARKS` and defaults to\n`~/.zshbookmarks`. You can manage this file with the [cdbk\nplugin](https://github.com/MikeDacre/cdbk).\n\nTo use ZSH paths when in ZSH or no paths at all other times, set\n`g:tzvt_tzvt_vim_include_path` to `zsh`.\n\n### Tmux Window Name Alteration\n\nIf `tzvt_set_tmux_window_status` is true, then the window-name will be automatically\nchanged also, and for the window running vim the current-window-status-format\nwill be updated to use the terminal title instead of window name, which allows\nmore vim sugar in the title. One side-effect of this is that if you have\nmultiple panes running with vim in some of them and non-ZSH shells (or ZSH\nwithout this plugin installed) in the others, then the\ncurrent-window-status-format will not be updated on leaving vim, which could\ngive the other panes a long title.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikedacre%2Ftmux-zsh-vim-titles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikedacre%2Ftmux-zsh-vim-titles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikedacre%2Ftmux-zsh-vim-titles/lists"}