starship-git-kaomoji

Animated git-status kaomoji for Starship + zsh

Inspired by the beloved jovial theme — rainbow powerline on top, expressive kaomoji on the input line.

Line 1: Starship status bar  ·  Line 2: animated kaomoji pointer

Most Starship setups put everything on one line. jovial showed how delightful a two-line shell can feel — a rich status bar above, a playful input line below.

starship-git-kaomoji brings that spirit to Starship:

No Python. No JSON. No Node. Just zsh + sh + a plain-text face file.

Clean repo — all is well

Dirty repo — something changed

All 14 git states at a glance

clean · dirty · staged · untracked · conflict · rebase · merge · ahead · behind · diverged · cherry · revert · bisect · nogit

• Two-line prompt — Starship draws line 1 in precmd, zsh draws line 2 via PROMPT
• 14 git states — clean, dirty, staged, conflict, rebase, ahead/behind, and more
• Idle animation — kaomoji cycles through frames while you think (configurable interval)
• Three face roles per state — health (status bar), pointer (static), anim (frames)
• Fast — faces compiled to cache; animation runs in-process (~0.08 ms/frame)
• Zero extra runtimes — kaomoji.faces is plain INI-like text parsed by POSIX sh
• Terminal-friendly — tested on Ghostty, iTerm2, Alacritty

git clone https://github.com/YOUR_USER/starship-git-kaomoji.git \
  ~/.local/share/starship-git-kaomoji

Add to ~/.zshrc after eval "$(starship init zsh)":

export STARSHIP_KAOMOJI_HOME="$HOME/.local/share/starship-git-kaomoji"
eval "$(starship init zsh)"
source "$STARSHIP_KAOMOJI_HOME/init.zsh"

init.zsh auto-detects its own directory — STARSHIP_KAOMOJI_HOME is optional if you source by absolute path.

Merge examples/starship.snippet.toml into ~/.config/starship.toml.

Key points:

1. Start format with ╭─ (line 1 corner)
2. Do not put $character / the input line in format — zsh owns line 2
3. Add custom.git_kaomoji for the health indicator in the status bar
4. Disable [git_status] — this library replaces it

Minimal snippet:

[character]
success_symbol = ""
error_symbol = ""
format = "$symbol"

[git_status]
disabled = true

[custom.git_kaomoji]
when = "git rev-parse --is-inside-work-tree >/dev/null 2>&1"
style = "bg:#FCA17D fg:black bold"
format = '[$output]($style)'
command = "$STARSHIP_KAOMOJI_HOME/git-kaomoji.sh health"

Reload:

source ~/.zshrc

Edit kaomoji.faces — one block per git state:

[conflict]
health= (╯°□°)╯
pointer=(╯°□°)╯ 
anim=(╯°□°)╯ |┻━┻ (╯°□°)╯|(ノ°ο°)ノ|flip the table again

Frame selection: index % frame_count.

Point to a custom file:

export STARSHIP_KAOMOJI_FRAMES="$HOME/.config/kaomoji/my.faces"

On first load, faces compile to ~/.cache/starship-kaomoji/faces-*.sh and refresh automatically when the source file changes.

# Slower, calmer animation
export STARSHIP_KAOMOJI_INTERVAL=2.5

┌─────────────────────────────────────────────────────────┐
│  precmd                                                   │
│    ├─ starship prompt  →  line 1 (async after commands)  │
│    └─ PROMPT hook      →  line 2 (kaomoji + cursor)      │
├─────────────────────────────────────────────────────────┤
│  idle timer (background)                                  │
│    SIGUSR1 → frame++ → zle reset-prompt                  │
└─────────────────────────────────────────────────────────┘

./kaomoji-benchmark.sh [repo_dir] [iterations]

Preview images are PNG files in docs/assets/ (generated from the .svg sources). GitHub renders PNG reliably; SVG previews often break due to sanitization and font issues.

To regenerate after editing the SVG sources:

brew install librsvg   # once
cd docs/assets
for f in demo-*.svg; do rsvg-convert -w 1840 "$f" -o "${f%.svg}.png"; done

To use real terminal screenshots instead, save as demo-clean.png / demo-dirty.png and update paths in this README.

• Face concept and layout inspired by jovial by @zthxxx
• Built on Starship

MIT — use freely, customise faces, share your kaomoji.