What Ghostbranch can see

Ghostbranch is a program on your own machine. There’s no Ghostbranch server, no account with us, and no hosted service in the middle. It works with your repos through GitHub, using a GitHub token you give it, and keeps its own records in a folder on your machine.

Who it talks to

Ghostbranch talks to GitHub only: github.com for git and for logging in, and api.github.com for everything else. Every request to GitHub carries your token, except two: logging in, which is how you get a token, and the update check, which asks GitHub for the latest release anonymously. Updates, and no telemetry says exactly what it sends.

Nothing about your code, your repos or your use of Ghostbranch is sent anywhere else.

The token decides what it can reach

Ghostbranch can do on GitHub exactly what its token can do, and nothing more. Which token it uses is in Log in.

• With the Ghostbranch GitHub App (ghostbranch login), the token reaches only the repos you picked when you installed the app. There it can do only what the app’s permissions allow and what you may do yourself.
• With your own token, it reaches what that token reaches. A fine-grained token can be limited to the shadow repo alone.

That’s also what keeps a coding agent from publishing. Ghostbranch’s own safeguards, the console code, agent grants and the push guard, stop mistakes. They don’t stop a determined program running as your user, which could fake a terminal, edit Ghostbranch’s files, or push with git directly. What stops that is a token that can’t publish: give the agent one that reaches only the shadow repo, and keep it away from your own tokens. Tokens and the keychain shows how.

What it keeps, and where

What	Where	Who can read it
Your stored login: the GitHub token, its refresh token, their expiry, your GitHub account name	Your operating system’s keychain, in one entry named ghostbranch	Your user, as the keychain allows
Saved plans, agent grants, waivers, and the ledger of every change Ghostbranch made and who started it	The workspace folder, under GHOSTBRANCH_HOME	Your user only, on macOS and Linux
The update check’s cache	update-check.json, at the top of GHOSTBRANCH_HOME	Your user only, on macOS and Linux
The list of repo pairs, and a local git copy of each pair’s two repos	The workspace folder, under GHOSTBRANCH_HOME	Your user only, on macOS and Linux
Each feature’s record, and each saved plan’s commits	The shadow repo on GitHub, under refs/ghostbranch/	Whoever can read the shadow repo
The settings, in .ghostbranch.yml	The shadow repo’s ghostbranch branch	Whoever can read the shadow repo
The push guard’s hook	Your checkout’s git hooks folder	Your usual file permissions

GHOSTBRANCH_HOME is %LOCALAPPDATA%\ghostbranch on Windows, ~/Library/Application Support/ghostbranch on macOS, and $XDG_STATE_HOME/ghostbranch on Linux (by default ~/.local/state/ghostbranch), unless you set it. Environment variables has the details.

Tokens never go in a file

Ghostbranch keeps a token only in the keychain. On a machine with no keychain, it stores nothing, and you set GHOSTBRANCH_TOKEN instead. A token set in GHOSTBRANCH_TOKEN is never stored at all, and with it set, the keychain isn’t opened.

Ghostbranch never prints a token, logs it or puts it in an error message. When it runs git, it hands the token over in git’s environment rather than on the command line or in a config file, so the token isn’t written into its local copy of the repos and doesn’t show in a list of running processes. For those runs it also turns off git’s credential helpers and ignores your own global git settings, so neither can redirect a push or hand git another password.

File permissions

On macOS and Linux, Ghostbranch keeps its folder to your user. It creates its folders with mode 0700 and its files with mode 0600, readable and writable by you only: plans, grants, waivers, the ledger, the list of pairs and the update check’s cache. Its local copy of the shadow repo, with your unreleased commits, writes its files 0600 too.

An install made by an older version has looser folders, mode 0755. The next Ghostbranch command that changes something makes them private, and prints one line for each folder it changed:

· Made /home/you/.local/state/ghostbranch/workspaces private (0700)

Ghostbranch changes the top folder only when it’s the default one. If you set GHOSTBRANCH_HOME yourself, that folder is yours to manage, and Ghostbranch never changes its mode. The folders inside it are still made private.

ghostbranch doctor checks all of this, and only reports. When a folder or file is open to other users, it warns and names the chmod that fixes it. It never changes anything itself. To close everything at once on an older install, or on a GHOSTBRANCH_HOME you set:

chmod 700 "$GHOSTBRANCH_HOME"   # or the default folder above, if you haven't set it

On Windows, the default folder is inside your user profile, and the files take its permissions. A GHOSTBRANCH_HOME outside your profile, such as on another drive, may take that drive’s looser permissions instead. doctor warns about that, and gives an icacls line that makes the folder yours alone.

Security

Mode 0600 keeps other users on the machine out. It doesn’t keep out a program running as you, such as a coding agent: that can read everything in this folder, and your keychain too, unless its sandbox stops it. That’s why the token is the boundary, not these files.