zellij-smart-tabs: a Zellij Plugin That Renames My Tabs For Me

type

Post

status

Published

date

Apr 8, 2026

slug

zellij-smart-tabs

summary

I Built a Zellij Plugin That Renames My Tabs For Me

Five tabs open, three of them named "Tab #3". Sound familiar? I got tired of manually renaming tabs every time I switched projects, so I built zellij-smart-tabs -- a plugin that keeps your tab names in sync with what's actually happening in them.

How it works

The plugin watches Zellij events -- directory changes, pane updates, running programs -- and renames tabs using a template you define. Out of the box you get the git repo name plus the running program with Nerd Font icons:

Templates are MiniJinja (Jinja2-like), so you can make it whatever you want:

The interesting bits

The concept is simple -- listen for events, format a string, rename the tab. A couple things turned out to be trickier than expected.

Manual rename detection is a race condition. My first approach tried to detect when you renamed a tab by comparing names. But rename_tab() is async -- the next event still shows the old name, so the plugin thinks you changed it. I tried delays, expected-name tracking, all fragile. The fix was to stop being clever: explicit set_focused_to_manual / set_focused_to_managed pipe commands. With a keybinding, press r to rename (auto-sets manual mode), Esc to cancel (restores auto). No race conditions.

Program detection flip-flops. Zellij has two sources: terminal_command (for command panes) and get_pane_running_command (polled). Using both interchangeably caused programs to flip between None and "nvim" every cycle. Fix: command panes use one, regular panes use the other, never mix.

Pane status

Any program can report its status to the plugin via pipe:

I use this with Claude Code hooks to show whether Claude is thinking, waiting, or done -- right in the tab name. Status is freeform; defaults map to Nerd Font icons but you can override everything.

Getting started

That's it. Tabs start renaming themselves.

For format templates, substitutions, keybindings, and Claude Code integration, see the README.

zellij-smart-tabs -- MIT licensed, Rust WASM