Tokyo Night Tmux: a themed status bar with a row of widgets

A status bar theme, not a terminal colour scheme

Tokyo Night Tmux is described as a clean, dark Tmux theme inspired by the lights of Tokyo at night, and it was adapted from the Tokyo Night VS Code theme, with the README calling it the perfect companion for tokyonight-vim.

That last point sets the scope. This is a tmux plugin, and what it repaints is the status bar, not the terminal emulator. If you want the rest of your terminal in the same colours, the README points at a separate theme, the Tokyo Night Kitty theme, and shows a preview with Kitty and the SFMono Nerd Font Ligaturized. So the visual result is a combination of two things installed separately, and the tmux plugin is the piece that owns the bar.

What the plugin adds beyond colour is the widget row. The features table is the clearest statement of scope, and it is longer than a colour palette usually is: four colour themes with a transparent background option, a local git status showing branch, changes and a push and pull sync indicator, a GitHub or GitLab widget listing open pull requests, pending reviews and assigned issues, a network speed widget with interface detection, a now playing widget that reads track information through playerctl on Linux or nowplaying-cli on macOS, a battery widget with level and charge state and contextual icons, a date and time widget with configurable format, a path widget showing the current pane path as relative or absolute, a hostname widget, eight styles for window and pane identifiers including digital, roman and squares, an SSH indicator that changes the icon automatically for SSH sessions, a visual highlight for when the tmux prefix is active, a separate style for zoomed panes, and reordering of the right status bar.

So the honest summary is that this is a status bar with a built in dashboard, where the colours are the part most people notice and the widgets are the part that takes the setup work.

One plugin line and the prefix I to install it

The installation is the shortest of any project in this category. There is no cloning and no sourcing, because the plugin is loaded by tmux plugin manager, tpm, and the whole step is a single line added to your tmux.conf:

set -g @plugin "janoamaral/tokyo-night-tmux"

The README instructs you to add that to your ~/.tmux.conf and press prefix followed by I to install.

After changing the configuration, the reload command is:

tmux source ~/.tmux.conf

That is worth noting because a tmux configuration is not re-read when you save the file, and the plugin style and options are set in that file, so a session that was started before the change will keep the old status bar until it is sourced or restarted.

The options are all set as tmux user options with the @tokyo-night-tmux_ prefix, which is the conventional way to pass settings to a tmux plugin, and the README groups them into three steps: install the plugin, pick a theme, and enable widgets. The theme and widget steps are both marked optional in the headings, which is accurate, since the plugin renders the bar with its defaults if you configure nothing beyond the plugin line itself.

Dependencies: Nerd Fonts v3, Bash 4.2, and a package list per platform

The quick start states the two hard requirements plainly. Nerd Fonts version 3 or later and Bash 4.2 or later are required.

The Nerd Fonts requirement is the one that catches people. Every icon in the status bar is a Nerd Font glyph, and the version 3 requirement is about the glyph set rather than the font itself, so an older patched font will render the wrong icons or none at all. The README links to the Nerd Fonts site for the download.

The Bash requirement exists because the plugin's scripts are Bash, and a distribution still shipping Bash 3, which is what macOS shipped for years, cannot run them.

Beyond that, each platform needs a set of command line tools, and the README gives one list per distribution. On macOS:

brew install --cask font-monaspace-nerd-font font-noto-sans-symbols-2
brew install bash bc coreutils gawk gh glab gsed jq nowplaying-cli

On Arch Linux:

pacman -Sy bash bc coreutils git jq playerctl

On Ubuntu or Debian:

apt-get install bash bc coreutils gawk git jq playerctl

And on Alpine Linux:

apk add bash bc coreutils gawk git jq playerctl sed

The list is telling. bc is there for the arithmetic the widgets need, gawk and coreutils for the text processing, jq for parsing the JSON that the GitHub and GitLab widgets read, gh and glab for the GitHub and GitLab command line tools, playerctl and nowplaying-cli for the now playing widget, and the two font casks on macOS for the icons.

So the widget you want determines part of what you install, and the full dependency list is in the installation document the README links to, user_docs/installation.md.

Four themes and a transparent background, set by tmux options

The theme step is two lines of tmux options:

set -g @tokyo-night-tmux_theme night   # night (default) | storm | moon | day
set -g @tokyo-night-tmux_transparent 1 # transparent background

Four themes are available, night, storm, moon and day, with night as the default, and the transparent option drops the background so your terminal wallpaper shows through the bar. The features table lists the same four themes and notes the transparent background alongside them.

The design work comes from elsewhere. The theme was adapted from the Tokyo Night VS Code theme, so the palette is the VS Code one rather than something original, and the README positions this plugin as the companion to tokyonight-vim for people who want the same colours across a terminal, an editor and a multiplexer.

The documentation directory is split by topic, with user_docs/themes.md covering colour themes and transparency, user_docs/widgets.md covering the status bar widgets, user_docs/customization.md covering number styles and window icons, and user_docs/installation.md covering the dependencies. The colours and the widgets are therefore documented separately, which matches the way the configuration is set up.

The widget row and what each widget needs from you

Widgets are enabled individually, and the set of options is explicit:

set -g @tokyo-night-tmux_show_git 1             # local git status
set -g @tokyo-night-tmux_show_wbg 1             # GitHub / GitLab stats
set -g @tokyo-night-tmux_show_netspeed 1        # network speed
set -g @tokyo-night-tmux_show_battery_widget 1  # battery level
set -g @tokyo-night-tmux_show_music 1           # now playing
set -g @tokyo-night-tmux_show_path 1            # current path
set -g @tokyo-night-tmux_show_hostname 1        # machine hostname

What each one does is in the features table. The git widget shows the branch, the changes and a push and pull sync indicator. The GitHub and GitLab widget shows open pull requests, pending reviews and assigned issues. The netspeed widget shows upload and download speed with interface detection. The music widget reads the current track through playerctl on Linux or nowplaying-cli on macOS, which is why those two tools appear in the dependency lists. The battery widget shows the level and the charge state with contextual icons, the path widget shows the current pane path as relative or absolute, the hostname widget puts the machine name in the bar, and the date and time widget has a configurable format with YMD, MDY and DMY orders and 12 or 24 hour clocks.

The order of the right side of the bar is configurable too, through a single option:

# Optional: reorder the right status bar (default order shown)
# set -g @tokyo-night-tmux_show_right_widgets "path, git, datetime"

So the bar is a composition you assemble, and every widget is a separate switch you can leave off.

A shell project with a test directory and pre-commit hooks

The primary language of the repository is Shell, which is consistent with a plugin that is a set of scripts and a tmux configuration file. The root holds a tokyo-night.tmux file, a lib directory, a src directory, a test directory, snaps for the screenshots, and user_docs for the documentation the README links to. There is also an openspec directory, an AGENTS.md, a SECURITY.md, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md and a .pre-commit-config.yaml, plus a .editorconfig that contributors are asked to follow.

The pre-commit hooks are the notable part of that. The README says they are provided for code consistency and will run against all pull requests, and there is a CI badge for a workflow named pre-commit.yml, so the formatting and lint rules are enforced on the server rather than left to reviewers.

The release history is regular. The tags are v1.9.0 on 2026-08-14, v1.8.1 on 2026-04-27 and v1.7.0 on 2026-01-06, so minor versions arrive every few months, and the last push to the repository was on 2026-08-15, the day after the newest tag.

The licence is the one point where the metadata and the repository disagree in a way worth checking. The platform classifies the licence as a custom one that it cannot categorise, while the repository has a LICENSE.md file, and the README carries a Buy Me A Coffee link for the author. For a colours and shell script project that is a low risk, but for a team standardising on it, the terms in LICENSE.md are the ones to read.

Editorial conclusion

Adopt Tokyo Night Tmux if you spend your day in tmux and want a status bar that shows the state of your repository, your network and your machine without assembling it from separate plugins. Do not adopt it as a way to get a full terminal theme, since the README describes it as a companion for tokyonight-vim and it does not change the colour scheme of the terminal itself. Verify first that your terminal renders Nerd Fonts version 3 or later, since every icon in the status bar depends on it, that your Bash is 4.2 or newer because the plugin scripts are Bash, and which widgets you actually want enabled, since several of them shell out to external tools such as playerctl or nowplaying-cli that you have to install separately.

Frequently asked questions

Official sources

1. Issues
2. janoamaral/tokyo-night-tmux on GitHub
3. Project website
4. README
5. Releases