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).
  • 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://mcp.kvnlabs.xyz/device
    
    Code:
    ABCD-EFGH

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

  5. 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 with pbnode 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 specs

    You 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 codex is on your PATH, execution is available. Only if Codex is not on your PATH, set its path with executor.command in the Node configuration. pbnode status shows 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.

  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 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/repoflow

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

  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.

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.