Customize the terminal console

The ch console works out of the box. If you want a different theme, a narrower sidebar, or your own keys, change them from the settings screen or from a plain text file. This page covers both. For what the console shows and does by default, see Your sessions in the terminal.

The settings screen

Press Ctrl-B then ,, or open the menu and choose settings. The screen has four sections: theme, layout, indicators, and notifications.

• Tab and Shift-Tab change section.
• Up and Down pick a row.
• Left and Right change the sidebar width.
• Enter applies the row, and Esc closes the screen.
• You can also click the section names, the rows, and the apply and close buttons.

Each row shows where its current value comes from. Applying a row saves it to your own settings file (see Where settings live) and leaves the other lines and comments in that file alone.

Section	Row	Default
layout	Sidebar width	28 cells
layout	Collapse the sidebar	off
layout	Show the tab header	on
indicators	Tint a working tab	on
indicators	Badge a hidden tab that needs you	on
notifications	Ring the bell when a tab needs you	off

The theme section has its own rows. The next section covers them.

Themes

The console has three theme modes:

• system (the default) asks your terminal for its background colour and picks a light or dark theme to match. If the terminal doesn’t answer, the console uses the dark theme. Most tmux setups don’t pass the question through, so inside tmux the console usually stays dark.
• light always uses your light theme.
• dark always uses your dark theme.

The theme icon sits on the CodeHerder title row, left of the menu icon: ◐ for system, ☼ for light, and ☾ for dark. Click it, or press Ctrl-B then t (just t while the sidebar has focus), to cycle through the modes. The mode is saved.

Out of the box, light mode uses catppuccin-latte and dark mode uses codeherder. The built-in themes are:

codeherder, catppuccin, catppuccin-latte, tokyo-night, tokyo-night-day, dracula, nord, gruvbox, gruvbox-light, one-dark, one-light, solarized, solarized-light, and terminal. The terminal theme uses your terminal’s own colours, so it always matches whatever theme the terminal has.

In the settings screen, the theme section lists the mode, every built-in theme, and every custom theme you’ve added. The active theme has a check mark. Move the highlight and the console previews that theme live. Enter keeps it and Esc puts the old one back. The status line at the bottom names the setting that Enter will write: your light theme, your dark theme, or a pinned theme.

Session tabs follow the theme too, so a harness’s terminal output picks up the same colours as the rest of the console.

Pin a theme or change a mode’s theme

Three settings control themes:

Setting	What it does	Default
CH_TUI_THEME	The mode: system, light, or dark. A theme name here pins that theme instead.	system
CH_TUI_THEME_LIGHT	The theme light mode uses.	catppuccin-latte
CH_TUI_THEME_DARK	The theme dark mode uses.	codeherder

For example, to use Nord whenever the console is in dark mode:

ch --tui-set CH_TUI_THEME_DARK=nord

Write your own theme

A custom theme is a file named <name>.env in ~/.codeherder/themes/, or in a .codeherder/themes/ folder in a repo. The name uses lowercase letters, digits, and hyphens, and can’t be a built-in theme name or one of system, light, and dark. A theme in the repo replaces a theme with the same name in your home folder.

Each line sets one colour role to a #rrggbb value. Roles you leave out come from the theme named by BASE. BASE=dark and BASE=light stand for the default dark and light themes, and a file with no BASE starts from dark. This file builds on Nord:

# ~/.codeherder/themes/midnight.env
BASE=nord
SURFACE=#0b1020
TEXT=#e6e9f2
ACCENT=#ffb454

The main roles are SURFACE, TEXT, MUTED, FAINT, ACCENT, BORDER, SELECTED_TEXT, SELECTED_BACKGROUND, TAB_BACKGROUND, ATTENTION_TEXT, ATTENTION_BACKGROUND, and WORKING_CUE. You can also set ANSI_0 through ANSI_15 to recolour the 16 terminal colours inside a session tab.

A theme with an unknown role, a bad colour, or a bad name is skipped, and the console shows a warning. Select your theme the same way as a built-in one: from the settings screen, or with CH_TUI_THEME=midnight.

Where settings live and which one wins

Every console setting is a variable whose name starts with CH_TUI_. When more than one place sets the same one, the first match in this list wins:

1. A --tui-set KEY=VALUE flag on the command line. You can repeat it.
2. An environment variable.
3. The repo’s .codeherder.env file. See Project defaults for the CLI.
4. Your own file, ~/.codeherder/tui.env.
5. The built-in default.

The settings screen writes to ~/.codeherder/tui.env. If a higher source also sets the same key, the screen still saves your change and tells you which source wins, so nothing is dropped without a word.

tui.env holds console settings only. Credentials never go in it, and the console never reads them from there.

A bad setting never stops the console from opening. An unreadable file, an unknown CH_TUI_* name, or a value that doesn’t parse gives a warning that names the key and the file, and the console uses the next value down. The warning count shows in the footer, and the keybinds view lists each one.

Remap a key

Every console key is a setting named CH_TUI_KEY_*. Its value is a comma-separated list of bindings:

CH_TUI_KEY_NEW_SESSION=ctrl+n,alt+n

A binding is zero or more modifiers followed by one key.

• Modifiers: ctrl, alt (also opt, option, meta), shift, and super (also cmd, command). Join them to the key with + or -, as in ctrl+b or alt-x.
• Keys: one printable character, or a name: tab, enter, esc, space, backspace, up, down, left, right, home, end, pgup, pgdown, insert, delete, comma, plus, minus, and f1 through f12. shift+r and R mean the same key.

An empty value unbinds a key. The exception is the command key, which can’t be unbound and needs a Ctrl, Alt, or Cmd modifier, because a bare character would stop you typing it.

Two commands that are active in the same place can’t share a key. If you assign one, the later command goes back to its default and the console shows a warning. A few keys stay fixed and can’t be taken: moving through lists (arrows, j/k, Enter, Esc, Space, PgUp/PgDn, Home/End), the keys inside copy mode, editing the filter field, and the keys inside the settings screen and the menu.

Cmd bindings

Most macOS terminals keep Cmd for themselves. A cmd or super binding only reaches ch when your terminal reports it through the kitty keyboard protocol, and ch checks for that when it starts. It works in kitty, WezTerm, Ghostty, foot, Alacritty 0.13 or later, Rio, and iTerm2 3.5 or later with “Report keys using CSI u” turned on. It doesn’t work in macOS Terminal.app, GNOME Terminal and other VTE terminals, Windows Terminal, or most tmux setups.

You can mix forms in one list, for example CH_TUI_KEY_MENU=cmd-k,alt-m. If none of the listed forms works in your terminal, the command keeps its default key, and the keybinds view says so.

Every key and its default

The command key (CH_TUI_KEY_COMMAND) starts a command. Every key below works after it, except the ones marked as working in the sidebar or in a task or session details tab, which work on their own.

Setting	Default	What it does
CH_TUI_KEY_COMMAND	ctrl+b	Starts a command. It’s never typed into a session.
CH_TUI_KEY_COPY	c	Start copy mode
CH_TUI_KEY_QUIT	q	Detach and quit
CH_TUI_KEY_GROUPING	g	Open the grouping menu (also works in the sidebar)
CH_TUI_KEY_SEARCH	/	Filter the session list (also works in the sidebar)
CH_TUI_KEY_SESSIONS	s	Show sessions in the sidebar
CH_TUI_KEY_WORKSPACES	w	Show workspaces in the sidebar (also works in the sidebar)
CH_TUI_KEY_NEXT_TAB	tab,right	Next tab
CH_TUI_KEY_PREV_TAB	shift+tab,left	Previous tab
CH_TUI_KEY_TAB_1 to CH_TUI_KEY_TAB_4	1 to 4	Jump to that tab
CH_TUI_KEY_NEW_SESSION	n	Start a new session (also works in the sidebar)
CH_TUI_KEY_CLOSE_TAB	x	Close the current tab
CH_TUI_KEY_REDRAW	r	Redraw the screen and reload the list
CH_TUI_KEY_SEND_PREFIX	b	Send the command key itself to the session
CH_TUI_KEY_KEYBINDS	?	Open the keybinds view
CH_TUI_KEY_MENU	m	Open the menu
CH_TUI_KEY_SETTINGS	comma	Open the settings screen
CH_TUI_KEY_THEME	t	Cycle the theme mode (also works in the sidebar)
CH_TUI_KEY_RELOAD_CONFIG	R	Reload settings and theme files
CH_TUI_KEY_SIDEBAR_COLLAPSE	[	Collapse the sidebar
CH_TUI_KEY_SIDEBAR_EXPAND	]	Expand the sidebar
CH_TUI_KEY_SIDEBAR_NARROW	minus	Make the sidebar 2 cells narrower
CH_TUI_KEY_SIDEBAR_WIDEN	plus	Make the sidebar 2 cells wider
CH_TUI_KEY_DETAILS	i	Open the current tab’s details
CH_TUI_KEY_REPOS	p	Open the repos the current session uses
CH_TUI_KEY_TASK	T	Open the task of the current session
CH_TUI_KEY_NEXT_SESSION	N	Open the next session of the task
CH_TUI_KEY_STOP_SESSION	S	Stop the current session; press twice to confirm (also in a details tab)
CH_TUI_KEY_SIDEBAR_QUIT	q,ctrl+c	In the sidebar: detach and quit
CH_TUI_KEY_FOCUS_PANE	tab	In the sidebar: move focus to the open tab
CH_TUI_KEY_SIDEBAR_RELOAD	r	In the sidebar: reload the session list
CH_TUI_KEY_DOC_TASK	t	In a details tab: open the task
CH_TUI_KEY_DOC_NEXT	n	In a details tab: open the next session
CH_TUI_KEY_DOC_RELOAD	r	In a details tab: refresh
CH_TUI_KEY_DOC_CLOSE	x	In a details tab: close it
CH_TUI_KEY_DOC_OUTPUT	o	In a details tab: switch to the terminal
CH_TUI_KEY_DOC_BROWSER	b	In a task tab: copy the task link; Ctrl+click the button to open it

See your keys and reload changes

Press Ctrl-B then ? to open the keybinds view. It lists every command with the keys that are active now, and the file, environment variable, or flag each one came from. It also shows whether your terminal supports the keyboard protocol, and every warning from loading your settings.

After you edit tui.env, a repo .codeherder.env, or a theme file, press Ctrl-B then R, or choose reload config from the menu. The console re-reads the files and applies the new keys, theme, and sidebar width without restarting. Your sessions keep running either way.

Related guides

• Your sessions in the terminal — what the console shows and how to use it
• Project defaults for the CLI — share console settings with your team through a committed .codeherder.env