A catppuccin neovim + tmux starter guide

Let me begin by saying that what I am about to outline is not prescriptive. While you are free to copy the plugins and dotfiles that I use, there are a myriad ways of combining various plugins that suit your fancy to achieve the same overall effect. Instead, I wish to highlight how tightly tmux, a terminal multiplexer, and neovim, a text editor, compliment each other. By focusing on the core functionality that a great editing experience should have (such as the ability to run commands, see the current git status, and even keep track of time) the system can be built with specific outcomes as the north star. With that, let’s begin!

What the end setup will look like

Tmux

Tmux is a terminal multiplexer. Essentially, this boils down to a fancy way to switch between and spawn new terminal processes. For us right now, none of the complex stuff matters; it is okay to use tmux for just a few things. Here we will focus on three main feature sets.

1. Tmux allows us to have multiple windows open at the same time. This allows us to have one window in which we are editing code with neovim, and another in which we are running the code we are writing to test it out or to push it to various places.
2. Tmux allows us to easily close our terminal at the end of the day, and come back to it again. This reduces friction by enabling us to start right where we left off.
3. Tmux displays information visually, and this is customizable. In tandem with neovim, we can split information between the bottom and top of the display, to avoid things getting too cluttered.

Setup

Installing tmux is pretty straightforward. Since I’m on debian, I installed through apt install tmux, however there are specific instructions for different distributions and operating systems (including macOS). After installation, invoking tmux is as simple as typing tmux on the command line.

At this point, you’ll see a bar appear on the bottom of the screen. You’ve just done a whole bunch of things. In one step you’ve created a session, a window, and a pane. For me, it was helpful at first to understand the hierarchy of those three items, relative to the base terminal. It looks like this

tmux > sessions > windows > panes

The s at the end of those words is important. A single session can have multiple windows, and a single window can have multiple panes. In this article, we are going to focus only on scenarios in which you have one session, multiple windows, and one pane within each of those windows. More advanced scenarios are cool, but they aren’t necessary to understand to get going with neovim.

As mentioned at the top of the article, we are looking for tmux to do three things. Let’s dive into them below.

Editing and running code at the same time

To see how we can have two windows open at the same time, we can create a new window and switch between the two of them. The prompt will be the same in both, and so you can envision (for now) running nvim on one, and any command that you like in the other.

The default “prefix” in tmux is ctrl + b. The “prefix” is the key combination that tells the system “I want to do something in tmux. The next keys I press after the prefix are what I want to do”. To create a new window, the combo is ctrl + b + c. You don’t have to hit all the keys at once, you can hit ctrl then b then c in quick succession and it should work.

In the bar at the bottom, you will now see two boxes, corresponding to the two windows you now have open. To switch between them, you can use ctrl + b + p for “previous window” and ctrl + b + n for “next window”. If these keys seem awkward to you, they can always be changed later. Try switching between the windows to get a hang for it.^[1]

Closing the session and coming back to it

Let’s close the terminal application (by hitting the X button for the window or the key combination you have set up to close programs). Then, relaunch your terminal application. Type tmux attach-session and you will see those two bars return at the bottom of your screen. If you want to see how the terminal history is saved, try something like echo "Testing", and repeat the process of closing and reopening again. You should see the “Testing” in the same place that you left it.

Displaying information in tmux

Right now, the tmux bar is pretty boring. It displays the windows and that’s about it. We can make it much more interesting however, and this is where we begin with the customization and configuration.

We’ll place the configuration file for tmux in ~/.config/tmux/tmux.conf. Similar to other programs, we’ll also use a plugin system so that we can quickly get up and running. The tmux plugin manager is called tpm. Follow the instructions in the README to load the required lines into the tmux.conf file.

For a plugin to start with to quickly show tmux’s visual capabilities, you can use mark-pitblado/catppuccin-tmux or catppuccin/tmux. Whichever you pick, make sure to install required dependencies, and a nerd font so that various icons render in the terminal correctly. The rest of this post will layout configuration for mark-pitbaldo/catppuccin-tmux, however, the exact configuration that you use isn’t super important, the main goal is to decide on what information should be displayed in tmux. In the configuration in this post, tmux will display:

1. The current tmux session
2. Open windows
3. The current filepath
4. The time

First, let’s load the plugin into the configuration file and state which things we would like to show^[2].

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin "mark-pitblado/catppuccin-tmux"

set -g @catppuccin-tmux_show_git 0
set -g @catppuccin-tmux_pane_id_style hide 
set -g @catppuccin-tmux_zoom_id_style hide 
set -g @catppuccin-tmux_show_path 1

run '~/.tmux/plugins/tpm/tpm'

If you are starting fresh with tmux, you will see that line at the bottom of your screen instead. To move the tmux bar to the top, we can add the following to the tmux.conf file.

set -g status-position top 
# ...
# rest of the other lines

I won’t got over any other tmux configuration options, as the ones listed above are only ones that are required for tmux to display our objectives, and keep the bottom bar free for neovim.

Neovim

Neovim is a text editor that operates in the terminal. It is a newer version of the vim editor. Neovim allows us to see some additional information while editing, and we will use it to compliment the information that tmux displays. Neovim will be responsible for showing:

1. The current vim mode
2. The current git branch
3. The git status
4. Diagnostic stastics
5. The hostname

Setup

This post is going to assume that you have neovim installed and use some plugin manager (doesn’t matter which). If you are brand new to setting up neovim, I would recommend kickstart.nvim. After having neovim installed and a plugin manager setup, the key plugin is lualine. To show the five aspects above, you can use a configuration that looks something like the following

{
'nvim-lualine/lualine.nvim',
    dependencies = { 'nvim-tree/nvim-web-devicons' },
    config = function()
      require('lualine').setup {
        sections = {
          lualine_a = { 'mode' },
          lualine_b = { 'branch', 'diff', 'diagnostics' },
          lualine_c = {},
          lualine_x = { '' },
          lualine_y = {},
          lualine_z = { 'hostname' },
        },
      }
end,
},

Of course, since this is a catppuccin theme, installing the catppuccin plugin for neovim is also helpful. This is how that looks when using lazy.nvim

{ "catppuccin/nvim", name = "catppuccin", priority = 1000 }

Switching between catppuccin flavours

I am a huge fan of mocha, but if you want to use any of the other flavours of catppuccin here is how to do so.

Changing catppuccin flavour in tmux

In the tmux.conf file, set the following value to either latte, frappe, or macchiato. If no value is set, it will default to mocha.

set -g @catppuccin-tmux_theme 'frappe'

Changing catppuccin flavour in neovim

In the catppuccin neovim plugin, change the flavour via the setup.

require("catppuccin").setup({
    flavour = "frappe",
})

You can also use :colorscheme catppuccin-frappe to change on the fly.

Additional resources and considerations

I just created the catppuccin-tmux repository over the last week. I’ve done my best to catch all of the colours and variable names from the tokyo-night configuration, but if I have missed anything, please feel free to create an issue. If it is causing you problems, the catppuccin/tmux is more mature. There is also a showcase where you can check out other people’s configurations (this one looks really cool)

With that said, you are all done! You should have a bar at the top of your editor that displays key information like the current file and time, and a bottom bar that displays the git branch, git revisions, and diagnostics. You can easily have one window open for editing, and quickly switch to another window to run or test the code that you writing.