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

Tweet: https://x.com/thisistonydang/status/2071723089755603091

A drop-in Starship 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 runsneon status --current-branch

. - That command prints the branch pinned in the nearest .neon

file (walking up the directory tree) and makesno 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— providesneon status --current-branch

. Install/update:npm install -g neonctl

(the installed commands areneon

andneonctl

).Starship—https://starship.rs/guide/#-installation** A linked Neon project**in the directory where you want the branch to show:neon link

thenneon 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 aNerd Fontglyph 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, replacewhen

with a pure-shell check that only invokes the CLI inside Neon projects. Thiswhen

is POSIX-sh script, so addshell = ["sh"]

to the block to ensure it runs undersh

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— Confirmneon status --current-branch

actually prints a branch in that directory. You need a pinned branch: runneon link

thenneon checkout <branch>

(this creates the.neon

file).A bare icon with no branch name— Make sure thewhen

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 withnpm 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 addingcommand_timeout = 1000

at the top ofstarship.toml

, or use the "Faster outside Neon projects"when

above.— Runneon: command not found

npm install -g neonctl

(Node ≥ 22) and make sure your npm global bin directory is on yourPATH

.The symbol renders as a box or— Your terminal font lacks that glyph. Use a plain emoji, or install a?

Nerd Font.

Learn more: Neon CLI · Starship custom commands

source & further reading

gist.github.com — original article immunity-agent: the control plane for AI agents — intercept, policy, audit Fix: This model is not supported when using X-OpenAI-Internal-Codex-Responses-Lite config.json