{
  "markdown": "<div align=\"center\">\n\n<img src=\"docs/assets/icon.svg\" width=\"112\" alt=\"PromptBranch logo\" title=\"PromptBranch\">\n\n# PromptBranch\n\n**A local-first prompt library and version-control system for AI prompts.**\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-3178C6)](LICENSE)\n\n[Features](#features) · [Install](#installation) · [Docs](#documentation) · [GitHub](https://github.com/PromptBranch/promptbranch)\n\n</div>\n\n---\n\nPromptBranch is a simple, local-first place to create, organize, test, and improve\nyour AI prompts. Keep prompts on your own computer, track their changes over time,\nrun them with different AI models, and connect your favorite AI tools. You stay in\ncontrol of your data and approve changes before they are saved.\n\n> [!WARNING]\n> **Work in progress.** PromptBranch is actively evolving. You may encounter bugs or\n> incomplete behavior, and parts of this documentation may be inaccurate or unfinished.\n> Please [report non-security issues](https://github.com/PromptBranch/promptbranch/issues).\n> Report security concerns privately through the [security policy](.github/SECURITY.md).\n\n## Features\n\n### Build a prompt library\n\n- 📚 **Organize prompts** with tags, collections, starring, filters, full-text\n  search (⌘K), History and Notes, JSON import/export, and automatic local backups.\n- 🌿 **Track versions** with branches, sequential version history, change notes,\n  diffs, and duplicate-as-variation workflows.\n- 🧪 **Evaluate results** with four-dimension ratings, a Results run log,\n  side-by-side comparison, an LLM judge, and an evaluation summary.\n\n### Run with AI and agents\n\n- ⚡ **Run against multiple models** using a [models.dev](https://models.dev)-backed\n  catalog for OpenAI, Anthropic, Google, and OpenAI-compatible endpoints. Run up to\n  six models concurrently with encrypted API keys and token/cost tracking.\n- 🤖 **Work with agents** through a CLI and MCP server over the same library. Agents\n  can report runs and notes or propose variations; humans review and approve them.\n\n### Share and sync on your terms\n\n- 🔗 **Share immutable snapshots** behind unguessable URLs, with pre-publish secret\n  scanning, import deep links, revocable delete tokens, and a dedicated Shares view.\n- 🔄 **Sync directly between your devices** on the local network. Pair with a short\n  verified code; changes are stored locally first and catch up automatically when\n  devices can reach one another.\n\n## Installation\n\nPromptBranch desktop is available for macOS, Windows, and Linux. Download an\ninstaller for your operating system from\n[GitHub Releases](https://github.com/PromptBranch/promptbranch/releases).\n\nThe CLI and MCP server are cross-platform too. See the\n[installation guide](docs/getting-started/installation.md) for setup, including\n[building from source](docs/getting-started/installation.md#build-from-source).\n\n## Where your data lives\n\nThe desktop app, CLI and MCP server all open the same database:\n\n| Platform | Path |\n|---|---|\n| macOS | `~/Library/Application Support/PromptBranch/library.db` |\n| Linux | `$XDG_CONFIG_HOME/promptbranch/library.db` |\n| Windows | `%APPDATA%\\PromptBranch\\library.db` |\n\nSet `PROMPTBRANCH_DB=/path/to.db` to point any entry point at a different\nlibrary (for example, a separate personal or test library).\nIf you used a pre-release build (named *PromptBuilder* or *PromptHub*), the\napp copies your existing library into the new location on first launch and\nleaves the original untouched.\n\nIt is safe to run the CLI or MCP server while the desktop app is open —\nthey share the database file. The app picks up new runs, notes, ratings and\nsuggestions when you focus the window.\n\n## Agent integration\n\nAI coding agents interact with your library through two thin adapters — the\nCLI and the MCP server — with the same semantics as the app UI. The rule is\n**agents propose, humans approve**: agents can read prompts, report runs and\nnotes, and *suggest* variations, but a suggested variation is created as a\n**pending** version that is invisible to search and listings and cannot become\ncurrent until a human approves it in the app's **Suggestions** view (left\nrail, with a pending-count badge; approve optionally sets it as current,\nreject keeps it permanently inactive).\n\nOnboarding is copy-paste: open Settings → *Agent integration* for the resolved\nDB path and a ready-to-paste MCP client config. The npm package also includes\nan optional skill file that teaches coding agents the fetch → report → suggest\nworkflow.\n\n### MCP server\n\n`@promptbranch/mcp` is available from npm. Point any stdio-capable MCP client\nat it with this configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"promptbranch\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@promptbranch/mcp@latest\"]\n    }\n  }\n}\n```\n\nTools: `get_prompt`, `search_prompts`, `list_prompts`, `report_run`,\n`add_note`, `suggest_variation`. Prompts are referenced by title (exact, then\ncase-insensitive, then unique substring — ambiguous matches return the close\ncandidates) or by id. `suggest_variation` returns a pending suggestion; tell\nyour human to open the Suggestions view to review it.\n\n### CLI\n\nThe CLI provides the same surface for shell pipelines. Run the public package\nwithout a global install as `npx -y @promptbranch/cli@latest`, or install it\nglobally with `npm install -g @promptbranch/cli@latest` to use the shorter\n`promptbranch` command. All commands accept `--json` for machine-readable\noutput:\n\n```sh\npromptbranch list --tag security\npromptbranch get \"security-audit\" > /tmp/prompt.md\npromptbranch search \"sql injection\"\npromptbranch report-run --prompt \"security-audit\" --tool kimi-cli --model k2 --outcome 4 --summary \"found 2 issues\"\npromptbranch add-note --prompt \"security-audit\" --body \"works well on small diffs\"\npromptbranch suggest --prompt \"security-audit\" --file improved.md --rationale \"tighter scope\"\npromptbranch suggestions   # pending review queue\npromptbranch db-path       # prints the resolved database path\n```\n\nSharing is human-only — `publish` and `import` exist only here and in the\ndesktop app; there is intentionally no MCP tool for pulling internet content\ninto the library.\n\n## AI providers\n\nPromptBranch can run prompts against real models and use AI to draft or improve\nprompts. Supported providers: **OpenAI**, **Anthropic**, **Google**, and any\n**OpenAI-compatible** endpoint (Ollama, LM Studio, …) via a custom base URL.\n\nSetup is one step: Settings → AI Providers → **Connect a provider** → paste the\nAPI key (encrypted with your OS keychain via Electron `safeStorage`; keys are\ndecrypted only inside the app at execution time). The connection is tested\nautomatically as part of connecting, and the model catalog refreshes in the\nbackground. If `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or\n`GOOGLE_GENERATIVE_AI_API_KEY` is set in the environment, PromptBranch offers\na one-click **Use environment key** connect for that provider.\n\nOnce connected, every catalog model of the provider is immediately usable —\nthere is no model-selection step in Settings. Models are picked from the\nsearchable model picker next to the Run button (filter as you type, grouped by\nprovider, with context-window/pricing hints and per-prompt recents). Individual\nmodels can be hidden from the picker's hover action; everything else just\nworks. OpenAI-compatible endpoints have no catalog, so their model ids are\ndeclared inline on the provider's settings row.\n\nThe model catalog comes from [models.dev](https://models.dev) and is cached\nlocally. Browsing and editing stay offline; catalog refreshes, model runs, and\nsharing use the network. A failed catalog refresh keeps\nserving the stale cache.\n\nEach Run executes the prompt (after `{{variable}}` substitution) against up to\n6 models concurrently and records one entry per model — provider, model,\nstatus, output or error, latency, token usage and estimated USD cost from\ncatalog pricing — grouped together for the compare view.\n\n## Sharing\n\nSnapshots are immutable and live behind unguessable `/p/<id>` URLs on the\nofficial portal, <https://promptbranch.app>.\n\n- **Publishing** happens from the Share dialog on the prompt toolbar (scope\n  choice, pre-publish secret scan, exact-payload preview). Delete tokens are\n  stored locally so shares can be revoked later from the **Shares view** in\n  the left rail (search, status filtering, copy link, revoke, and remove\n  revoked entries).\n- **Importing** works via `promptbranch://import?url=` deep links or\n  `promptbranch import`; the snapshot becomes a new local prompt with its\n  tags and a provenance note. A shared history remains viewable on the portal;\n  it is not recreated as a local version chain.\n\n## Multi-device sync\n\nSync your library across your own computers, directly, with **no server and\nno account**: devices discover each other on the local network via mDNS,\nauthenticate with a one-time pairing code, and exchange incremental\nrecord-level changes over mutually-pinned TLS. Enable it in\n**Settings → Sync**; a status line in the left-rail footer shows\n*Synced / Syncing / Waiting for devices* at a glance.\n\n- **How it works**: every change (from the app, the CLI or the MCP server —\n  they share the database file) is captured into a local op log with\n  logical-clock revisions; peers exchange the ops they're missing and merge\n  them deterministically. Append-only records (versions, notes, ratings,\n  runs) union by id; small mutable fields resolve last-writer-wins; same-name\n  tags/collections/branches merge into one row. Concurrent edits to a prompt\n  simply produce concurrent versions in its history.\n- **Trust**: each device has a self-signed certificate; the 8-character\n  pairing code is derived from the accepting device's certificate\n  fingerprint, so a man-in-the-middle on the network produces a mismatching\n  code. Forgetting a device unpins it permanently. API keys never leave a\n  device, and settings are deliberately device-local. Share records do sync\n  (delete tokens included), so shares can be managed and revoked from any\n  paired machine.\n- **Reach**: sync happens when devices are on the same network (or a VPN —\n  pair by address in Settings → Sync → *Add a device*). Changes wait while\n  devices are apart; nothing is ever \"pending upload\", because changes are\n  durable the moment they're written.\n- **macOS note**: the first sync session triggers the system's Local Network\n  permission prompt — allow it, or pairing and discovery won't see peers.\n\n## Documentation\n\nBrowse the full documentation in [`docs/`](docs/SUMMARY.md).\n\n| Start here | Go deeper |\n| --- | --- |\n| [Overview & Philosophy](docs/getting-started/overview.md) | [Prompt Management](docs/features/prompt-management.md) |\n| [Installation](docs/getting-started/installation.md) | [Search & Organization](docs/features/search-and-organization.md) |\n| [Quickstart](docs/getting-started/quickstart.md) | [Library Data & Backups](docs/features/library-data-and-backups.md) |\n| [Core Concepts](docs/getting-started/core-concepts.md) | [Multi-Model Execution](docs/features/ai-execution-and-models.md) |\n| [MCP Server](docs/integrations/mcp-server.md) | [LLM Judge](docs/features/llm-judge-and-evaluations.md) |\n| [CLI](docs/integrations/cli.md) | [AI Assist](docs/features/ai-assist.md) |\n| [AI Providers](docs/integrations/ai-providers.md) | [Peer-to-Peer Sync](docs/sync/peer-to-peer-sync.md) |\n| [Link Sharing](docs/sharing/link-sharing-and-portal.md) | [Configuration & Environment](docs/reference/configuration-and-env.md) |\n\nWant to contribute? Read [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nPromptBranch is released under the [MIT License](LICENSE). The third-party\nsoftware bundled with the app is listed in\n[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and is also viewable\nin-app via **About → Open Source Licenses**.\n",
  "bytes": 11797,
  "sha": "ac90851c3fc4b1dc90149c895967cdad49bd3ef498fa5919a3d46cdcefdf7582",
  "repo_slug": "promptbranch/promptbranch",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_promptbranch_promptbranch_ac081a2f/readme"
}