DEV Community

Akash Jana
Akash Jana Subscriber

Posted on

How to Change Your Herdr Theme

#herdr #tutorial #terminal #ai

I was tired of so many colors for a pretty long time.

Every multiplexer, every editor, every theme pack Catppuccin, Dracula, Tokyo Night, Nord, Gruvbox all beautiful, all... loud. After a while I just wanted to pivot to something black and white. No rainbow status dots screaming at me. No neon selection bars. Just text, contrast, and quiet.

So I went looking for a black & white theme for Herdr and discovered Herdr doesn't have one.

That detour turned into zenbones-herdr: the whole Zenbones pack, 23 themes, ported to Herdr. Created some custom themes as well.

This post is two things:

  1. A practical guide to changing your Herdr theme.
  2. The visual guide I wish Herdr docs had. What theme variable targets what component, with annotated screenshots.

TL;DR 

herdr plugin install AkashJana18/zenbones-herdr
herdr plugin action invoke open --plugin zenbones
Enter fullscreen mode Exit fullscreen mode

Pick a theme, done. Want pure grayscale?
Start with zenwritten-dark, snowbones-dark, or akabones-dark.

Why Zenbones?

Zenbones is a Neovim colorscheme built on HSLuv, a perceptually uniform color space. The palette generation is principled, contrast-focused, and calm by design.

The family includes:

  • zenbones — the base, warm and contrast-focused
  • zenwritten — zero saturation, pure grayscale
  • neobones / forestbones / rosebones / tokyobones / seoulbones — takes on neovim.io, Everforest, Rose Pine, Tokyo Night, Seoul256
  • nordbones / duckbones / zenburned / kanagawabones — dark-only takes on Nord, Spaceduck, Zenburn, Kanagawa
  • snowbones / akabones — custom minimal builds (pure white / charcoal & bone)

That zenwritten line is what hooked me. Herdr's built-ins (catppuccin, catppuccin-latte, terminal, tokyo-night, tokyo-night-day, dracula, nord, gruvbox, gruvbox-light, one-dark, one-light, solarized, solarized-light) are all chromatic. There is no grayscale option. So I ported the whole pack instead of just one theme.

If you want black-and-white Herdr today:

  • zenwritten-dark — true grayscale + a single muted blue accent
  • akabones-dark — charcoal #101010 + bone, near-monochrome (my daily driver in the screenshots below)
  • snowbones-dark/light — pure white and shades of white, zero hue

What that looks like in practice, the model picker with no rainbow. Just white text, dimmed subtext, and one warm selection bar:

GitHub logo AkashJana18 / zenbones-herdr

Minimal paper theme for Herdr. Port of zenbones zenwritten for the Herdr TUI.

Zenbones for Herdr

23 color themes from the zenbones ecosystem for the Herdr terminal multiplexer. HSLuv-based palettes, light and dark variants, works in any terminal.

refined-herdr-akabone.mov

Themes











































































Theme Variants Description
zenbones light, dark The base theme — contrast-focused, warm accents
zenwritten light, dark Zero saturation, pure grayscale + zenbones accents
neobones light, dark Inspired by neovim.io — green-leaning
forestbones light, dark Inspired by Everforest — natural greens and golds
rosebones light, dark Inspired by Rose Pine — purple and rose tones
tokyobones light, dark Inspired by Tokyo Night — deep blue-violet
seoulbones light, dark Inspired by Seoul256 — balanced mid-tones
nordbones dark only Inspired by Nord — arctic blues
duckbones dark only Inspired by Spaceduck — high contrast space
zenburned dark only Inspired by Zenburn — muted warm gray
kanagawabones dark only Inspired by Kanagawa — Japanese ink wash
vimbones light only Inspired by vim.org — warm yellow-green
snowbones light,
…



View on GitHub


How to Change Your Herdr Theme (3 Ways)

1. The Settings UI (no plugin needed for in-built themes)

This is the path annotated in Image 2.

  1. Press prefix+s (default prefix is ctrl+b, so ctrl+b then Shift+S) to open Settings.
  2. Go to the theme tab (↑↓ select, tab switch section).
  3. ↑↓ through the built-in list (catppuccin, terminal, tokyo-night, dracula, nord, gruvbox, ...).
  4. Press Enter (↵ apply), then esc to close.

Herdr applies it immediately. Under the hood this sets in config:

[theme]
name = "catppuccin"
Enter fullscreen mode Exit fullscreen mode

2. Edit config.toml manually by hand

Herdr reads ~/.config/herdr/config.toml (or $HERDR_CONFIG_PATH). Print the commented defaults anytime with:

herdr --default-config
herdr --default-config > ~/.config/herdr/config.toml
Enter fullscreen mode Exit fullscreen mode

Pick a base theme:

[theme]
name = "nord"
Enter fullscreen mode Exit fullscreen mode

Override individual tokens on top of it:

[theme.custom]
panel_bg = "#101010"
sidebar_bg = "#1A1A1A"
active_row_bg = "#101010"
selection_bg = "#2E2E2E"
accent = "#BDBDBD"
text = "#EEEEEE"
subtext0 = "#BDBDBD"
Enter fullscreen mode Exit fullscreen mode

Then reload without restarting panes:

herdr server reload-config
# or: prefix+shift+r
Enter fullscreen mode Exit fullscreen mode

Color values accept hex (#101010), named colors (cyan), rgb(r,g,b), or reset aliases (reset / default / transparent useful to let your terminal background show through).

3. The zenbones-herdr picker (23 themes in one keystroke)

Install once:

herdr plugin install AkashJana18/zenbones-herdr
# local checkout:
herdr plugin link /path/to/zenbones-herdr
Enter fullscreen mode Exit fullscreen mode

Open the picker:

herdr plugin action invoke open --plugin zenbones
Enter fullscreen mode Exit fullscreen mode

Apply directly without UI:

./bin/apply.sh zenwritten-dark
./bin/apply.sh akabones-dark
./bin/apply.sh tokyobones-dark
./bin/apply.sh default   # remove [theme.custom], back to Herdr default
Enter fullscreen mode Exit fullscreen mode

What the plugin actually does is simple and reversible: it writes a [theme.custom] block into your config.toml, backs up the old file to config.toml.bak-YYYYMMDD, and runs herdr server reload-config. Picking default strips that block out again. Each file in themes/ is just the 19 Herdr tokens pre-computed, e.g. themes/akabones-dark:

panel_bg = "#101010"
sidebar_bg = "#1A1A1A"
active_row_bg = "#101010"
selection_bg = "#2E2E2E"
text = "#EEEEEE"
subtext0 = "#BDBDBD"
accent = "#BDBDBD"
red = "#683d3b"
green = "#98BD99"
yellow = "#FFDF9B"
blue = "#97BDDE"
mauve = "#A5A6C5"
teal = "#C6D5CF"
peach = "#EB99B1"
surface0 = "#242424"
surface1 = "#2E2E2E"
surface_dim = "#0C0C0C"
overlay0 = "#696969"
overlay1 = "#DDDDDD"
Enter fullscreen mode Exit fullscreen mode

What Variable Targets What? (The Missing Diagram)

Herdr's config reference documents every theme.custom.* key, but there is no image showing where each token lands in the UI. Here is that diagram, annotated on the real Settings screen:

Sidebar image

Panel image

Reading the annotations:

panel_bg — the big surface (green in the screenshot)

The background of the settings modal / panel itself. In the screenshot the whole green-bordered box is panel_bg. Set this to #101010 and the entire dialog goes near-black. panel_bg = "reset" lets your terminal background bleed through instead.

accent — anything that says "this is active" (pink/purple in the screenshot)

This is the hardest-working token. It paints:

  • the active settings tab (theme pill, top-left)
  • the currently-selected row (catppuccin ✓ highlighted row)
  • the ↵ apply button
  • the PREFIX badge in the bottom mode bar
  • underlined hints like ctrl+a, w, ? in that bar
  • the section title in Image 1 (OpenCode Zen)

If you only change one token to de-saturate Herdr, change this one. All the B&W ports set accent to a gray (#BDBDBD) or a single muted tone instead of cyan/pink.

Note: there is also a separate ui.accent key (default "cyan") for highlights/borders/navigation UI. theme.custom.accent overrides the theme token on top of the base theme — that is what the screenshot arrows are pointing at.

overlay1 — secondary chrome (blue in the screenshot)

The quieter interactive chrome:

  • the + new-tab button in the tab bar
  • the inactive tabs (indicators, sound, toasts, integrations)
  • the ↑↓ select tab section footer hint

overlay0 is its dimmer sibling (borders, separators, scrollbar tracks). In a monochrome theme these two carry all the hierarchy, so getting their contrast right matters more than any hue.

overlay1

The sidebar trio: sidebar_bg, active_row_bg, selection_bg

Visible at the top of the screenshot (and in the left column behind the modal):

panel_bg = "#101010"
sidebar_bg = "#1A1A1A"
active_row_bg = "#101010"
selection_bg = "#2E2E2E"
Enter fullscreen mode Exit fullscreen mode
  • sidebar_bg — the desktop sidebar background only (the spaces / agents column on the left). Omit it and the sidebar keeps the host terminal background.
  • active_row_bg — the active Space and focused Agent row, without touching separators or scrollbars.
  • selection_bg — the Navigate-mode cursor row in the sidebar.

Splitting these three is what lets akabones-dark keep the sidebar (#1A1A1A) one step lighter than the panel (#101010) while the cursor row (#2E2E2E) still reads clearly.

text / subtext0 — the two text levels

  • text — primary: model names (Muse Spark 1.2 Free), theme names (catppuccin, tokyo-night), Select model.
  • subtext0 — everything dimmed: Search, the OpenCode Zen suffix, the Free column, Connect provider ctrl+a Favorite ctrl+f.

In Image 1 you can see this split clearly: bright white for the selectable name, gray for metadata. A good B&W theme lives or dies on this ratio.

surface0 / surface1 / surface_dim

Secondary surfaces layered on panel_bg — popups, hover states, nested panels. Kept close to panel_bg in the bones ports (#242424 / #2E2E2E on a #101010 base) so depth comes from lightness steps, not hue.

surface dim

red / green / yellow / blue / mauve / teal / peach

Semantic colors: agent state dots, git ahead/behind counts, and per-agent accents. In the colorful ports these follow the inspiration theme (Nord blues, Tokyo Night violet). In zenwritten / akabones / snowbones they are deliberately muted to near-grays so a red dot never shouts. They are pretty obvious to understand hence not marked on the image annotations.

My recommendation if you are color-fatigued: live in zenwritten-dark or akabones-dark for a week. Keep one muted accent so selection is still findable. You will notice how often color was doing hierarchy work that lightness steps do better.

Get the Pack

  • Repo: AkashJana18/zenbones-herdr
  • Install: herdr plugin install AkashJana18/zenbones-herdr
  • fzf Picker: herdr plugin action invoke open --plugin zenbones
  • 23 themes, light + dark variants, works in any terminal, Herdr >=0.8.0, Linux + macOS
  • Revert anytime: pick default or run ./bin/apply.sh default

Currently doing it through a bash script, but I’m wondering if there’s a better way to make Herdr’s default theme system support external themes

If you’ve got ideas, lmk here: https://github.com/herdrdev/herdr/discussions/4366

Palettes ported from zenbones.nvim (HSLuv-based). Herdr port maintained by Akash Jana PRs and fixes welcome.

If this visual mapping saved you a config cycle, a star on the repo is the cheapest thanks.

Top comments (1)

Collapse
 
yashksaini profile image
Yash Kumar Saini •

This is a nice extension tool. I don't use herdr but seeing this makes me wanna use it now and with your tool. The color confiugration and the tool ease of use is really great.