Configuration

One optional file of plain key/value lines — and a way to change most of it without restarting anything.

Where the config lives

$XDG_CONFIG_HOME/termdock/termdock.conf, falling back to ~/.config/termdock/termdock.conf, or wherever $TERMDOCK_CONFIG points. It does not exist until you create it, and a missing file simply means defaults.

Plain key value lines, # for comments:

# termdock.conf
prefix C-a               # prefix key, any Ctrl+letter (default C-b)
mouse on                 # mouse support (default on)
history-limit 10000      # scrollback lines kept per pane
shell /bin/zsh           # shell for new panes (default $SHELL)
popup-command lazygit    # what Ctrl-B P runs (default: the shell)
focus-events on          # forward synthetic pane focus-in/out (default off)
repeat-time 1000         # ms a bare arrow keeps moving focus (0 disables)
bind M jump-picker       # rebind one key; repeatable, one per line
theme dracula            # bundled color preset
status-bg black
status-fg silver
pane-active-bg teal
pane-bg default          # background behind unstyled pane content
pane-fg default
status-segments git,battery,cpu,mem
status-icons unicode     # icons before them: off, unicode or nerd

A typo never stops a session starting. A line termdock cannot parse is ignored and the default kept. That is the right trade, and its cost is that a mistake is invisible — which is what termdock doctor below is for.

Icons in the status bar

status-icons puts a glyph in front of each optional segment.

Only nerd needs a font installed. termdock cannot ship an icon font, and no terminal program can: it writes characters to a pty, and your terminal emulator draws them with whatever font it is set to. Which glyphs exist is its decision, never termdock's. If you would rather not install anything, use unicode — or leave it off.

It has three values rather than on/off, because no program can ask a terminal whether its font actually contains a glyph — so the choice is yours to make by looking.

Value	Shows
`off`	The default. Words alone: `cpu 8% \| mem 41%`. Never wrong on any font.
`unicode`	`░ cpu 8% \| ▓ mem 71%` — the shade fills up as the number climbs, so the glyph is a second look at the figure rather than decoration. Nothing to install: these are Block Elements, which ordinary monospace fonts carry, rather than the Private Use Area. They are text-presentation too, so they stay one column wide and cannot push the right-aligned bar out of alignment.
`nerd`	Real microchip and memory icons, and the only value that requires installing a Nerd Font and selecting it in your terminal. These glyphs live in the Private Use Area — codepoints Unicode leaves deliberately unassigned — so only a font patched to add them has anything to draw. Without one the bar reads `◆ mem 10%`: a replacement box where the microchip should be.

Open the settings screen with Ctrl-B C, put the cursor on status-icons and step it with ←→. The bar redraws as you go, so you can see which set your font can draw instead of guessing. If a set shows boxes, it is the wrong one for your font.

Installing a Nerd Font

Install it where the terminal is, not where termdock is. The font is used by the terminal emulator you are looking at. Over SSH that is your laptop, not the server; on Windows with WSL that is Windows, not the WSL distribution. Installing fonts on the far side does nothing at all, and is the usual reason this appears not to work.

Any font from nerdfonts.com will do — JetBrains Mono is used here. On Linux:

mkdir -p ~/.local/share/fonts
curl -fLo /tmp/JetBrainsMono.zip   https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip
unzip -o /tmp/JetBrainsMono.zip -d ~/.local/share/fonts/JetBrainsMono
fc-cache -f

On macOS:

brew install --cask font-jetbrains-mono-nerd-font

On Windows, including when you run termdock in WSL — do this on the Windows side, not inside the distribution:

Download JetBrainsMono.zip from the nerd-fonts releases.
Extract it, select the .ttf files, right-click → Install.
Windows Terminal → Settings → your profile → Appearance → Font face.

Then pick the font in your terminal's settings. It is listed as JetBrainsMono Nerd Font, or as JetBrainsMono NF in terminals that show the short family name — Windows Terminal is one. Restart the terminal, then set status-icons nerd. None of this is needed for unicode, which draws characters fonts already have.

Which settings apply when

prefix, shell, history-limit, popup-command, focus-events, repeat-time and bind are read by the server, so they take effect when a session is created.

mouse, theme and the colours are read by the client, so detaching and reattaching is enough.

Themes

Eleven, built in — no plugin, no plugin manager:

termdock themes

catppuccin  dracula  everforest  gruvbox  monokai  nord
one-dark    rose-pine  solarized  tokyo-night  ubuntu

A theme sets the status bar, the active pane's accent, and the pane backgrounds — so a themed session looks themed all the way out to the margins, rather than being a coloured status bar floating on whatever your terminal profile uses. termdock also asks the terminal emulator itself to adopt the colours, so even the few pixels of padding around the character grid match, and puts them back when you detach.

A theme is only a baseline: an explicit pane-active-bg line still overrides just that one colour, whichever order the two lines come in. pane-bg default opts the pane backgrounds back out while keeping the rest.

Changing settings while it runs

Ctrl-B C opens every setting with its current value and what it does. ← → steps through the values a setting can take — all eleven palettes on theme, applying each as you land on it, so you choose by looking rather than by reading names. Enter types a value for anything free-form.

S writes the current value to your config file, rewriting just that line. Nothing is written unless you ask: silently rewriting a file full of your own comments and ordering is not a thing to do as a side effect of trying something out.

The same vocabulary works from the command prompt:

Ctrl-B :  set theme nord
Ctrl-B :  set -p theme nord     # and persist it

Checking your own setup

termdock doctor

Checks the things that fail silently:

[ warn ] theme                  "drakula" is not a built-in theme, so the line is being ignored
                                → check the spelling against `termdock themes`
[ warn ] shell integration      no `termdock shell-init` line found in your shell startup files
                                → add: eval "$(termdock shell-init)"

Every check reports what it found rather than a bare verdict, so the output is worth pasting into a bug report from a machine you cannot see, and every warning names the thing to do about it.

Crash recovery

termdock snapshots each session continuously: the layout, every pane's working directory and name, and the last 200 lines of each pane's screen. If the daemon dies or the machine reboots, starting a session with the same name brings it back — including the stack trace you were reading, rather than four blank prompts.

What comes back is text, not a live program: nothing can resurrect what was running. Quitting deliberately with Ctrl-B q deletes the snapshot, so a session you ended stays ended.

Debugging input

If a key does something unexpected, set TERMDOCK_INPUT_LOG=/path/to/file when starting the server and every key, mouse and resize event is appended there with the state it left behind:

02:47:54.598 key code=66 rune='\x00' mod=0    -> prefix=true mode=normal
02:47:54.598 key code=257 rune='\x00' mod=0   -> prefix=false mode=normal

What your terminal emulator actually sends for a chord, and whether a key reached the daemon at all, are otherwise invisible.