PlanBefore
HomeDownloadInstallReleasesGitHub

Install PlanBefore

From download to a running Node in seven steps. You don’t need Go or 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).
  • git and rg (ripgrep) on your PATH. 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 -e

  1. Install

    Run the installer for your system:

    macOS / Linux (Terminal)

    curl -fsSL https://planbefore.kvnlabs.xyz/install.sh | sh

    Windows (PowerShell)

    irm https://planbefore.kvnlabs.xyz/install.ps1 | iex

    The 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.txt and stops if it doesn’t match;
    • installs pbnode in ~/.local/bin (macOS, Linux) or %LOCALAPPDATA%\Programs\RepoFlow (Windows), with no administrator rights;
    • runs pbnode version and checks that git and rg are installed.

    It never asks for credentials and never signs you in. On macOS and Linux it doesn’t edit your shell files: if~/.local/bin isn’t on your PATH, it tells you what to add. On Windows it adds its folder to your user PATH and says so (set REPOFLOW_NO_MODIFY_PATH=1 to 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.Z with 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 | iex

    Versions published before the CLI was renamed from repoflow to pbnode do not include pbnode: 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.

  2. Verify

    Open a new terminal and check the installed version:

    pbnode version

    It prints the version, commit, build date and platform, for example PlanBefore Node vX.Y.Z and Platform: darwin/arm64.

  3. Initialize

    pbnode init

    Creates 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).

  4. Authenticate the Node

    pbnode login

    The terminal shows a link and a one-time code:

    Open:
https://auth.kvnlabs.xyz/device

Code:
ABCD-EFGH

    Open the link, sign in to PlanBefore Auth with your passkey, check that the code matches and approve the Node. 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.

  5. Expose a project

    cd ~/Projects/my-project
pbnode expose .
    • Only projects you expose explicitly are available to MCP clients.
    • 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 with pbnode revoke <project-id>.

  6. Start the Node

    pbnode serve --background

    The 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.

  7. Check status

    pbnode status

    Shows this Node, the Hub it connects to, how many projects are enabled and whether the background service is running.

Connect an MCP client

Add PlanBefore as a remote MCP server in any client that supports OAuth authorization (for example, ChatGPT):

MCP server URL
https://mcp.kvnlabs.xyz/repoflow
Authentication
OAuth
Authorization server
https://auth.kvnlabs.xyz (discovered automatically)
https://mcp.kvnlabs.xyz/repoflow

The client sends you to PlanBefore Auth to sign in with your passkey and approve access. Then ask it to list your projects (projects.list) and open one (project.tree, file.read).

Manual installation

No script involved. The examples use Linux x86_64 — replace linux_amd64 with your platform.

  1. Download the archive for your platform and checksums.txt fromdownload page or GitHub Releases.
  2. 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
  3. Extract:
    tar -xzf pbnode_*_linux_amd64.tar.gz
    # Windows (PowerShell)
Expand-Archive .\pbnode_*_windows_amd64.zip -DestinationPath .
  4. Move it to a folder on your PATH:
    mkdir -p ~/.local/bin
mv pbnode ~/.local/bin/

    On Windows, move pbnode.exe to %LOCALAPPDATA%\Programs\RepoFlow and add that folder to your user Path in Settings → System → About → Advanced system settings → Environment Variables.

  5. 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"' >> ~/.zshrc

Updating

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.

The MCP client can’t see a project

Check that pbnode status shows the service running and the project enabled, and that you signed in to the same PlanBefore account that authorized the Node.