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

> Source: <https://gist.github.com/thisistonydang/0b6c03ec9aa9b619ffecd48f58fd40c7>
> Published: 2026-06-29 21:31:43+00:00

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)