Install PlanBefore
From download to a running Node in seven steps. You don’t need the source code — only git and rg (ripgrep).
Requirements
- macOS 12 or later (Apple Silicon or Intel), a 64-bit Linux distribution (x86_64 or ARM64), or Windows 10/11 (x64 or ARM64).
gitandrg(ripgrep) on yourPATH. PlanBefore uses them to read Git history and search code.- A PlanBefore account with a passkey. Accounts are currently invitation-only.
# macOS (Homebrew)
brew install git ripgrep# Debian / Ubuntu
sudo apt install git ripgrep# Fedora
sudo dnf install git ripgrep# Windows (PowerShell)
winget install --id Git.Git -e
winget install --id BurntSushi.ripgrep.MSVC -eInstall
Run the installer for your system:
macOS / Linux (Terminal)
curl -fsSL https://planbefore.kvnlabs.xyz/install.sh | shWindows (PowerShell)
irm https://planbefore.kvnlabs.xyz/install.ps1 | iexThe installer:
- detects your operating system and CPU architecture;
- finds the latest stable release on GitHub Releases and downloads it over HTTPS;
- verifies its SHA-256 checksum against
checksums.txtand stops if it doesn’t match; - installs
pbnodein~/.local/bin(macOS, Linux) or%LOCALAPPDATA%\Programs\RepoFlow(Windows), with no administrator rights; - runs
pbnode versionand checks thatgitandrgare installed.
It never asks for credentials and never signs you in. On macOS and Linux it doesn’t edit your shell files: if
~/.local/binisn’t on yourPATH, it tells you what to add. On Windows it adds its folder to your userPATHand says so (setREPOFLOW_NO_MODIFY_PATH=1to skip that).Options, and reading the script first
Read the scripts before running them: install.sh —install.ps1. Pin a version or change the destination with environment variables(replace
vX.Y.Zwith a tag from Releases):curl -fsSL https://planbefore.kvnlabs.xyz/install.sh | REPOFLOW_VERSION=vX.Y.Z REPOFLOW_INSTALL_DIR="$HOME/bin" sh$env:REPOFLOW_VERSION = 'vX.Y.Z'; irm https://planbefore.kvnlabs.xyz/install.ps1 | iexVersions published before the CLI was renamed from
repoflowtopbnodedo not includepbnode: the installer stops with a clear message and installs nothing. Their original files remain available under Releases.Prefer not to pipe a script into your shell? Follow the manual installation.
Verify
Open a new terminal and check the installed version:
pbnode versionIt prints the version, commit, build date and platform, for example
PlanBefore Node vX.Y.ZandPlatform: darwin/arm64.Initialize
pbnode initCreates the local configuration: a name for this Node (your hostname) and the address of the PlanBefore Hub. Nothing is shared yet. The file lives in
~/Library/Application Support/RepoFlow(macOS),~/.config/repoflow(Linux) or%AppData%\RepoFlow(Windows).Authenticate the Node
pbnode loginThe terminal shows a link and a one-time code:
Open: https://mcp.kvnlabs.xyz/device Code: ABCD-EFGHOpen the PlanBefore Hub link, sign in with your PlanBefore Auth passkey, check that the code matches and approve the Node in the Hub. The terminal then confirms
✓ Node authorized. You can approve it from any device that has your passkey: if the Node runs on a server or a virtual machine without one, open the link on your computer or phone and type the code there.You never type a password or token into the CLI. The Node’s private key is generated on your machine and stored in your system’s credential store (Keychain, Credential Manager or Secret Service). You can rename or revoke the Node from your account.
Connect a project
cd ~/Projects/my-project pbnode expose .- Only projects you expose explicitly are available to authorized assistants.
- PlanBefore never exposes your whole filesystem, and it excludes files such as
.env, private keys and credentials by default. - List your projects with
pbnode projects; stop sharing one withpbnode revoke <project-id>.
Do you also want planning?
You can authorize a folder inside the project to keep Functional Requirements, tasks, and reviews:
pbnode expose . --spec-root specsYou don’t need this capability to use PlanBefore only as an analysis tool.
Enable task execution
If you want PlanBefore to implement the tasks you approve, install Codex on your machine. Nothing else needs configuring: if
codexis on yourPATH, execution is available. Only if Codex is not on yourPATH, set its path withexecutor.commandin the Node configuration.pbnode statusshows whether task execution is available. Codex works directly on your project on your machine; PlanBefore follows execution and returns the result to the assistant for review.Today, integrated execution uses Codex. PlanBefore will soon extend compatibility to Claude Code and other local development agents.
Start the Node
pbnode serve --backgroundThe Node connects out to the PlanBefore Hub — no open ports, no VPN — and keeps running after you close the terminal. Stop it with
pbnode stop. After a reboot, run the command again.Check status
pbnode statusShows this Node, the Hub it connects to, how many projects are enabled and whether the background service is running.
Connect your AI assistant
Add PlanBefore to ChatGPT, Claude, Gemini, or another compatible assistant and authorize access from your PlanBefore account.
- MCP server URL
https://mcp.kvnlabs.xyz/repoflow- Authentication
- OAuth
- Authorization server
https://auth.kvnlabs.xyz(discovered automatically)
https://mcp.kvnlabs.xyz/repoflowAfter connecting it, ask the assistant to list your projects or analyze one of them. If you configured a planning folder, you can also use PlanBefore to create Functional Requirements and tasks.
Manual installation
No script involved. The examples use Linux x86_64 — replace linux_amd64 with your platform.
- Download the archive for your platform and
checksums.txtfromdownload page or GitHub Releases. - Verify the checksum — the output must match the line for your file in
checksums.txt:# Linux sha256sum --ignore-missing -c checksums.txt # macOS shasum -a 256 pbnode_*_darwin_arm64.tar.gz# Windows (PowerShell) Get-FileHash .\pbnode_*_windows_amd64.zip -Algorithm SHA256 - Extract:
tar -xzf pbnode_*_linux_amd64.tar.gz# Windows (PowerShell) Expand-Archive .\pbnode_*_windows_amd64.zip -DestinationPath . - Move it to a folder on your
PATH:mkdir -p ~/.local/bin mv pbnode ~/.local/bin/On Windows, move
pbnode.exeto%LOCALAPPDATA%\Programs\RepoFlowand add that folder to your userPathin Settings → System → About → Advanced system settings → Environment Variables. - Check it runs:
pbnode version, then continue with step 3.
Unsigned binaries. PlanBefore builds are not code-signed or notarized yet. If macOS blocks a file you downloaded with a browser, verify the checksum and run xattr -d com.apple.quarantine ~/.local/bin/pbnode. On Windows, SmartScreen may warn about an unrecognized app: choose More info → Run anyway, or run Unblock-File .\pbnode.exe.
Troubleshooting
pbnode: command not found
The install folder isn’t on your PATH. For zsh (bash: use ~/.bashrc), then open a new terminal:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcUpdating
Run the install command again. If the Node was running, restart it with pbnode stop and pbnode serve --background. Your configuration and Node identity are kept.
Your AI assistant can’t see a project
Check that pbnode status shows the service running and the project enabled, and that you authorized the assistant with the same PlanBefore account that authorized the Node.
Still stuck? See Support.