PromptBranch

PromptBranch

A local-first prompt library and version-control system for AI prompts.

Features · Install · Docs · GitHub

---

PromptBranch is a simple, local-first place to create, organize, test, and improve your AI prompts. Keep prompts on your own computer, track their changes over time, run them with different AI models, and connect your favorite AI tools. You stay in control of your data and approve changes before they are saved.

[!WARNING]

Work in progress. PromptBranch is actively evolving. You may encounter bugs or

incomplete behavior, and features may change as development continues.

Please report non-security issues.

Report security concerns privately through the security policy.

Features

Build a prompt library

• 📚 Organize prompts with tags, collections, starring, filters, full-text search (⌘K), History and Notes, JSON import/export, and automatic local backups.
• 📋 Copy prompts from another app while PromptBranch is running with the optional Quick access palette, a configurable global shortcut, variable inputs, and an exact text preview.
• 🌿 Track versions with branches, stable version IDs, amend-in-place and save-as-new actions, history labels, change notes, diffs, and variations.
• 🧪 Evaluate results with four-dimension ratings, a Results run log, side-by-side comparison, an LLM judge, and an evaluation summary.

Run with AI and agents

• ⚡ Run against multiple models using a models.dev-backed catalog for OpenAI, Anthropic, Google, and OpenAI-compatible endpoints. Run up to six models concurrently with encrypted API keys and token/cost tracking.
• 🤖 Work with agents through a CLI and MCP server over the same library. Agents can report runs and notes or propose variations; humans review and approve them.

Share and sync on your terms

• 🔗 Share immutable snapshots behind unguessable URLs, embed active shares on websites, or review and import public Markdown URLs. Shares include pre-publish secret scanning, revocable links, and a dedicated Shares view.
• 🔄 Sync directly between your devices on the local network. Pair with a short verified code; changes are stored locally first and catch up automatically when devices can reach one another.

Installation

PromptBranch desktop is available for macOS, Windows, and Linux. Download an installer for your operating system from GitHub Releases.

The CLI and MCP server are cross-platform too. See the installation guide for setup, including building from source.

Where your data lives

The desktop app, CLI and MCP server all open the same database:

Set PROMPTBRANCH_DB=/path/to.db to point any entry point at a different library (for example, a separate personal or test library). If you used a pre-release build (named *PromptBuilder* or *PromptHub*), the app copies your existing library into the new location on first launch and leaves the original untouched.

It is safe to run the CLI or MCP server while the desktop app is open — they share the database file. The app picks up new runs, notes, ratings and suggestions when you focus the window.

Agent integration

AI coding agents interact with your library through two thin adapters — the CLI and the MCP server — with the same semantics as the app UI. The rule is agents propose, humans approve: agents can read prompts, report runs and notes, and *suggest* variations, but a suggested variation is created as a pending version that is invisible to search and listings and cannot become current until a human approves it in the app's Suggestions view (left rail, with a pending-count badge; approve optionally sets it as current, reject keeps it permanently inactive).

Onboarding is copy-paste: open Settings → *Agent integration* for the resolved DB path and a ready-to-paste MCP client config. The npm package also includes an optional skill file that teaches coding agents the fetch → report → suggest workflow.

MCP server

@promptbranch/mcp is available from npm. Point any stdio-capable MCP client at it with this configuration:

{

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

Tools: get_prompt, search_prompts, list_prompts, report_run, add_note, suggest_variation. Prompts are referenced by title (exact, then case-insensitive, then unique substring — ambiguous matches return the close candidates) or by id. suggest_variation returns a pending suggestion; tell your human to open the Suggestions view to review it.

CLI

The CLI provides the same surface for shell pipelines. Run the public package without a global install as npx -y @promptbranch/cli@latest, or install it globally with npm install -g @promptbranch/cli@latest to use the shorter promptbranch command. All commands accept --json for machine-readable output:

promptbranch list --tag security

promptbranch get "security-audit" > /tmp/prompt.md promptbranch search "sql injection" promptbranch report-run --prompt "security-audit" --tool kimi-cli --model k2 --outcome 4 --summary "found 2 issues" promptbranch add-note --prompt "security-audit" --body "works well on small diffs" promptbranch suggest --prompt "security-audit" --file improved.md --rationale "tighter scope" promptbranch suggestions # pending review queue promptbranch db-path # prints the resolved database path

Sharing is human-only — publish and import exist only here and in the desktop app; there is intentionally no MCP tool for pulling internet content into the library.

AI providers

PromptBranch can run prompts against real models and use AI to draft or improve prompts. Supported providers: OpenAI, Anthropic, Google, and any OpenAI-compatible endpoint (Ollama, LM Studio, …) via a custom base URL.

Setup is one step: Settings → AI Providers → Connect a provider → paste the API key. PromptBranch encrypts it using your operating system's secure credential storage and only decrypts it when needed for a model request. The connection is tested automatically as part of connecting, and the model catalog refreshes in the background. If OPENAI_API_KEY, ANTHROPIC_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY is set in the environment, PromptBranch offers a one-click Use environment key connect for that provider.

Once connected, every catalog model of the provider is immediately usable — there is no model-selection step in Settings. Models are picked from the searchable model picker next to the Run button (filter as you type, grouped by provider, with context-window/pricing hints and per-prompt recents). Individual models can be hidden from the picker's hover action; everything else just works. OpenAI-compatible endpoints have no catalog, so their model ids are declared inline on the provider's settings row.

The model catalog comes from models.dev and is cached locally. Browsing and editing stay offline; catalog refreshes, model runs, and sharing use the network. A failed catalog refresh keeps serving the stale cache.

Each Run executes the prompt (after {{variable}} substitution) against up to 6 models concurrently and records one entry per model — provider, model, status, output or error, latency, token usage and estimated USD cost from catalog pricing — grouped together for the compare view.

Sharing

Snapshots are immutable and live behind unguessable /p/ URLs on the official portal, https://promptbranch.app.

• Publishing happens from the Share dialog on the prompt toolbar (scope choice, pre-publish secret scan, exact-payload preview). Delete tokens are stored locally so shares can be revoked later from the Shares view in the left rail (search, status filtering, copy link, revoke, and remove revoked entries).
• Importing works via promptbranch://import?url= deep links or promptbranch import; the snapshot becomes a new local prompt with its tags and a provenance note. A shared history remains viewable on the portal; it is not recreated as a local version chain.
• Website embeds use copyable HTML for active shares. Choose Auto, Light, or Dark when copying; Auto follows the visitor's system appearance. The prompt appears in Shadow DOM without an iframe, with its title and an Open in PromptBranch button. The portal script runs on the host page, so use embed code only from a portal you trust. See the sharing guide for the HTML snippets and CSP requirements.
• Public Markdown links use promptbranch://import-markdown?url=. The desktop app fetches only after the user chooses Fetch Markdown, then previews the content before creating a new local prompt. The source must be reachable over public HTTPS. The sharing guide includes an HTML button example that website owners can copy and customize.

Multi-device sync

Sync your library across your own computers, directly, with no server and no account: devices discover each other on the local network via mDNS, authenticate with a one-time pairing code, and exchange incremental record-level changes over mutually-pinned TLS. Enable it in Settings → Sync; a status line in the left-rail footer shows *Synced / Syncing / Waiting for devices* at a glance.

• How it works: every change (from the app, the CLI or the MCP server — they share the database file) is captured into a local op log with logical-clock revisions; peers exchange the ops they're missing and merge them deterministically. Independently created records union by id; changes to the same record resolve last-writer-wins; same-name tags/collections/branches merge into one row. Concurrent edits to a prompt produce both versions when saved separately, while concurrent amendments to the same version resolve deterministically.
• Trust: each device has a self-signed certificate; the 8-character pairing code is derived from the accepting device's certificate fingerprint, so a man-in-the-middle on the network produces a mismatching code. Forgetting a device unpins it permanently. API keys never leave a device, and settings are deliberately device-local. Share records do sync (delete tokens included), so shares can be managed and revoked from any paired machine.
• Reach: sync happens when devices are on the same network (or a VPN — pair by address in Settings → Sync → *Add a device*). Changes wait while devices are apart; nothing is ever "pending upload", because changes are durable the moment they're written.
• macOS note: the first sync session triggers the system's Local Network permission prompt — allow it, or pairing and discovery won't see peers.

Documentation

Browse the full documentation in docs/.

| Installation | [Search, Organization & Quick access](docs/features/search-and-org