Show your Neon branch in your terminal prompt (Starship) — copy-paste / agent-ready setup

A developer created a Starship prompt segment that displays the current Neon branch linked to a directory. The segment uses the Neon CLI's `neon status --current-branch` command, which reads a local `.neon` file without making network requests. It is hidden when not in a Neon project, and the setup is provided as a copy-paste configuration for Starship.

Tweet: https://x.com/thisistonydang/status/2071723089755603091 https://x.com/thisistonydang/status/2071723089755603091 A drop-in Starship https://starship.rs segment that displays the Neon branch your current directory is linked to, powered by the Neon CLI. It appears only inside directories linked to a Neon project, and shows nothing everywhere else. ~/code/my-app 🌿 main ❯ Using a coding agent?Hand it this whole file by saying:"Set up Starship with the Neon branch segment by following this gist:The steps below are ordered, idempotent safe to re-run , and self-checking. https://gist.github.com/thisistonydang/0b6c03ec9aa9b619ffecd48f58fd40c7 " - Adds a custom.neon module to Starship that runs neon status --current-branch . - That command prints the branch pinned in the nearest .neon file walking up the directory tree and makes no network request — it just reads a local file. - The segment is hidden when you're not in a Neon project the command exits non-zero when no branch is pinned , so you never get a stray icon. Node.js ≥ 22 — node --version Neon CLI ≥ 2.28.0 — provides neon status --current-branch . Install/update: npm install -g neonctl the installed commands are neon and neonctl . Starship — https://starship.rs/guide/ -installation https://starship.rs/guide/ -installation A linked Neon project in the directory where you want the branch to show: neon link then neon checkout <branch this writes a local .neon file with the branch . Run these in order. Each step is safe to re-run. node --version expect v22+ Neon CLI 2.28.0+ requires Node = 22 neon --version expect 2.28.0+ ; if missing or older: npm install -g neonctl starship --version if missing, install from https://starship.rs Add the matching line to your shell rc if it isn't already there : zsh — append to ~/.zshrc : eval "$ starship init zsh " bash — append to ~/.bashrc : eval "$ starship init bash " fish — append to ~/.config/fish/config.fish : starship init fish | source mkdir -p ~/.config && touch ~/.config/starship.toml Append this block to ~/.config/starship.toml only if a custom.neon table is not already present don't create a duplicate custom.neon : custom.neon description = "Current Neon branch" command = "neon status --current-branch" prints the branch pinned in .neon no network when = "neon status --current-branch" exits non-zero when no branch - segment is hidden symbol = "🌿 " style = "bold green" format = " $symbol$output $style " If your starship.toml defines its own format = "..." , add ${custom.neon} wherever you want the branch to appear e.g. right after $git branch . If you have no custom format , Starship shows custom modules automatically — nothing to do here. exec "$SHELL" or just open a new terminal cd <a directory linked to a Neon project neon status --current-branch should print your branch, e.g. "main" You should now see 🌿 main or your branch in the prompt. In a non-Neon directory, the segment is simply absent. - Symbol — symbol = "🌿 " . Use any emoji, or a Nerd Font https://www.nerdfonts.com/ glyph if your terminal font has one for example the database icon . - Color — style = "bold green" any Starship style string . - Faster outside Neon projects optional — when above runs the CLI on every prompt everywhere ~25 ms each . To skip it entirely unless a .neon exists up the tree, replace when with a pure-shell check that only invokes the CLI inside Neon projects. This when is POSIX-sh script, so add shell = "sh" to the block to ensure it runs under sh even if your interactive shell is fish or PowerShell: shell = "sh" when = ''' d="$PWD" while "$d" = "$HOME" && "$d" = / ; do if -e "$d/.neon" ; then neon status --current-branch /dev/null 2 &1 exit $? fi d=$ dirname "$d" done exit 1 ''' Nothing shows up — Confirm neon status --current-branch actually prints a branch in that directory. You need a pinned branch: run neon link then neon checkout <branch this creates the .neon file . A bare icon with no branch name — Make sure the when line is present; it hides the segment when there's no branch. This requires Neon CLI ≥ 2.28.0 older versions exit 0 even with no branch . Update with npm install -g neonctl . Prompt feels slow — Ensure you're on Neon CLI ≥ 2.28.0 it has a fast path for this command . If it still lags, raise Starship's timeout by adding command timeout = 1000 at the top of starship.toml , or use the "Faster outside Neon projects" when above.— Run neon: command not found npm install -g neonctl Node ≥ 22 and make sure your npm global bin directory is on your PATH . The symbol renders as a box or — Your terminal font lacks that glyph. Use a plain emoji, or install a ? Nerd Font https://www.nerdfonts.com/ . Learn more: Neon CLI https://neon.com/docs/reference/neon-cli · Starship custom commands https://starship.rs/config/ custom-commands