Environment variables

These variables change what ghostbranch does. Flags win over them where both exist, such as --workspace and --no-color.

Tokens

Ghostbranch uses the first token it finds, in this order:

1. GHOSTBRANCH_TOKEN;
2. your stored login, from ghostbranch login;
3. GH_TOKEN;
4. GITHUB_TOKEN;
5. the GitHub CLI’s token (gh auth token).

ghostbranch auth status says which one is in use. See Which token wins.

Variable	What it does
GHOSTBRANCH_TOKEN	The GitHub token to use, ahead of everything else. While it’s set, the stored login is never read, so the OS keychain isn’t touched. Coding agents and CI use it for a token of their own, such as one that reaches only the shadow repo.
GH_TOKEN	A GitHub token, used when there’s no GHOSTBRANCH_TOKEN and no stored login. The GitHub CLI reads it too.
GITHUB_TOKEN	The same, after GH_TOKEN.

ghostbranch logout removes only the stored login: these variables stay as they are.

State and workspaces

Variable	What it does
GHOSTBRANCH_HOME	The folder where Ghostbranch keeps this machine’s state: its workspaces, each with its pairs, grants, waivers, plans and ledger, plus locks and the update check’s cache.
GHOSTBRANCH_WORKSPACE	The workspace to use when a command has no --workspace. Without either, it’s default. A name is lowercase letters, digits and -, starts with a letter or a digit, and is up to 64 characters.

Without GHOSTBRANCH_HOME, the state folder is:

• Windows: %LOCALAPPDATA%\ghostbranch;
• macOS: ~/Library/Application Support/ghostbranch;
• Linux: $XDG_STATE_HOME/ghostbranch, or ~/.local/state/ghostbranch when XDG_STATE_HOME isn’t set.

The push guard reads GHOSTBRANCH_HOME from wherever git runs it. If you set it in one shell only, a push from another shell is checked against the default folder; ghostbranch doctor warns about this.

Who is acting

Variable	What it does
GHOSTBRANCH_ACTOR	Who the ledger records as running each command: human:<name>, agent:<name> (such as agent:claude-code) or app. Anything else stops the command with BAD_FLAG.

It’s a label: it never grants or blocks anything. Without it, the ledger records human:<your GitHub login>, or human:unknown with an ACTOR_UNKNOWN warning when the login can’t be read.

It also tells Ghostbranch whether a person or an agent is running it. agent: and app count as an agent, and human: as a person. Otherwise a run counts as an agent when it’s inside Claude Code (CLAUDECODE is set) or has no terminal a person could type into. See Say who is acting.

Output and the update check

Variable	What it does
NO_COLOR	Set to any non-empty value, it turns colour off in human output, as --no-color does. TERM=dumb does too. JSON never has colour.
GHOSTBRANCH_NO_UPDATE_CHECK	Set to any non-empty value, it turns the update check off.

The update check is also off in CI: when CI, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, CIRCLECI, JENKINS_URL or TF_BUILD is set.

Also read

Variable	What it does
GIT_EDITOR, VISUAL, EDITOR	The editor for the commit message of a squash promote run at a terminal without -m (and without --non-interactive). The first one set wins; without any, it’s notepad on Windows and vi elsewhere.
CLAUDE_CONFIG_DIR	Where ghostbranch guide --install claude writes the skill: skills/ghostbranch/SKILL.md in that folder, instead of in ~/.claude.
CLAUDECODE	Set by Claude Code. A run with it counts as an agent, unless GHOSTBRANCH_ACTOR names a person.
LOCALAPPDATA, XDG_STATE_HOME	Where the default state folder goes, as above.

In the shadow repo’s sync workflow

Name	What it does
GHOSTBRANCH_SYNC_TOKEN	A secret in the shadow repo, not a variable on your machine. The scheduled sync workflow uses it instead of its default token, which can’t push commits that change workflow files. Make it a fine-grained token with Contents and Workflows write on the shadow repo only, never on the public repo. See Setting up CI.

Errors you may see

AUTH_MISSINGexit 1No GitHub token was found.

Causes

• GHOSTBRANCH_TOKEN, GH_TOKEN and GITHUB_TOKEN are unset, there is no stored login (ghostbranch login), and `gh auth token` gave nothing

What to do

A person runs `ghostbranch login`, or sets GHOSTBRANCH_TOKEN. Agents and CI use a token of their own in GHOSTBRANCH_TOKEN; the permissions each command needs are in the token table of `ghostbranch guide`. `gh auth login` also works.

This needs a person.

BAD_FLAGexit 2A flag, argument or option value is invalid.

What to do

Fix the value named in error.field.

ACTOR_UNKNOWNwarningGHOSTBRANCH_ACTOR is unset and the GitHub login wasn't read; the ledger records human:unknown.

What to do

Set GHOSTBRANCH_ACTOR, for example agent:claude-code.

AGENT_ON_PERSON_LOGINwarningThis run looks like an agent or a script, and it is using a person's stored login, which can publish.

What to do

Give the agent its own shadow-only token in GHOSTBRANCH_TOKEN (see ghostbranch guide § Tokens). The person's login still needs the console code to publish.

UPDATE_AVAILABLEwarningA newer Ghostbranch release is out (details.latest; this is details.current). details.security is true when it fixes a security issue that affects this version (details.advisories).

What to do

Tell the person, quoting details.upgrade (the command that upgrades this install) and, for a security fix, details.advisories. Never run the upgrade yourself. GHOSTBRANCH_NO_UPDATE_CHECK=1 turns the check off.