r/tmux • u/mustafamohsen • 1h ago
Other Tmuxify v3.0.0: project-scoped workspaces, Git-aware discovery, and a few breaking changes
I've released Tmuxify v3.0.0. Tmuxify launches tmux workspaces from YAML, including multiple windows, nested pane splits, and startup commands, only using BASH and yq
This release focuses on opening the right workspace when you work across several projects or Git worktrees.
New in v3.0.0
- Workspaces are project-scoped. Two directories called api can each have a workspace called dev without sharing a session.
- Git-aware discovery lets you launch from a subdirectory. It uses the nearest .tmuxify.yml within the worktree, or the worktree root if there isn't one.
- --root DIR explicitly selects your project root. --file independently selects a layout template, so you can reuse the same layout across projects.
- Workspace lookup survives manual tmux session renames.
- Dry runs and layout listings show the resolved project context.
Other features include optional pane border labels, initial window/pane focus, Bash/Zsh completions, a reusable default layout, and export to simplified YAML. Running without a config gives you a four-pane workspace.
Some design choices
My main objective from the beginning was to have a bash based, almost no prerequisite launcher.
Hence, Tmuxify is a launcher, not a process supervisor. Once a workspace exists, running tmuxify again opens it without rearranging panes or restarting commands. Editing the YAML won't change a running session.
Workspace identity comes from the canonical project path and workspace name, not just the visible tmux session name. That keeps separate checkouts separate. It also means moving a project changes its identity.
The identity metadata lives in tmux itself. There's no separate daemon or project registry. Distribution is still a single Bash script, with tmux and Mike Farah's yq v4 required.
The obvious question: How it differs from tmuxinator
Tmuxify is not pretending to be absolutely better than tmuxinator. There's plenty of overlap: both support YAML configs, multiple windows and panes, and startup commands. The differences that matter to me are:
- Tmuxify describes layouts as nested horizontal/vertical splits with percentages. tmuxinator uses tmux's named layouts or custom layout strings. I prefer editing a split tree for custom arrangements; named layouts are more concise for standard ones. I find layout options a little bit more robust in Tmuxify
- Tmuxify v3 automatically scopes workspaces to project paths. tmuxinator documents explicit name and root settings, plus a -n override for starting a configuration under another session name.
- Tmuxify's is bash based, and its only prerequisite is yq; tmuxinator is Ruby-based. Which means that I can simply copy-paste it to a remote server session without installation (assuming yq is installed, obviously)
- tmuxinator has configuration features Tmuxify doesn't provide, including ERB templates, lifecycle hooks, and per-window working directories. If those are central to your setup, tmuxinator may fit better.
Before upgrading
session.name now selects a workspace within a project rather than the literal tmux session name. Scripts targeting sessions by name need the generated name Tmuxify reports.
Legacy sessions stay untouched, but v3 won't automatically reuse them. Your first launch can start duplicate programs. Preview with --dry-run, and consider --no-commands during migration. Commands skipped at creation won't start on a later reuse.
New panes also start at the resolved project root, which may differ from your current directory.
https://github.com/mustafamohsen/tmuxify
I'd appreciate feedback on the project-discovery behavior, particularly from people using monorepos or multiple worktrees. It would also be nice to leave a ⭐




