tmuxer

This is a neovim plugin that streamlines workspace management and tmux session handling.

It allows you to quickly navigate between different project directories and automatically creates or switches to corresponding tmux sessions.

Features

Quickly browse and open Git projects from configured workspaces

Automatically create tmux sessions for selected projects

Start Neovim instances within tmux sessions

List and switch between existing tmux sessions

View sessions, windows, and panes in a tree structure

Switch directly to a specific session, window, or pane

Floating popup support for tmux sessions

Multi-select support for batch operations

Kill tmux sessions or individual windows without leaving Neovim

Smart project sorting by parent directories

Toggle visibility of archived projects

Health check for verifying plugin setup

Requirements

Neovim 0.10.4 or higher

Tmux 3.2 or higher (popup support required for floating sessions)

Telescope.nvim

Fd command (optional, falls back to find if not available)

Usage

To configure the plugin with lazy.nvim, use the following setup:

return {
  "dkooll/tmuxer.nvim",
  dependencies = { "nvim-telescope/telescope.nvim" },
  cmd = { "TmuxCreateSession", "TmuxSwitchSession", "TmuxToggleArchive" },
  config = function()
    require("tmuxer").setup({
      workspaces = {
        {
          name = "workspaces",
          path = "~/Documents/workspaces"
        }
      },
      max_depth = 2,
      theme = "ivy",
      previewer = false,
      border = true,
      parent_highlight = {
        fg = "#9E8069",
        bold = true,
      },
      layout_config = {
        width = 0.5,
        height = 0.31,
      },
      icons = {
        window = "■",
        window_hl = { fg = "#A9B665" },
        floating = "▣",
        floating_hl = { fg = "#D3869B" },
        pane = "▪",
        pane_hl = nil,
      },
    })
  end,
  keys = {
    { "<leader>tc", "<cmd>TmuxCreateSession<cr>", desc = "Tmuxer: Create Session" },
    { "<leader>ts", "<cmd>TmuxSwitchSession<cr>", desc = "Tmuxer: Switch Session" },
    { "<leader>ta", "<cmd>TmuxToggleArchive<cr>", desc = "Tmuxer: Toggle Archive" },
    { "<leader>th", "<cmd>checkhealth tmuxer<cr>", desc = "Tmuxer: Health Check" },
  },
}

Configuration

workspaces

List of workspaces with name and path (default: {})

nvim_alias

Command to run in new tmux sessions (default: "nvim")

max_depth

Directory depth for git project search (default: 2)

theme

Telescope theme: "dropdown", "cursor", "ivy" or nil (default: nil)

previewer

Show telescope previewer (default: true)

border

Show border around picker (default: true)

show_archive

Show archived projects by default (default: false)

layout_config

Telescope layout dimensions (default: { height = 15, width = 80 })

icons.window

Icon for windows in the session picker (default: "■")

icons.floating

Icon for floating sessions in the session picker (default: "▣")

icons.pane

Icon for panes in the session picker (default: "▪")

icons.window_hl

Highlight group for the window icon (default: nil, e.g. { fg = "#A9B665" })

icons.floating_hl

Highlight group for the floating icon (default: nil, e.g. { fg = "#D3869B" })

icons.pane_hl

Highlight group for the pane icon (default: nil, falls back to window_hl if not set)

Commands

:TmuxCreateSession

Opens a Telescope picker to browse Git projects within configured workspaces and create tmux sessions

:TmuxSwitchSession

Lists all non-attached tmux sessions in a tree view. Sessions can be expanded to show windows and panes. Floating sessions (detected via tmux @floating session option) are nested under their parent and open as popups. Popup dimensions are read from tmux options @popup-width, @popup-height, and @popup-border.

:TmuxToggleArchive

Toggles visibility of projects inside archive folders

Session Picker Keybindings

<Right>/<Left> - Expand/collapse current item

<C-e> - Toggle expand/collapse everything

<C-d> - Kill selected session(s) or window(s)

<Tab> - Multi-select

Notes

The plugin uses Telescope for an intuitive, searchable interface

Projects are discovered by finding .git directories (uses fd if available for better performance)

Excludes folders named archive by default (toggle with :TmuxToggleArchive)

Session names are generated from project names (non-alphanumeric characters replaced with underscores)

If you want to use different neovim configurations or versions, you can override the default command within the config

nvim_alias = "NVIM_APPNAME=nvim-dev nvim"

Contributors

We welcome contributions from the community! Whether it's reporting a bug, suggesting a new feature, or submitting a pull request, your input is highly valued.