GPY is a shell prompt for Fish, Zsh and Bash. A small background agent watches
your repositories, so the prompt shows git and language state without running
git status on every command.
If the agent is not running, the prompt still draws; it computes each segment itself, which is slower. Timeouts and other tuning: Environment Variables.
- Supported Platforms and Shells
- macOS, Linux, and Windows through WSL
- Fish, Zsh, and Bash with some limitations
- Git detection
- Language detection
- Themes, including import of Starship
starship.toml - Palettes, including import of tinted-theming base16/base24 schemes
A whole prompt (clock, duration, directory and git) takes GPY 3–6 ms on macOS
and about 1.5 ms on Linux, in Bash, Zsh and Fish alike, because git status
comes from the agent's cache. Starship 1.27.0 takes 18–20 ms on a small
repository and about 130 ms on kubernetes on the same Mac (2026-11-19, GPY
0.12 code). The cache stays current: a saved change shows in the prompt about
140 ms later on macOS and 110 ms on Linux, and idle Zsh and Fish prompts
repaint on their own. Without the agent, one gpy-agent oneshot git request
is about 1.25 times faster than Starship's on small repositories and 1.35 to
2.2 times faster on large ones.
The large-repository oneshot lead depends on git's untracked cache being
present in the repository's index. The GPY agent adds git's untracked cache
to a repository's index where core.untrackedCache is unset, and your own git
commands can add it too; the benchmark primes it itself before timing.
gpy-agent oneshot never adds it, GPY never writes your git config, and a
value you set yourself is respected.
How it was measured, and how to run it yourself.
More info: Installation & Troubleshooting Guide.
- No IPC client is needed:
gpytalks to the agent's socket itself. - The default prompt uses Nerd Font glyphs.
gpy setupswitches to ASCII icons when it finds no Nerd Font; see Icons and Nerd Fonts. - Supported systems and shell versions: Supported Platforms and Shells.
curl -fsSL https://github.com/jpease/gpy/releases/latest/download/install-oneline.sh | sh
exec fish # or: exec zsh / exec bashThe installer is an asset of the latest release and checks every download against that release's published checksums; see what the checksums do and do not prove.
brew install jpease/tap/gpy
gpy setup
exec "$SHELL"Needs Rust 1.99+. See Building from Source.
git clone https://github.com/jpease/gpy.git
cd gpy
(cd gpy-agent && cargo build --profile release-dist)
mkdir -p ~/.local/bin
install -m 755 gpy-agent/target/release-dist/gpy-agent gpy-agent/target/release-dist/gpy ~/.local/bin/
~/.local/bin/gpy setup --from .gpy status # agent status and diagnostics
gpy doctor # health checks
gpy theme list
gpy theme use <name> # switch theme
gpy config wizard # interactive theme, palette and segment setup
gpy theme import ~/.config/starship.toml --name my-prompt
gpy palette import scheme.yamlTab completion for gpy is installed for all three shells.
- Installation Guide
- User guide, CLI reference, and Advanced Configuration
- Migrating from Starship
- GPY vs Starship performance
- Developer docs
See CONTRIBUTING.md. just check runs the full gate. To run an
unreleased build in an isolated shell without touching an installed release, see
scripts/README.md (just dev / scripts/gpy-dev.sh).
GPL-3.0-or-later. See LICENSE.
