Prompt themes in Termhint
Updated 19 November 2026All docs
Termhint can draw your shell prompt from a theme. This page lists the built-in themes, every
termhint theme command, the prompt you build in Settings and its parts, glyph levels, what bash
supports, and how to give the prompt back to your own setup. For an overview with previews, see
prompt themes.
How it works
- A theme is a JSON file. Termhint reads it and compiles it into the prompt your shell draws; the file is never executed.
- Themes need the shell integration:
termhint installfor zsh (the app adds it at launch), ortermhint install bash. See Install. - The prompt engine you had before (Starship, an Oh My Zsh theme, Powerlevel10k, …) stays
installed.
termhint theme offgives the prompt back to it. - Open tabs switch at once when you change the theme. A tab opened before your current version of Termhint needs to be reopened once.
- In zsh no process starts for each prompt: the prompt is built in the shell, the git branch is
read from
.git/HEAD, the git status is worked out by the app and added a moment after the prompt, and a language's version is asked in the background, once per folder.
Built-in themes
| Theme | Lines | What it shows | After |
|---|---|---|---|
robbyrussell |
1 | An arrow (red after a failed command), the folder, the git branch and a mark for uncommitted changes | robbyrussell, the default theme of Oh My Zsh |
agnoster |
1 | Colored blocks joined by arrows: marks for a failed command, root and background jobs; user@host; the Python environment; the folder; the git branch on green, or on yellow with marks when there are changes | The agnoster theme of Oh My Zsh |
pure |
2 | Folder, git branch with a star for uncommitted changes and arrows for commits to pull or push, how long a slow command took; then the prompt symbol (red after a failed command) | Pure by Sindre Sorhus |
lean |
2 | Folder (its last part bold) and git status with counts; at the right how long a slow command took, background jobs, the Python environment and user@host over SSH; then the prompt symbol | The lean style of Powerlevel10k |
starship |
2 | Folder (from the repository's folder inside one), git branch, git status symbols in brackets, the project's language version and how long a slow command took; then the prompt symbol. Over SSH the user and host come first | The default prompt of Starship |
agnoster looks best with a font that has the powerline arrows (glyph level nerd). Besides
these, the theme custom is the prompt you build in Settings, and your own theme files are listed
by termhint theme list too.
Choose a theme
In the app: Settings → Terminal → Prompt (⌘2 opens Terminal). The tiles are
drawn in your colors and font: Yours (the prompt you build), the five built-in themes, and
Shell's Own, which leaves the prompt to your ~/.zshrc.
From the command line:
termhint theme list # built-in themes and your own (* = in use)
termhint theme preview # every theme drawn with made-up values
termhint theme preview pure --glyphs nerd # one theme, with Nerd Font icons
termhint theme set pure # open tabs switch at once
termhint theme set lean --glyphs nerd # with Nerd Font icons
termhint theme set ~/my-theme.json # a theme file of your own
termhint theme off # your shell setup draws the prompt again
Theme commands
| Command | What it does |
|---|---|
termhint theme list |
The built-in themes and your own, with their description and credit (* = in use), then the glyph level in use and the folder for your own themes |
termhint theme set <theme> |
Let Termhint draw the prompt with this theme: a name from theme list, or a path to a .json theme file. Open shells switch at once. Options you leave out stay as they were |
termhint theme off |
Give the prompt back to your shell setup (Starship, Oh My Zsh, …); open shells switch at once |
termhint theme preview [<theme>] |
Print how a theme's prompt looks with made-up values, or every theme when none is named. Nothing is changed |
termhint help theme set |
The help of one command (termhint theme set --help prints the same) |
Options of theme set (--glyphs also works with theme preview):
| Option | What it does |
|---|---|
--glyphs auto|ascii|unicode|nerd |
What your terminal font can show. Default auto, or what you chose before. See Glyph levels |
--transient |
Once a command line is entered, only the prompt's last line (or the theme's short form) stays in front of it |
--no-transient |
Keep the whole prompt in front of entered lines |
--instant |
A new zsh shows its first prompt at once, before the rest of ~/.zshrc runs |
--no-instant |
Wait for ~/.zshrc again before the first prompt |
--instant adds a second marked block at the top of ~/.zshrc, backed up first. --no-instant,
theme off and termhint uninstall remove it. What ~/.zshrc prints while it loads appears
above the prompt once it is done.
The same choices are settings (see Settings reference):
| Key | Values | Default |
|---|---|---|
prompt.theme |
off, custom (the prompt made in Settings), a theme name, or a theme file's path |
off |
prompt.glyphs |
auto, ascii, unicode, nerd |
auto |
prompt.transient |
on, off |
off |
prompt.instant |
on, off |
off |
prompt.glyphs, prompt.transient and prompt.instant need a theme in use.
Glyph levels
Each theme has three glyph levels. --glyphs (or prompt.glyphs) picks one:
| Level | What the prompt uses |
|---|---|
auto |
Nerd Font icons in terminals that show them, standard symbols elsewhere (the default) |
ascii |
Letters, digits and punctuation only |
unicode |
Symbols every modern font has (arrows, check marks) |
nerd |
Nerd Font icons everywhere; the terminal needs a Nerd Font |
With auto, Termhint compiles the theme twice: once with icons, once with standard symbols. Each
shell loads the icon version only in a terminal that shows icons, so no terminal shows a box.
Which terminals show icons, and how to turn them on, is on Terminal icons.
When you turn icons on in a terminal while the prompt uses unicode, Termhint switches it to
auto.
Build your own prompt in Settings
Settings → Terminal → Prompt shows a terminal preview of your prompt in your colors and font. Pick Yours, then click anything in the preview to change it there:
- A part of the prompt: show or hide it, move it left or right, its line, its color and style, the text around it, and what only that part has (for the language version: which languages show, and no icons, emoji or Nerd Font icons).
- The prompt symbol: its text, its colors after a command that worked or failed.
- The command being typed: its highlighting colors (see Terminal colors).
- The
lsoutput: the file list colors. - The background: the terminal's background, text, cursor and selection colors.
Below the preview, Make it your own sets the number of lines (1 to 3), an empty line before each prompt, the look (Colored text or Blocks), where a block ends (Flat, Arrow, Round, Slanted) and every part as a button, including parts the preview does not draw (switched off, shown only over SSH, the Python environment, a git operation). Add Text adds a part with words or a symbol of your own.
Changes are saved as you go, in ~/.config/termhint/prompt-design.json; edit it in Settings, not
by hand. The prompt is the theme custom, and its parts are settings too:
termhint settings list prompt.
Prompt parts
Part ids for prompt.<part>.* keys and prompt.order:
| Part | What it shows | Shown by default | Default look |
|---|---|---|---|
user |
The user name | Yes, only over SSH or as root | Yellow, then the word "in" |
host |
The computer's name | Yes, only over SSH | Green, then the word "in" |
folder |
The current folder | Yes | Cyan |
git-branch |
The git branch, or the short commit when detached | Yes | Magenta, after the word "on" |
git-state |
The git operation in progress: rebase, am, merge, cherry-pick, revert or bisect |
Yes, while one runs | Yellow, in ( ) |
git-status |
Marks for the working tree (below) | Yes, when there is something to mark | Red, in [ ] |
language |
The project's language versions | Yes, in a project folder | Green, after the word "via", with emoji |
venv |
The active Python virtual environment | Yes, when one is active | Yellow, in ( ) |
duration |
How long the last command took | Yes, for slow commands | Yellow, after the word "took" |
time |
The time | No | Bright black, after the word "at" |
status |
The last command's exit status, when it failed | No | Red, after ✘ |
jobs |
The number of background jobs | No | Blue, after ✦ |
text-<n> |
Words of your own | Yes, once set | Blue |
Git status marks: = conflicts, $ stash, ✘ deleted, » renamed, ! modified, + added,
? untracked, ⇡ ahead, ⇣ behind, ⇕ both ahead and behind.
Keys of every part
Replace <part> with a part id, for example prompt.folder.color.
| Key | Values | What it does |
|---|---|---|
prompt.<part>.on |
on, off |
Whether the prompt shows the part |
prompt.<part>.place |
1, 2, 3, right |
On the left of line 1, 2 or 3, or at the right end of the first line. A line past prompt.lines means the last line |
prompt.<part>.color |
a color (below), none |
The text color in the text look; the background in the blocks look. none: the terminal's text color (blue in the blocks look) |
prompt.<part>.text-color |
a color, none |
The text color on the background, blocks look only. none: black |
prompt.<part>.bold |
on, off |
Bold (on for most parts) |
prompt.<part>.italic |
on, off |
Italics |
prompt.<part>.underline |
on, off |
Underlined |
prompt.<part>.word-before |
text, at most 40 characters | A word before the part in the terminal's own color, like "on" (text look only) |
prompt.<part>.word-after |
text, at most 40 characters | A word after the part in the terminal's own color, like "in" (text look only) |
prompt.<part>.prefix |
text, at most 40 characters | Text right before the part in its color: an icon, a bracket |
prompt.<part>.suffix |
text, at most 40 characters | Text right after the part in its color |
A color is default, black, red, green, yellow, blue, magenta, cyan, white,
bright-<name>, a number from 0 to 255, or #rrggbb. Named colors follow the terminal's
color scheme.
Keys of some parts
| Key | Values | What it does |
|---|---|---|
prompt.user.only-remote |
on, off |
Show the user name only in an SSH session or as root (default on) |
prompt.host.only-remote |
on, off |
Show the computer's name only in an SSH session (default on) |
prompt.language.icons |
off, emoji, nerd |
What shows before each version: nothing, an emoji (default), or a Nerd Font icon |
prompt.language.languages |
a comma-separated list, or none |
Which languages show: node, python, rust, go, ruby, swift, java, php, deno, bun (all by default) |
prompt.text-<n>.text |
text, at most 200 characters | What a text part says. Setting it the first time adds the part at the end of the first line; termhint settings reset prompt.text-<n> removes it |
With prompt.language.icons nerd, terminals without icons show the emoji instead, and the ASCII
level shows the version alone.
Layout keys
| Key | Values | Default | What it does |
|---|---|---|---|
prompt.lines |
1 to 3 |
2 |
How many lines the prompt has; the command is typed on the last |
prompt.blank-line-before |
on, off |
on |
An empty line before each prompt |
prompt.look |
text, blocks |
text |
Parts as colored text, or each on a background of its own |
prompt.edge |
flat, arrow, round, slant |
flat |
How a block ends in the blocks look. All but flat are Nerd Font icons: the terminal needs one |
prompt.order |
part ids, comma-separated | The parts listed come first, in that order; the others keep their order after them | |
prompt.folders |
0 to 20 |
3 |
How many trailing folders the folder part shows; 0 shows the whole path |
prompt.from-repository |
on, off |
on |
Inside a git repository, the folder starts at the repository's folder |
prompt.duration-from |
0 to 86400 |
2 |
Commands that ran at least this many seconds show how long they took |
prompt.clock |
24h, 12h |
24h |
The time part's clock |
prompt.clock-seconds |
on, off |
on |
The time part shows seconds |
prompt.symbol |
text, at most 12 characters | ❯ |
What the command is typed after; empty shows none |
prompt.symbol.stand-in |
text, at most 12 characters | ❯ |
What terminals without Nerd Font icons show instead of a symbol that is an icon |
prompt.symbol.color |
a color, none |
green |
The symbol's color after a command that worked |
prompt.symbol.error-color |
a color, none |
red |
The symbol's color after a command that failed |
prompt.symbol.bold |
on, off |
on |
The symbol in bold |
Examples:
termhint settings set prompt.theme custom # use the prompt made in Settings
termhint settings set prompt.folder.color cyan
termhint settings set prompt.time.on on
termhint settings set prompt.language.languages node,python
termhint settings set prompt.text-1.text work # adds a text part
termhint settings reset prompt.folder # the folder part as it came
Git status and versions
- The folder, branch, exit status, command duration, jobs and Python environment show as soon as the prompt is drawn.
- In zsh, the git status (changes, ahead/behind, stash, a rebase or merge in progress) comes from the app: it appears a moment after the prompt, and needs Termhint running.
- A language's version appears once the tool has answered, asked once per folder.
Your own theme file
Put your own themes in ~/.config/termhint/themes/<name>.json; they show in termhint theme list
by that name. You can also give termhint theme set the path of a file anywhere. Run
termhint theme set again after you change the file. The built-in themes are good starting
points.
{
"format": 1,
"name": "Example",
"blank_line_before": true,
"directory": { "max_folders": 3, "from_repository": true },
"duration": { "min_seconds": 2, "separator": " " },
"prompt": [
[ { "text": "{dir}", "fg": "blue", "bold": true },
{ "text": " {git_branch}", "fg": "242", "when": "git_branch" } ],
[ { "text": { "unicode": "❯ ", "ascii": "> " }, "fg": "magenta", "when": "ok" },
{ "text": { "unicode": "❯ ", "ascii": "> " }, "fg": "red", "when": "error" } ]
],
"right": [ { "text": "{duration}", "fg": "yellow", "when": "duration" } ]
}
| Key | What it holds |
|---|---|
format |
Always 1 |
name |
Up to 64 characters; description and credit are optional |
blank_line_before |
An empty line before each prompt |
directory |
max_folders (0 to 20, 0 keeps all), from_repository, truncation_prefix (at most 8 characters, like …/) |
duration |
min_seconds (default 2), separator between the parts ("" gives 1m5s, " " gives 1m 5s) |
time |
format: a strftime format for {time} (default %H:%M:%S) |
powerline |
separator and right_separator: joins segments that have a background color |
prompt |
1 to 4 lines, each a list of segments; the command is typed on the last |
right_first_line |
Shown at the right end of the first line, if it fits |
right |
The right prompt, on the line where the command is typed |
continuation |
Shown while a command continues on the next line |
transient |
What stays in front of an entered line with --transient |
A segment is a string, or an object with:
textwith{variable}placeholders ({{and}}for braces), orparts: a list of segments shown together. Text can be one string, or{ "nerd": …, "unicode": …, "ascii": … }per glyph level (asciirequired).when(all must hold) andwhen_any(one must hold);!namenegates.when_command: shown only while the command line starts with one of these commands, like["kubectl", "helm"](zsh only).fg,bg(colors as above),bold,dim,italic,underline.
Variables: dir, dir_head, dir_tail, user, host, time, status, duration, jobs,
venv, git_branch, git_staged, git_unstaged, git_added, git_modified, git_deleted,
git_renamed, git_untracked, git_conflicted, git_stashed, git_ahead, git_behind,
git_state, and the versions node_version, python_version, rust_version,
go_version, ruby_version, swift_version, java_version, php_version, deno_version,
bun_version. Conditions only: ok, error, ssh, root, git_dirty.
Unknown keys, names and colors are errors that say where they are.
bash
termhint install bash # prompt themes, terminal colors and runtime versions in bash
termhint uninstall bash # removes it again
termhint install bash writes ~/.config/termhint/shell/termhint.bash and sources it from the end
of ~/.bashrc and of the login file bash reads (~/.bash_profile, ~/.bash_login or ~/.profile,
whichever exists first; else a new ~/.bash_profile). Each file is backed up first.
bash gets the same themes, glyph levels and terminal colors, picked up at the next prompt. What differs from zsh:
- No autocomplete popup.
- No transient prompt and no
when_commandsegments.--instantworks on~/.zshrconly. - The git status comes from one
git statusper prompt inside a repository, so it does not need the app. - A tool's version is asked while the first prompt in its folder waits.
- The right prompt is drawn once; typing over it overwrites it. On a one-line prompt,
right_first_linewins overright.
Works with macOS's bash 3.2 and later. fish is not supported.
Use your own prompt or turn it off
termhint theme off,termhint settings set prompt.theme off, or the Shell's Own tile in Settings → Terminal → Prompt: your shell setup draws the prompt again. Open shells switch at once. Your design in Settings is kept.termhint uninstall(ortermhint uninstall bash) removes the shell integration and the compiled theme. See Uninstall.- When the trial ends without a license, the prompt goes back to your shell's own; your choice is kept for when a license is activated. See License.
Prompt not changing? See Troubleshooting.