GPY: Guppy Prompt, Yay!

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.

Features

• 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

Performance

Measured on pinned repositories, a single gpy-agent oneshot git request from GPY 0.4.0 was as fast as Starship 1.26.0 on small repositories and 1.3 to 2 times faster on large ones (2026-10-17). These are oneshot process timings, not prompt latency.

The large-repository 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. With the daemon running, the same request on the two large repositories takes about 3.5 ms (median, including starting socat). How it was measured, and how to run it yourself.

Install

More info: Installation & Troubleshooting Guide.

Requirements

• Bash and Fish talk to the agent through socat, or an nc that supports -U (netcat-openbsd); Zsh needs neither. Without one, every prompt starts a gpy-agent oneshot process. gpy doctor reports a missing client.
• The default prompt uses Nerd Font glyphs. gpy setup switches to ASCII icons when it finds no Nerd Font; see Icons and Nerd Fonts.
• Supported systems and shell versions: Supported Platforms and Shells.

Curl

curl -fsSL https://github.com/jpease/gpy/releases/latest/download/install-oneline.sh | sh
exec fish  # or: exec zsh / exec bash

The 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.

Homebrew

brew install jpease/tap/gpy
gpy setup
exec "$SHELL"

From source

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 .

Usage

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.yaml

Tab completion for gpy is installed for all three shells.

Documentation

• Installation Guide
• User guide, CLI reference, and Advanced Configuration
• Migrating from Starship
• GPY vs Starship performance
• Developer docs

Contributing

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).

License

GPL-3.0-or-later. See LICENSE.