Install

Ghostbranch is a single program with nothing else to install. It runs on macOS, Windows and Linux, and it needs git 2.38 or later on your PATH.

Choose a route

Pick whichever suits your machine. Each one installs the same binary.

HomebrewScoop / wingetnpmInstall scriptGo

Homebrew

$ brew install ghostbranch-labs/tap/ghostbranch

Copy

Placeholder: the Homebrew tap isn’t published yet.

Scoop / winget

$ scoop bucket add ghostbranch <BUCKET_URL>

$ scoop install ghostbranch

# or winget

$ winget install <WINGET_ID>

Copy

Placeholder: the Scoop bucket and winget package aren’t published yet.

npm

$ npm install -g ghostbranch

# also pnpm, yarn and bun

Copy

Placeholder: the npm package isn’t published yet.

Install script

$ curl -fsSL <INSTALL_SCRIPT_URL> | sh

Copy

Placeholder: the install script isn’t published yet.

Go

$ go install github.com/ghostbranch-labs/ghostbranch/cmd/ghostbranch@latest

Copy

Works once the repository is public.

Note

Ghostbranch has no release yet. Each route above says so until the first release is out, and the go install route works once the code repo is public.

Check that it works

First, ask for the version:

TerminalCopy

$ ghostbranch version

ghostbranch v0.0.0-20261014135732-03a0aa5dc864 (commit 03a0aa5dc864), JSON contract 0.15

This one is a development build. A release prints its version number instead. The JSON contract is the version of the --json output that agents and scripts read.

Then run ghostbranch doctor. It checks your setup, names the fix for anything that’s wrong, and changes nothing. Right after you install, it looks like this:

TerminalCopy

$ ghostbranch doctor

✓ tools git 2.43.0; ghostbranch v0.0.0-20261014135732-03a0aa5dc864, commit 03a0aa5dc864

✗ token no GitHub token: run `ghostbranch login`, or set GHOSTBRANCH_TOKEN or GH_TOKEN, or run `gh auth login`

fix: ghostbranch login

– pair not in a checkout of a registered public repo; pass --repo <owner/repo> to check a pair

– guard no pair, so no public repo to guard (see pair)

✓ state workspace "default"; the records are readable, none is newer than this binary, and no gate job has been pending for over an hour (features not checked: no readable pair); its state directories are private to you

– ci no readable pair to audit (see pair)

update check: off (development build)

error: 1 check(s) failed: token [DOCTOR_FAILED]

Next:

ghostbranch login (a person must run this)

token: no GitHub token: run `ghostbranch login`, or set GHOSTBRANCH_TOKEN or GH_TOKEN, or run `gh auth login`

Each line is one check. The mark in front says how it went:

Mark	Meaning
check mark	Passed.
exclamation mark	A warning: things work, but read the message.
cross	Failed. The fix: line below it is the command that fixes it.
–	Skipped: there’s nothing to check yet.

The token check fails because you haven’t logged in yet, and the next page fixes that. The pair, guard and CI checks wait until you set up a repo and run doctor inside it.

Tip

Run ghostbranch doctor whenever something fails in a way you don’t understand. It’s safe to run at any time.

Updates, and no telemetry

Ghostbranch sends no telemetry. The one request it makes on its own is the update check. It asks GitHub whether a newer release is out: at most two anonymous requests, with no token and no IDs. It tells you when there is one, and it never downloads or installs anything itself.

Development builds skip the check, as the last line of doctor says. To turn it off in a release, set GHOSTBRANCH_NO_UPDATE_CHECK=1. CI turns it off by itself.