# Customize the terminal console

Source: https://codeherder.com/docs/terminal-console-settings/

Change the console's theme, sidebar, indicators, and keys from the settings screen or an env file, and see which setting wins when two disagree.

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](https://codeherder.com/docs/terminal-console/).

## 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](https://codeherder.com/docs/terminal-console-settings/#where-settings-live-and-which-one-wins)) 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](https://codeherder.com/docs/project-config/).
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](https://codeherder.com/docs/terminal-console/) — what the console shows and how to use it
- [Project defaults for the CLI](https://codeherder.com/docs/project-config/) — share console settings with your team through a committed `.codeherder.env`