Skip to content

Impressions

Edit source

One prompt, wearing every other prompt's face.

Part 5 of 5ofKronuZSH
  1. 1Molting Zsh
  2. 2What the Prompt Leaves Behind
  3. 3Before You Ask
  4. 4Punching Up
  5. 5Impressions

Part 4 made the serious case: a home-made prompt can paint as fast as the giants and carry a fraction of their code. This is the unserious case, and it is the one I enjoy most.

Because the whole layout is a handful of lines I own, the prompt is not condemned to look like mine. It can do impressions. Here it is wearing pure’s two-line face:

Terminal window
~/project main*
❯

…oh-my-zsh’s robbyrussell:

Terminal window
➜ project git:(main) ✗

…an agnoster ribbon:

Terminal window
you@laptop ~/project  main

…and, because nothing was stopping me, a DOS box from 1994:

Terminal window
C:\project\>

Same engine under every one. The same paint in about 7 milliseconds, the same gitstatusd, the same shell-integration marks. Only the costume changes. Here is how the costume comes off.

For most of this project the layout was welded shut. PROMPT was assembled once, at startup, with the segments in the order I liked: an error dot, user at host, git, then a second line with the time, the path, the caret. To change the shape you opened the engine and edited it.

That is fine while the shape is mine. It is useless if I want anyone else to reshape it without touching the file. So I lifted the layout out of the engine and into variables you set from ~/.zshrc.local, these three above all:

  • KZ_PROMPT_PROMPT, the live prompt (one line, or two).
  • KZ_PROMPT_RPROMPT, the right prompt.
  • KZ_PROMPT_TRANSIENT_PROMPT, the collapsed line the scrollback trick leaves behind.

Set any of them and the prompt takes the new shape at the very next draw. No rebuild, no reload, no restart.

Getting there took one trick that is not obvious. PROMPT is a template zsh re-expands on every draw, with PROMPT_SUBST on. A segment like $kz[git] works because it sits literally in that template, so each redraw re-parses it and resolves it. A layout handed in through a variable is a different animal: when zsh expands $KZ_PROMPT_PROMPT, what comes back is data, a finished string, not fresh syntax to parse again. A single ${(e)...} evaluates it once and stops, and the $kz[git] inside falls out as ten literal characters, unresolved.

The fix is to evaluate twice, in the one pass:

Terminal window
# one PROMPT_SUBST pass, two levels: the layout, then the segments it named
PROMPT='${(e)${(e)KZ_PROMPT_PROMPT-$DEFAULT_KZ_PROMPT_PROMPT}}'

The inner ${(e)} resolves the layout string; the outer one resolves the $kz[...] segments that string just produced. Both ride the single expansion zsh already does per draw, so a skin costs nothing at render time. It reads like a stutter. It is load-bearing.

A skin composes from two sets. The segment palette, $kz[git], $kz[pwd], $kz[time] and the rest, each a ready-made piece. And the color palette, $kz[FG.blue] for a foreground, $kz[BG.blue] for a background. So minimal’s whole layout is one line:

Terminal window
KZ_PROMPT_PROMPT='$kz[pwd]$kz[git] ${kz[FG.magenta]}${kz[GLYPH.caret]}${kz[RESET]} '

Rendered in a repository with some work in flight, it looks like this:

Terminal window
~/project main origin/main ( 1 ✗ ⇡1  2  1 ⊖1) ❯

You might ask why I reach for ${kz[FG.magenta]} when zsh’s own %F{magenta} is shorter and paints the same color. I used to. It cost me an evening.

The moment a color goes inside a conditional, %F{} turns on you. Say the branch should appear only when there is one:

Terminal window
# looks right, renders as a truncated mess
'${kz[git.branch]:+ %F{blue}(${kz[git.branch]})%f}'

zsh reads ${name:+word} by scanning for the brace that closes word. %F{blue} brought a brace of its own, and the } after blue is the first one zsh meets, so it decides the conditional ends there. Half the segment falls on the floor. ${kz[FG.blue]} is a balanced ${...}; zsh counts it right, and the segment stays whole. The palette earns its keep twice: once for theming a color, and once for being a color you can drop inside a conditional without it biting.

That is the whole reason the robbyrussell impression up top is only two lines, git:(branch) and all:

Terminal window
KZ_PROMPT_GIT='${kz[git.branch]:+ ${kz[FG.blue]}git:(${kz[FG.red]}${kz[git.branch]}${kz[FG.blue]})${kz[RESET]}${kz[git.dirty]:+ ${kz[FG.yellow]}✗${kz[RESET]}}}'
KZ_PROMPT_PROMPT='%(?.${kz[FG.green]}.${kz[FG.red]})➜%f ${kz[FG.cyan]}%c%f$kz[git] '

Two lines to wear oh-my-zsh’s flagship theme, reading git from the same daemon, inside the same paint budget.

Once the layout is loose, taste is the only limit, and I have little. The DOS box up top is one line, the path as a drive letter, bold green on the memory of a CRT:

Terminal window
KZ_PROMPT_PROMPT='%B${kz[FG.green]}C:\\${PWD:t}\\>%f%b '

Or an all-emoji line: a folder, a plant for the branch, a small fire when the tree is dirty, a spark for the caret:

Terminal window
📁 ~/project 🌿 main 🔥 ⚡

The agnoster ribbon up top wanted one thing the rest did not: backgrounds. The palette is just color codes now, layer-neutral, so the engine wraps each hue both ways: ${kz[FG.green]} paints it as a foreground, ${kz[BG.green]} the same code as a background. A powerline skin fills its blocks with the BG. side. Nerd Font separators, solid color, the whole agnoster silhouette, out of the engine that a line ago was a DOS box.

There is exactly one rule, and you will not trip it by accident. Every prompt this shell draws is wrapped in the OSC 133 marks that tell the terminal where a command begins and ends, and the OSC 1337 marks iTerm reads for the same purpose. Those live in the engine, wrapped around whatever a skin renders, so the quiet scrollback, the command boundaries, iTerm’s jump-to-previous-command, all of it survives any costume you hang on the prompt.

I did not want to take that on faith. So there is a small harness that renders a skin in a throwaway shell, no terminal attached, and asserts the marks are still there:

dev/preview-skin.py skins/robbyrussell.zsh

It prints the prompt and fails loudly the instant a skin drops a mark. Every impression above went through it before it earned a file.

They all live in skins/, a few lines each. Copy one into your ~/.zshrc.local, or delete an %F and write your own in the time it takes your coffee to cool. That was the arc of these five posts. Not that my prompt is the one to use, but that the file got small enough, and now loose enough, that the one to use is the one you shape.

Go wild.