Tmuxedo: A Cleaner, Modular Approach to Tmux Configuration

Tmuxedo helps you break down your tmux configuration into modular files and manage plugins in a clean, structured way.
Maintainable, extensible, and fast - keep your tmux setup under control.

---

✨ Features

• 🔧 Modular config – split your .tmux.conf into logical, reusable files
• 📦 Built-in plugin manager – declarative config, zero boilerplate
• 🔄 Automatic plugin updates – clones and keeps plugins up to date
• ⚡ One command to rule them all – apply config + plugins in one shot

---

📦 Installation

Homebrew (macOS & Linux)

brew install aranborkum/tap/tmuxedo

Install from crates.io:

cargo install --locked tmuxedo

Or build from source:

git clone https://github.com/AranBorkum/tmuxedo
cd tmuxedo
cargo install --locked --path .

---

🚀 Getting Started

Running tmuxedo for the first time sets up:

• ~/.config/tmux/tmuxedo/ – your modular config directory
• ~/.local/share/tmuxedo/plugins/ – plugin installation directory
• ~/.config/tmux/tmuxedo/plugins.conf – your plugin manifest

Add this line to the end of your .tmux.conf to hook it all up:

run-shell 'tmuxedo'

---

🛠 Adding Config Files

Drop .conf files into ~/.config/tmux/tmuxedo/. You can name them however you like.

Example: bindings.conf

unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

unbind r
bind r run-shell tmuxedo

---

🔌 Managing Plugins

Via TUI

Run the built-in terminal UI:

tmuxedo --tui

Or use the key binding: <prefix> + C-t (defined by default).

The TUI lets you:

• Install plugins from the known list
• Update or remove existing plugins
• Add new ones manually

If a plugin isn't listed, manually add it to plugins.conf, and consider submitting a PR to include it for others!

---

🔄 Applying Changes

To apply your full configuration (including plugins), just run:

tmuxedo

For convenience, bind it to a key in tmux (e.g. <prefix> + r):

bind r run-shell tmuxedo

---

⚠️ Important Update (v0.1.12+)

Breaking Change for Existing Users: As of version 0.1.12, installed plugins now include the GitHub username in their directory name (e.g., username_repo_name) to prevent namespace conflicts.

How to Update: If you are upgrading from an older version, you must clear your old plugins directory to allow tmuxedo to re-install them with the correct structure.

1. Delete your existing plugins directory:

   rm -rf ~/.config/tmux/plugins

2. Re-run tmuxedo to re-install plugins with updated naming convention.

⚠️ Important Update (v0.1.14+)

Change for Existing Users:
As of version 0.1.14, a banner is now displayed at the top of the TUI. To accommodate this, the popup dimensions have changed.

How to Update:
Add the flags -w 80% -h 80% (recommended) after display-popup in tmuxedo.conf, or simply delete tmuxedo.conf and re-run tmuxedo to regenerate it.

1. Delete your existing config file:

   rm -f ~/.config/tmux/tmuxedo/tmuxedo.conf

2. Re-run tmuxedo to regenerate the config file

⚠️ Important Update (v0.1.15+)

Change for Existing Users

As of v0.1.15, plugins are now installed in:

~/.local/share/tmuxedo/plugins

instead of the config directory.

Tmuxedo will automatically reinstall your plugins in the new location on first run.

The old directory:

~/.config/tmux/tmuxedo/plugins

can be safely deleted.

---

🙌 Contributions Welcome

Found a bug? Want to suggest a plugin or feature?
Open an issue or PR on GitHub!

Support

If you find Tmuxedo useful and would like to support its development, you can buy me a coffee ☕ — it’s very much appreciated!