tmux-palette: a Raycast-style command palette for tmux

The problem: tmux has no launcher

tmux gives you key bindings and a prefix, and that is the whole interface. Remembering that prefix + % splits vertically while prefix + " splits horizontally is the kind of knowledge that decays if you do not use it daily. tmux-palette targets that gap. It opens a searchable list over your current pane, you type a few letters, you pick an entry, and the action runs. The README frames the intended use plainly: "Type a few letters, pick a command, hit enter: split a pane, jump to a window, detach a session, open a popup tool, or switch to a custom palette."

The audience is narrower than "tmux users". It is people who already have tmux 3.4 or newer, are willing to install Bun, and want their launcher to be a file they can edit rather than a plugin they have to fork. The repository states the codebase is roughly 2k LOC, which is the number that matters if you intend to read the thing before trusting it with your session management.

How tmux-palette works: Bun, popups, and JSON palettes

The architecture is a thin shell wrapper over a TypeScript program. The package.json declares bin.tmux-palette as ./bin/tmux-palette.sh, so the tmux binding invokes that script, which hands off to the Bun entry point at src/cli.ts (the start script is "bun src/cli.ts"). The repository ships bin/, src/, tests/, and a tmux-palette.tmux file, which is the piece TPM sources.

The palette renders inside a tmux popup. That is why tmux 3.4 is recommended: the README ties the requirement to display-popup -E support. On narrower terminals the tool auto-fullscreens, a behaviour the README attributes to mobile clients like Moshi and Blink on iOS.

Configuration lives outside the checkout. The README states that user config lives in ~/.config/tmux-palette/*.json so local changes survive repo updates, and repeats the claim in the highlights as "No fork required". The pieces named in the README are palettes (custom command lists), hidden.json for hiding built-in items, sizing.json for popup dimensions and borders, and a theme setting. Palettes can be static JSON or scriptable sources: the README describes pointing a palette at a shell command that prints JSON or one item per line, with examples in examples/. A popup entry such as { "popup": "htop" } opens a tool in a tmux popup instead of running inline.

Installing tmux-palette and binding it to a key

Two supported install paths exist: TPM or a manual clone. Both need Bun, and neither works without a tmux binding, because the palette does not open on its own. The manual route clones into a path of your choosing and installs dependencies.

git clone https://github.com/eduwass/tmux-palette ~/Sites/tmux-palette
cd ~/Sites/tmux-palette
bun install

After that, add a binding to .tmux.conf. The README's example uses Ctrl+Space with -n, which skips the prefix and is described as giving the most Raycast-like feel.

bind -n C-Space run-shell "~/Sites/tmux-palette/bin/tmux-palette.sh"

Reload the config with tmux source-file ~/.tmux.conf and press the binding. You should see the main palette, which the README describes as covering panes, windows, sessions, and built-in tmux actions.

If you already use TPM, the plugin route sets the binding for you. The README gives these options, with @palette-key defaulting to C-Space and the other two unbound by default.

set -g @plugin 'eduwass/tmux-palette'
set -g @palette-key 'C-Space'
set -g @palette-find-pane-key 'M-f'
set -g @palette-move-pane-key 'M-m'

Then press prefix + I. The README states TPM clones the repo, runs bun install on first load, and binds the keys. Setting @palette-key to 'off' skips the main binding if you want to wire it yourself.

For a first real customization, the examples directory is the starting point. The README says to copy drop-in palettes from examples/ into ~/.config/tmux-palette/palettes/. The shipped example files are docker-containers.json, find-files.json, git-branches.json, github-prs.json, and npm-scripts.json. Copying one of those and binding it to its own key is the shortest path to a palette that does something your default tmux cannot.

The beta status is the real constraint

The README is unusually direct about this: "The tool is in beta. It's stable enough to use day-to-day, but the surface area is still settling." The author states the next few weeks are meant for running it personally and shaking out bugs rather than growing the feature set, and that new features will likely be closed unless discussed in an issue first. Contributions that improve the existing base (refactors, performance, polish, docs) or fix bugs are what the project wants.

Take that at face value. If your workflow depends on a plugin with a frozen configuration schema, tmux-palette is the wrong tool right now. The JSON keys you write today are not guaranteed to survive the beta. The compensating factor is the same thing that makes the beta tolerable: roughly 2k LOC and no runtime dependencies, so a breaking change is something you can read and patch rather than something you have to wait on.

The second constraint is Bun. There is no Node fallback documented, and the package.json declares zero runtime dependencies while listing Bun types as a dev dependency. Bun is a hard prerequisite, not an optimization.

The third is the tmux version. The README recommends 3.4+ specifically for display-popup -E. Older tmux may install fine and then fail at the moment you press the key, which is a worse failure mode than a clear install error. The guided-onboarding prompt in the README tells the agent to warn rather than stop when tmux is below 3.4, which suggests the author expects it to partly work.

One more gap worth naming: the README does not document rollback or an uninstall procedure. Removing the binding from .tmux.conf and deleting the clone is the obvious path, but the project does not state it, and it does not say what happens to ~/.config/tmux-palette/ when you stop using the tool.

tmux-palette compared with fzf-based tmux scripts

The closest thing most tmux users already have is a hand-rolled fzf binding: a shell function that pipes a list into fzf and acts on the selection. That approach shares the philosophy of tmux-palette (small, scriptable, no framework) but differs in three concrete ways.

First, state. An fzf script rebuilds its list every time it runs. tmux-palette has a persistent config directory at ~/.config/tmux-palette/ with named palettes, a hidden.json for suppressing built-in entries, sizing.json for popup geometry, and themes. You edit files, not functions.

Second, the built-in surface. A fzf binding gives you whatever you wrote. tmux-palette ships a main palette covering panes, windows, sessions, and built-in tmux actions, plus a theme picker with live preview and 13 built-in themes (the README lists Shades of Purple, Dracula, Tokyo Night, Catppuccin, Gruvbox, Nord, Solarized among them, plus a transparent Terminal theme that follows your terminal colors).

Third, the runtime. An fzf script depends on fzf and whatever shell utilities you pipe into it. tmux-palette depends on Bun and nothing else at runtime. If you already have fzf installed and your bindings work, the migration buys you configuration ergonomics and themes, not capability. If your fzf scripts have grown into a directory of half-remembered shell functions, the JSON layout is the actual improvement.

Maintenance, licence, and upgrade cost

The last push to the default branch was on 2026-06-24. The repository is not archived. There are no releases retrieved, so versioning is tracked through package.json, which currently reads 0.3.0, and through CHANGELOG.md in the repository root.

Upgrade cost depends on how you installed it. Under TPM, the plugin is a git clone, so upgrading is a pull plus whatever the changelog says. The README's claim that local changes survive repo updates rests on the split between the checkout and ~/.config/tmux-palette/, so the upgrade risk is concentrated in the JSON schema, not in your files being overwritten. Read CHANGELOG.md before pulling during the beta.

On licensing: the repository metadata does not state a licence, and no LICENSE file appears in the top-level entries listed for the repository (which include .github/, CHANGELOG.md, README.md, bin/, examples/, src/, tests/, and configuration files, but no licence file). That is a real gap. Without a stated licence, the default position is that no rights are granted, which matters if you intend to vendor the code, ship it inside a company image, or fork it into a product. If you need clarity, the honest step is to open an issue asking the author to add a licence file rather than assume a permissive default. This is not legal advice; it is an observation about what the repository does and does not contain.

Editorial conclusion

Adopt tmux-palette if you already run tmux 3.4+ and Bun and want a keyboard-driven launcher for panes, windows, sessions, and shell commands without editing the repository. Skip it if you are not willing to install Bun, if you need a stable plugin surface, or if your tmux predates display-popup -E. Before committing, verify three things: that bun --version resolves, that tmux -V reports 3.4 or higher, and that ~/.config/tmux-palette/ is the directory your local JSON edits land in, since that path is what keeps your customizations alive across repo updates.

Frequently asked questions

Official sources

1. eduwass/tmux-palette on GitHub
2. Issues
3. README