DEV Community

Akash Jana
Akash Jana Subscriber

Posted on Edited 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.

The reason for writing this blog is mentioned in this post:

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 (2)

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.

Collapse
 
akashjana profile image
Akash Jana •

Thanks, give it a try herdr is great from managing agents!