tmuxinator

Create a new project

$ tmuxinator new [project]

$ tmuxinator edit [project]

$ tmuxinator list

$ tmuxinator start [project]

$ tmuxinator stop [project]

tmuxinator command [args]
Common commands include:
tmuxinator start project_name [args]
tmuxinator new project_name
tmuxinator edit project_name
tmuxinator list

start [args]
    Starts or attaches to a tmux session for the specified project. Additional arguments are passed directly to `tmux`.

new
    Creates a new project configuration file (e.g., `~/.config/tmuxinator/.yml`) and opens it for editing in the `$EDITOR`.

edit | open | config
    Opens the configuration file for the specified project in `$EDITOR`. These are aliases for the same functionality.

list | ls
    Lists all available tmuxinator projects that have configuration files.

delete | rm
    Deletes the specified project's configuration file.

stop
    Stops the `tmux` session associated with the project, if it is currently running.

local [name]
    Creates a `.tmuxinator.yml` file in the current directory. This is useful for project-specific configurations that live with the codebase. An optional `name` can be provided for this local project.

debug
    Outputs the processed project configuration, including resolved paths and variables. This is very useful for troubleshooting issues with project startup.

doctor
    Diagnoses potential issues with the tmuxinator installation, `tmux` setup, and environment variables.

implode
    Deletes all tmuxinator project configuration files from the default configuration directory. Use with caution.

version
    Displays the installed tmuxinator version.

help [command]
    Shows help information for a specific command or for `tmuxinator` itself if no command is specified.

tmuxinator is a powerful command-line tool that simplifies the management of `tmux` sessions. It allows users to define complex `tmux` window, pane, and command layouts for specific projects using simple YAML configuration files. Instead of manually creating windows and splitting panes every time you start a project, tmuxinator automates this process.

Users create a `.tmuxinator.yml` file for each project, specifying the project's root directory, environment variables, pre-window/pane commands, and the layout of windows and their respective panes, including commands to run within each. When tmuxinator start <project_name> is executed, it reads this configuration and launches a new or attaches to an existing `tmux` session with the predefined setup. This greatly enhances productivity for developers and users who frequently work on multiple projects, each requiring a specific terminal environment. It integrates seamlessly with `tmux`, providing a streamlined workflow for reproducible development environments.

tmuxinator requires `tmux` to be installed and accessible in the system's PATH. Project configuration relies on YAML syntax, which can be sensitive to indentation and formatting; errors in the YAML file can prevent a session from starting correctly. Environmental variables and shell specifics (e.g., sourcing `~/.bashrc`) might need careful handling within the YAML configuration for commands to execute as expected. While tmuxinator handles session creation and management, users still need basic `tmux` knowledge to navigate within the session once it's launched.

tmuxinator projects are defined in YAML files. Global projects are typically stored in `~/.config/tmuxinator/` (or `~/.tmuxinator/` for older versions), while local, project-specific configurations can be named `.tmuxinator.yml` in the project's root directory. These files specify the project's root path, environment variables, pre-session commands, windows, panes, and commands to run within each.

Users often integrate tmuxinator into their shell dotfiles (e.g., `.bashrc`, `.zshrc`) to set up aliases or custom functions for quick project launching, further streamlining their workflow. This allows for commands like `p project_name` to launch a full development environment.

tmuxinator was created by Christopher White and is primarily developed in Ruby, distributed as a Ruby gem. Its development began to address the need for easily reproducible `tmux` session configurations for development projects, allowing users to define complex window and pane layouts with associated commands in a declarative manner. Since its inception, it has become a widely adopted tool in the developer community for enhancing productivity within terminal environments, providing a structured approach to managing diverse project workspaces.

tmux(1): Terminal multiplexer, the core tool `tmuxinator` manages and automates., byobu(1): Another text-based window manager that uses `tmux` or `screen` as its backend, offering a higher-level abstraction., screen(1): GNU Screen, an older terminal multiplexer with similar functionality to `tmux`., yaml(7): YAML Ain't Markup Language, the data serialization format used for `tmuxinator` project configurations.