zsh-tmux

zsh-tmux plugin for zsh.

Requirements

This is a list of plugins that need to be installed previously to enjoy all the goodies of this configuration:

• gomplate
• python
• taskfile

Installation

oh-my-zsh users

If you're using oh-my-zsh, install this plugin by doing the following:

1. Go to your oh-my-zsh custom plugins directory: cd ~/.oh-my-zsh/custom/plugins
2. Clone the plugin: git clone https://github.com/hadenlabs/zsh-tmux
3. Edit your .zshrc and add plugins=( ... zsh-tmux ) to your list of plugins
4. Open a new terminal and enjoy!

antigen users

If you're using Antigen, install this plugin by doing the following:

1. Add antigen bundle hadenlabs/zsh-tmux to your .zshrc where you're adding your other plugins.
2. Either open a new terminal to force zsh to load the new plugin, or run antigen bundle hadenlabs/zsh-tmux in a running zsh session.
3. Enjoy!

antibody users

If you're using Antibody, install this plugin by doing the following:

1. Add :

antibody bundle hadenlabs/zsh-tmux

to your .zshrc where you're adding your other plugins.

2. Either open a new terminal to force zsh to load the new plugin, or run antibody bundle hadenlabs/zsh-tmux in a running zsh session.
3. Enjoy!

Usage

How to use this project

What the plugin does

The plugin loads tmux helpers, installs missing runtime dependencies, and synchronizes the repository assets into the expected tmux paths in your home directory.

Post-install behavior

When the plugin is loaded, it ensures the required tools are available and then keeps these paths aligned with the repository data:

• data/conf/.tmux.conf -> ${HOME}/.tmux.conf
• data/sync/tmux/ -> ${HOME_CONFIG_PATH}/tmux/
• data/sync/tmuxinator/templates/ -> ${HOME_CONFIG_PATH}/tmuxinator/templates/

Common workflow

1. Install the plugin with your preferred zsh plugin manager.
2. Run task setup if you are developing in this repository.
3. Reload your shell.
4. Use tmux::post_install or tmux::sync if you need to resync the local tmux assets manually.

Interactive helpers

• edittmux opens the generated tmux config file in ${EDITOR}
• tx::project lets you select a tmuxinator template with fzf and starts in a single workspace window with panes for editing, app work, opencode, shell, and commands
• ftm switches to or creates tmux sessions
• ftmk deletes tmux sessions

Examples

Common

Install Dependencies

task setup

Functions

zsh tmux includes a small utility tmux.

Public functions and aliases

tmux::dependences

Checks and installs the dependencies required by the plugin.

tmux::post_install

Runs the post-install sync flow for tmux and tmuxinator assets.

tmux::sync

Synchronizes data/conf/.tmux.conf into ${HOME}/ and data/sync/ into ${HOME_CONFIG_PATH}/.

tmux::install

Installs tmux using the platform-specific implementation.

edittmux

Opens ${TMUX_FILE_SETTINGS} in the configured ${EDITOR}.

tx::project name_project

Selects a tmuxinator template with fzf and starts a tmuxinator project in a single optimized workspace window that includes an opencode pane. If no name is passed, it uses the current directory name.

tx

Alias for tmuxinator when the command is available.

ftm

Creates a new tmux session or switches to an existing one.

ftmk

Deletes a tmux session.

Help

Got a question?

File a GitHub issue.

Contributing

See Contributing.

Module Versioning

This Module follows the principles of Semantic Versioning (SemVer).

Using the given version number of MAJOR.MINOR.PATCH, we apply the following constructs:

1. Use the MAJOR version for incompatible changes.
2. Use the MINOR version when adding functionality in a backwards compatible manner.
3. Use the PATCH version when introducing backwards compatible bug fixes.

Backwards compatibility in 0.0.z and 0.y.z version

• In the context of initial development, backwards compatibility in versions 0.0.z is not guaranteed when z is increased. (Initial development)
• In the context of pre-release, backwards compatibility in versions 0.y.z is not guaranteed when y is increased. (Pre-release)

Copyright

Copyright © 2018-2026 Hadenlabs

Trademarks

All other trademarks referenced herein are the property of their respective owners.

License

The code and styles are licensed under the LGPL-3.0 license See project license..

Don't forget to 🌟 Star 🌟 the repo if you like zsh-tmux

Your feedback is appreciated