# PromptBranch
**A local-first prompt library and version-control system for AI prompts.**
[](LICENSE)
[Features](#features) ยท [Install](#installation) ยท [Docs](#documentation) ยท [GitHub](https://github.com/PromptBranch/promptbranch)
---
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 parts of this documentation may be inaccurate or unfinished.
> Please [report non-security issues](https://github.com/PromptBranch/promptbranch/issues).
> Report security concerns privately through the [security policy](https://github.com/PromptBranch/promptbranch/blob/HEAD/.github/SECURITY.md).
## 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.
- ๐ฟ **Track versions** with branches, immutable revision IDs, stable history
labels, change notes, diffs, and duplicate-as-variation workflows.
- ๐งช **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](https://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, with pre-publish secret
scanning, import deep links, revocable delete tokens, 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](https://github.com/PromptBranch/promptbranch/releases).
The CLI and MCP server are cross-platform too. See the
[installation guide](https://github.com/PromptBranch/promptbranch/blob/HEAD/docs/getting-started/installation.md) for setup, including
[building from source](https://github.com/PromptBranch/promptbranch/blob/HEAD/docs/getting-started/installation.md#build-from-source).
## Where your data lives
The desktop app, CLI and MCP server all open the same database:
| Platform | Path |
|---|---|
| macOS | `~/Library/Application Support/PromptBranch/library.db` |
| Linux | `$XDG_CONFIG_HOME/promptbranch/library.db` |
| Windows | `%APPDATA%\PromptBranch\library.db` |
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:
```json
{
"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:
```sh
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 (encrypted with your OS keychain via Electron `safeStorage`; keys are
decrypted only inside the app at execution time). 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](https://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/