The prompt

zsh/prompt.zsh draws two lines: an info line with every fact, then the input line, which holds only the $.

_{Rendered from the real prompt, 96 columns wide, for a demo project: the default theme and SHKIT_FORMAT='{dir} · {git} · {mr}'.}

• How it stays fast
• Built-in blocks
• Format
• Colors
• Icons
• Behaviour
• Notifications
• Tab title
• Security

How it stays fast

Each prompt only computes local facts: the directory, git status, files on disk. That stays under 50 ms even in a 35,000-file repository.

Anything that needs the network or a slow command is read from a cache under $XDG_RUNTIME_DIR ($TMPDIR on macOS):

• git fetch, for a true behind count;
• the merge / pull request, its CI and its review, through glab / gh;
• docker ps;
• the untracked files of {git.untracked}, counted again at each new prompt.

When a cache entry is older than its TTL, a background job refreshes it and a muted ↻ shows. When the job finishes, the prompt redraws in place, without pressing Enter. Every job has a timeout, and only one runs per cache entry. The untracked count shows no ↻: it would show at every prompt.

Built-in blocks

A block with nothing to say shows nothing, and neither do the separators around it. So the default format holds nearly every block: most only show when there is something to say.

{ticket} and {stack} need a setting, usually per project:

shkit project
shkit set -p ticket_url 'https://tracker.example/t/{id}'   # {id} = the ticket id
shkit set -p ticket_pattern 'SHOP-[0-9]+'                  # default: [A-Z]+-[0-9]+
shkit set -p stack shop                                    # the compose project name

You can write your own or get them from plugins. shkit show lists every block available.

Format

Two settings lay the prompt out:

SHKIT_FORMAT='{host} · {dir} · {git} · {ticket} · {mr}  {review} · {stack} · {docker} · {duration} · {status}'   # the info line (default)
SHKIT_RIGHT_FORMAT='{agents} · {quota}'           # right end of the info line (default)

A format is {block} placeholders and literal text:

• Text between two blocks is a separator. It shows only when a block on each side shows something.
• Text before the first block or after the last one always shows.
• Literal text is printed as is, in the MUTE color. % has no special meaning.
• An unknown {name} shows nothing.

shkit set format '[{git}] {dir}'
shkit set right_format ''            # nothing on the right

The right part is aligned to the terminal's right edge and follows its width when you resize the window. If both parts can't fit on one line, the right part is left out.

SHKIT_SEPARATOR (default ' · ') separates the parts inside a block, for example the branch, its status and a rebase in {git}.

The input line is SHKIT_ICON_PROMPT (default $) in the PRIMARY color, and in bold FAIL after a failed command.

Colors

Blocks never use color codes directly. They use roles, and each role is an SGR code: '1;32' (bold green), '38;5;33' (256-color), '38;2;255;128;0' (true color).

shkit set color_accent '38;5;33'
shkit set quota_palette 108 150 185 227 221 215 209 167

A block may add its own role, for example SHKIT_COLOR_PHP.

Icons

Every icon is a variable. Set one to '' to drop it.

shkit set icon_branch $'\ue0a0'     # a branch glyph before the branch name
shkit set icon_agent '🤖'

The Nerd Font glyphs need a Nerd Font, or Symbols Nerd Font as a fallback font in your terminal.

Behaviour

These are best set in settings.sh, or with shkit set:

A fetch never runs during a rebase or other operation in progress, never asks for credentials, and gives up after 60 s.

Notifications

When a command ran for SHKIT_NOTIFY_AFTER seconds or more (30 by default), a desktop notification from shellkit says so as it ends: ✓ make done or ✗ make failed · exit 2, with a green check or a red error icon, then how long it took and the full path. It comes from notify-send on Linux, or osascript on macOS (which shows it under Script Editor, with no icon). Over SSH, on Linux without a display, or when neither exists, the terminal bell rings instead, so the tab gets flagged.

• Only the command's name is sent, never the line: a notification history would otherwise keep a token typed in it.
• Interactive programs are skipped: a line where any command is listed in SHKIT_NOTIFY_IGNORE (editors, pagers, ssh, top, database shells, fg…) is not notified. Aliases are expanded, and sudo and its options, env, nice, VAR=…, ( and { are looked through: sudo -E vim and make && vim are skipped. The name shown is the line's first command, past a cd.
• Nor what you stopped: a command ended with Ctrl+C or suspended with Ctrl+Z.
• It fires even when you are watching: no terminal reports portably whether its tab is visible.

shkit set notify_after 120                       # longer commands only
shkit set notify_timeout 5000                    # on screen for 5 s
shkit set notify_ignore vim less man ssh docker  # the full list (an array, or one string)
shkit set notify false                           # off

Or in settings.sh, or for one shell: export SHKIT_NOTIFY=false, before zsh starts. SHKIT_NOTIFY_TIMEOUT only applies to notify-send, and GNOME Shell keeps its own delay for normal notifications. macOS sets its own delay too.

Tab title

The terminal tab shows the full current path, even in $HOME. While a refresh runs, SHKIT_SPINNER frames animate in front of it. Turn that off with SHKIT_TITLE_SPINNER=false.

Security

PROMPT_SUBST stays off, and every dynamic text (branch names, file contents, API answers) is escaped before it reaches the prompt. A branch named $(rm -rf ~) or %F{red} is printed as is, never run or interpreted.