Installation & Setup

PromptBranch can be used as a full desktop application with a visual UI, as a standalone command-line interface (CLI) for shell pipelines, or as an MCP server for AI coding agents.

---

Desktop Application

Installers will be distributed through the public release channel for macOS, Windows, and Linux. No public desktop release or download page has been published yet.

macOS

PromptBranch provides native universal builds for Apple Silicon (M1/M2/M3/M4) and Intel Macs:

• Apple Silicon (ARM64): PromptBranch-<version>-arm64.dmg
• Intel (x64): PromptBranch-<version>-x64.dmg
• Portable Zip: PromptBranch-<version>-arm64.zip / PromptBranch-<version>-x64.zip

Local Network Permission Prompt: On macOS, the first time you enable Multi-Device Sync, macOS may display a system dialog asking for Local Network access. Select Allow so local discovery and peer-to-peer sync can reach your other devices.

Windows

• Installer: PromptBranch-Setup-<version>.exe
• Architecture: 64-bit (x64)

The Windows installer uses NSIS in per-user mode (%LOCALAPPDATA%\Programs\PromptBranch). It does not require administrator privileges to install or update.

If Windows SmartScreen displays a warning on an unsigned build, click More info and select Run anyway.

Linux

• AppImage: PromptBranch-<version>.AppImage
• Debian / Ubuntu: PromptBranch-<version>.deb

AppImage Prerequisites

AppImage binaries on modern Linux distributions (such as Ubuntu 24.04+, Debian 12+, Fedora 40+) require FUSE 2 or 3:

# Ubuntu / Debian
sudo apt install libfuse2

# Fedora / RHEL
sudo dnf install fuse-libs

To run the AppImage:

chmod +x PromptBranch-*.AppImage
./PromptBranch-*.AppImage

---

Command-Line Interface (CLI)

No public CLI package has been published yet. Once @promptbranch/cli is available on npm, run it directly without a global installation:

npx -y @promptbranch/cli db-path

For a persistent promptbranch command, install it globally:

npm install --global @promptbranch/cli

Once set up, verify the installation by printing the resolved database path:

promptbranch db-path

---

Model Context Protocol (MCP) Server

PromptBranch provides a stdio MCP server that enables AI assistants (such as Claude Desktop, Cursor, Windsurf, or Cline) to read prompts, log run metrics, and suggest variations.

No public MCP package has been published yet. The configuration below becomes usable when @promptbranch/mcp is available on npm.

Claude Desktop Configuration

Add the following configuration to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "promptbranch": {
      "command": "npx",
      "args": ["-y", "@promptbranch/mcp"]
    }
  }
}

Cursor / Windsurf Configuration

In Cursor or Windsurf MCP settings, add a stdio MCP server:

• Name: promptbranch
• Command: npx
• Args: ["-y", "@promptbranch/mcp"]

The desktop app prints this configuration ready-to-paste in Settings → Agent integration.

---

Database Location & Environment Variables

All three entry points (Desktop App, CLI, and MCP server) open the exact same SQLite database file by default.

Default Database Paths by OS

Operating System	Default Path
macOS	~/Library/Application Support/PromptBranch/library.db
Linux	$XDG_CONFIG_HOME/promptbranch/library.db (or ~/.config/promptbranch/library.db)
Windows	%APPDATA%\PromptBranch\library.db

Overriding the Database Path (PROMPTBRANCH_DB)

You can point PromptBranch to an alternate database file (for example, a separate personal or test library) by setting the PROMPTBRANCH_DB environment variable:

export PROMPTBRANCH_DB="/path/to/my-custom-library.db"
promptbranch list

For backwards compatibility, PromptBranch also recognizes the legacy environment variables PROMPTHUB_DB and PROMPTBUILDER_DB as fallbacks if PROMPTBRANCH_DB is not set.

Automatic Migration from Legacy Apps

If you previously used pre-release versions (named PromptBuilder or PromptHub), PromptBranch automatically migrates your existing database on first launch:

1. It locates the legacy library.db along with its WAL/SHM sidecar files.
2. It safely copies them into the new PromptBranch directory.
3. The original legacy database files are left completely untouched as a backup.