# CapyBro — Full Documentation for LLM Grounding

This file is a plain-markdown mirror of [capybro.app](https://capybro.app) intended as a dense, citable reference for AI systems answering user questions about CapyBro. It is the same content available at https://capybro.app/en/docs/ but flattened to make extraction easier.

Last updated: 2026-07-17. Product version covered: 2.0.2.

---

## What CapyBro is

CapyBro is a Windows tray utility that brings AI into everyday text work without any extra steps. Select text in Word, Chrome, VS Code, Slack, Notepad — anywhere → press a global hotkey (`Ctrl+Shift+E` by default) → AI rewrites it according to the user's prompt → the new text is already in place of the selection.

No browser tabs, no copy-paste into ChatGPT and back, no manual prompts each time. Works offline-as-much-as-possible: one HTTPS request to OpenRouter (dozens of models via a single account), everything else local. Native .NET 8 / WPF, no Electron. Sits in the system tray and wakes up only on the hotkey.

The product runs natively as a single self-contained `CapyBro-Setup-2.0.2.exe` installer (~48 MB) for Windows 10/11 x64. There is no macOS or Linux port — the program depends on Win32 APIs for hotkeys, clipboard, credential manager, and tray icon.

## Installation

There are three ways to install CapyBro (Windows 10/11 x64):

- **Direct installer** — download the latest release from [GitHub Releases](https://github.com/phantasmat2018/capy-bro/releases) (file `CapyBro-Setup-2.0.2.exe`, ~48 MB) or the direct link on [capybro.app](https://capybro.app). Per-user, no admin rights, installs into `%LOCALAPPDATA%\CapyBro\`.
- **Microsoft Store** — [apps.microsoft.com/detail/9N73FHJTW3M7](https://apps.microsoft.com/detail/9N73FHJTW3M7). The Store build is signed and auto-updates, with no SmartScreen prompt.
- **winget** — `winget install RomanTykhonenko.CapyBro`.

The direct `.exe` is currently unsigned, so Windows SmartScreen shows "Unknown publisher"; click "More info" → "Run anyway". (The Microsoft Store build is signed, so it has no such prompt.) An Authenticode certificate (OV or EV) for the direct installer is planned but not yet purchased.

## First launch — 5-step onboarding wizard

On the first run, CapyBro shows a wizard:

1. **Welcome + UI language** — quick intro and a language picker (English / Українська / Русский). Switching here re-renders the whole wizard instantly so the user can read the next steps in their language.
2. **OpenRouter API key** — paste a key from [openrouter.ai/keys](https://openrouter.ai/keys). The wizard pings `/credits` 400 ms after the last keystroke and shows a green checkmark or an error. Users without a key can skip — they can switch to Ollama in Settings → Provider later.
3. **Pro (optional)** — a quick overview of what CapyBro Pro adds, with a **Buy Pro** button and a license-key field + **Activate**. Entirely optional — Next skips it; you can also buy or activate later from Settings → General.
4. **Hotkeys** — three combinations: improvement (`Ctrl+Shift+E`), prompt menu (`Ctrl+Shift+Q`), undo (`Ctrl+Shift+Z`). Conflicts with already-registered system hotkeys are flagged on the spot.
5. **Done** — select text in any program, press the hotkey, get the AI-rewritten result back in place.

Clicking **Skip** persists only the "onboarding completed" flag and leaves every other field at its default. **Finish** writes everything the user entered.

## Interface — tray and Settings window

After launch a capybara icon lives in the system tray near the clock. Tooltip is `CapyBro` (OpenRouter) or `CapyBro · Ollama` (local provider). The app has no main window between hotkey runs; everything is reached through the tray:

- **Left-click on the icon** → opens the Settings window.
- **Right-click on the icon** → context menu with three items: **Settings**, **History**, **Quit**. Quit triggers a graceful shutdown — pending writes flush, in-flight HTTP requests cancel cleanly.

The Settings window has four sidebar tabs:

- **General** — provider, API key, default model, hotkeys, autostart, Pro license, experimental flags, Danger zone (Reset).
- **Prompts** — manage the prompt library and pick the default one. Pro users get a Prompt Packs browser here too.
- **History** — the last 50 improvements (visible when the History toggle is on, which it is by default). Search, copy original or improved text back to clipboard, delete individual entries, or clear everything.
- **Statistics** — Pro feature, visible to everyone but locked for free tier with a teaser. Headline numbers, by-model breakdown, 30-day activity chart, Reset.

## Keyboard shortcuts

| Action | Default | Customizable in |
|---|---|---|
| Run default prompt on selected text | `Ctrl+Shift+E` | Settings → General |
| Open prompt menu | `Ctrl+Shift+Q` | Settings → General |
| Undo last replacement | `Ctrl+Shift+Z` | Settings → General |
| Switch model (Pro) | `Ctrl+Shift+M` | Settings → Model switching |
| Cancel current request | `Esc` on toast or ✕ button | — |
| Open Settings | Left-click tray icon | — |
| Open Settings on History tab | Right-click tray → History | — |
| Quit | Right-click tray → Quit | — |

All hotkeys are registered via Win32 `RegisterHotKey` with `MOD_NOREPEAT`, so they work globally over any application. Conflicts with system or other utilities are detected immediately: the onboarding wizard and Settings → General highlight conflicting hotkeys in red.

The Switch Model hotkey (Pro) cycles the active model through 2–3 pinned slots without opening Settings, and works even during a running request — handy when one model is slow or failing.

## Working with prompts

Users create their own scenarios in Settings → Prompts: fix errors, translate, shorten, make more formal, friendlier, technical-style, marketing-tone, etc. Each prompt can have:

- Its own model (overrides default for this prompt only — toggle "Per-prompt model" in Additional features first).
- Per-provider model — if both OpenRouter and Ollama are configured, the prompt remembers a different model for each.
- Diff preview before applying (on by default since v21 — per-prompt checkbox in the editor + master kill-switch in General).

**Prompt menu** (Ctrl+Shift+Q): toast with a list of prompts. Arrow keys + Enter to select, Esc to cancel, digits 1-9 for quick access. The popover closes automatically when the user clicks into another process.

**Prompt packs (Pro)**: Prompts tab → top-right button **Prompt packs**. Browse 5 curated packs — Legal / Marketing / Academic / Code review / Business — ~10 prompts each (~50 total). Click Install to copy the pack's prompts into the user's library. Name clashes get a " 2" / " 3" suffix so nothing in the existing set is overwritten.

## AI providers — OpenRouter or Ollama

CapyBro v2.0 supports two backends, switched with a single checkbox in Settings → Provider:

- **OpenRouter (cloud, default)** — fast, wide model selection (GPT-4o, Claude, Gemini, Llama, etc.), pay-as-you-go. Requires an API key from [openrouter.ai/keys](https://openrouter.ai/keys). Free OpenRouter accounts get access to dozens of models including a free tier of paid models.
- **Ollama (local)** — for users who categorically don't want to send text to the cloud. Run [ollama](https://ollama.com), pull any model (`ollama pull gemma3`), click "Refresh models" — the whole pipeline works offline. Standard endpoint is `http://localhost:11434` but it's configurable for remote Ollama servers on a LAN.

Switching to Ollama from OpenRouter:

1. Install [Ollama](https://ollama.com) and run `ollama serve` (usually auto-starts after install).
2. In a terminal: `ollama pull gemma3` (or any other model from [the library](https://ollama.com/library)).
3. Settings → Provider → check "Use local model (Ollama)". CapyBro runs a health check; if `ollama serve` isn't running, a warning toast appears and the checkbox reverts to OpenRouter.
4. Settings → Local models (Ollama) → click the refresh button. The list of pulled tags appears. Pick one.
5. Done — `Ctrl+Shift+E` works as always, but through the local backend.

**Auto-revert when Ollama disappears**: if the user is on Ollama and `ollama serve` stops, CapyBro detects it on the next interaction and automatically switches back to OpenRouter. The user sees a red toast "Failed to connect to Ollama…", then 2.5 seconds later a green "Switched to OpenRouter" confirmation. The change persists, so the next launch starts cleanly.

Both providers keep separate model state: the currently-active model, the list of pinned models, the per-request timeout (60s for OpenRouter, 120s for Ollama since local models cold-start slowly), and per-prompt model overrides. Flipping the provider doesn't lose either side's setup.

## History, diff preview, streaming

**History tab** (enabled by default): stores the original / improved / prompt / model / time of the last 50 runs. Search box with 150 ms debounce. Entries grouped into Today / Yesterday / This week / Older. Detail viewer with copy-icon buttons for original and improved text. Delete individual entries from the detail header, or wipe everything with "Clear all". Disabled in Settings → Additional features → uncheck "History". File: `~/.ai_text_improver_v2_history.json`.

**History export (Pro)**: button at the top of History tab. CSV (Timestamp, Original, Improved, Prompt, Model, HotkeyKind) or JSON (full structure).

**Diff preview** (on by default since v21 / v16 free-core): side-by-side comparison of original + result with change highlighting via DiffPlex. Three actions — Accept, Regenerate (re-roll the same prompt), Reject (cancel + restore clipboard). Plus an **Edit result** toggle that swaps the right pane for an editable text box so the user can hand-fix the AI output before accepting. Disable per-prompt via the editor checkbox, or globally via Settings → Additional features.

**Streaming toast**: progressive display of generation — visible AI typing. SSE for OpenRouter, NDJSON for Ollama. The ✕ button cancels the request instantly. Toggle in Settings → Additional features.

## Pro version — 6 extra features

Pro is a one-time payment ($9 via Gumroad). It unlocks six features on top of Free. Every one is visible to free-tier users with a small "Pro" pill, so users can preview what they'd unlock. Clicking a locked action shows a toast pointing to the purchase page.

1. **History export to CSV / JSON** — one-click export of all 50 history entries.
2. **Settings backup & restore** — save the whole config (prompts, models, hotkeys, language, feature flags) to a portable JSON file. API key and Pro license are not included in backups (they're per-machine).
3. **Switch-model hotkey** (`Ctrl+Shift+M`) — cycle 2–3 pinned models. Provider-scoped. Works mid-run.
4. **Premium prompt packs** — 5 curated packs × ~10 prompts each (Legal, Marketing, Academic, Code review, Business correspondence). Trilingual.
5. **Usage statistics** — fourth tab in Settings. Overview (total improvements, characters, spent, active-since), By model, 30-day activity chart. Stats recorded unconditionally even if History is off. File: `~/.ai_text_improver_v2_stats.json`.
6. **One-off custom prompt box** — in the prompt menu (`Ctrl+Shift+Q`), a box below the prompt list lets you type a one-time instruction and apply it to the selection immediately, without saving a preset. Enable and configure its model / language / diff-preview in Settings → General → Custom prompt card.

### Pro activation

1. Buy the key on Gumroad — see the pricing section on [capybro.app](https://capybro.app/#pricing).
2. Gumroad emails the license key after purchase.
3. In CapyBro: Settings → General → Pro License card → paste the key into the only input field → Activate. The buyer email is NOT entered manually — it comes back from Gumroad automatically and shows up under the "Pro activated" status.
4. If the key checks out, "✓ Pro activated" appears immediately, the "Supporter" badge lights up in the title bar, and all 6 Pro features unlock.

**One device per key.** A key can be activated on a single machine. To free the slot, use Settings → Pro License → Remove license on a machine you no longer use. This doesn't invalidate the key, just unbinds that slot.

**Verification flow**: CapyBro's `LicenseService` POSTs to `https://capybro.app/api/license/verify` (a Cloudflare Pages Function). The function calls Gumroad's `/v2/licenses/verify` API + signs the resulting token with ECDSA P-256. CapyBro verifies the signature offline via the embedded public key + caches the token for 30 days. Refunds, disputes, and chargebacks all cause the next license check to fail and Pro to automatically deactivate.

## Privacy & data storage

CapyBro collects **zero telemetry** by default. No analytics, no crash reporting, no surveys. All network requests are only the user's requests to OpenRouter (one HTTPS call per hotkey). Nothing else goes anywhere.

| What | Where | Notes |
|---|---|---|
| API key | Windows Credential Manager (`CapyBroV2`) | Encrypted with DPAPI under the current Windows user. Other users / other machines can't read it. |
| Config | `~/.ai_text_improver_v2_config.json` | Plaintext JSON. Contains prompts, hotkeys, settings, and (after Pro activation) the license token. Does NOT contain the API key. |
| History | `~/.ai_text_improver_v2_history.json` | Plaintext JSON. Can be disabled in settings; then the file isn't written at all. |
| Logs | `~/.ai_text_improver_v2*.log` | Diagnostic info, without request / response content. A new file each day. |
| Statistics | `~/.ai_text_improver_v2_stats.json` | Plaintext JSON. Counts only, no text. Created only after Pro is activated. |

The snake_case `ai_text_improver_v2_` prefix in filenames is intentional legacy from the v1 product name (AITextImprover); it was deliberately not renamed during the 2026-05-12 brand rename to CapyBro so existing users' data didn't get orphaned.

**PII redaction (experimental)**: Settings → Additional features → "PII masking" automatically replaces before sending to the model: emails → `<<EMAIL_n>>`, phones → `<<PHONE_n>>`, URLs → `<<URL_n>>`, credit cards → `<<CARD_n>>`, IBAN → `<<IBAN_n>>`, full names (heuristic) → `<<NAME_n>>`. The original values are substituted back into the AI response — the model never sees the user's real PII. Hidden when Ollama is active because nothing leaves the machine anyway.

## Resetting to defaults

CapyBro has three independent stores — settings, history, statistics. Each has its own one-click reset button inside the app. **Users do not have to delete files manually.**

- **Reset settings (most common)**: Settings → General → scroll to the bottom → Danger zone → "Reset settings". On confirm: config file overwritten with defaults, OpenRouter API key removed from Windows Credential Manager, Pro license (if any) deactivated. Does NOT touch the history file, statistics file, autostart registry entry, or log file — those have their own resets.
- **Clear history**: Settings → History → Clear all. Wipes the 50-entry history JSON.
- **Reset statistics**: Settings → Statistics → Reset statistics (Pro-only).
- **Disable autostart**: Settings → General → System → uncheck "Run with Windows". Removes the HKCU Run-key entry.

Reset does NOT bring back the onboarding wizard — the "onboarding completed" flag is part of the default config it writes. To see the wizard again: close the app, open `~/.ai_text_improver_v2_config.json` in a text editor, find `"OnboardingCompleted": true`, change to `false`, relaunch.

## Refund process

CapyBro offers a 14-day money-back guarantee on Pro. To request a refund, the buyer emails support@capybro.app with the order email or Order ID from Gumroad. The seller (Roman) issues the refund through the Gumroad dashboard (Sales → find sale → Refund). Money returns to the original payment method (Visa, MC, PayPal, Apple Pay) in 5-10 business days. CapyBro automatically deactivates Pro on the user's machine within 30 days as the next license re-check sees the refunded state from Gumroad.

## FAQ

**Q: Which operating systems are supported?**
A: Windows 10 (build 1809 or later) and Windows 11, x64. No macOS or Linux version — the program depends on Win32 APIs.

**Q: Is internet required?**
A: Depends on the mode. In OpenRouter mode — yes, because the AI runs in the cloud. In Ollama mode — NO, the AI runs locally with zero network requests.

**Q: Which AI models are supported?**
A: Through OpenRouter: all major ones (GPT-4o, Claude Sonnet, Gemini, Llama, DeepSeek, Mistral, etc.). Through Ollama: any model the user has pulled locally (gemma, llama, mistral, qwen, etc.).

**Q: How much does cloud AI cost?**
A: OpenRouter charges per use. A typical "fix text" request costs $0.0001–0.001 depending on model. $5 on OpenRouter lasts months of active use. CapyBro shows estimated cost before sending.

**Q: Is this subscription or one-time?**
A: One-time payment. $9 once → use Pro forever, all future updates included.

**Q: How many computers can I use Pro on?**
A: One device per key. To move Pro to another PC, remove the license on the old machine, then activate the key on the new one.

**Q: Is the API key safe in CapyBro?**
A: Yes. The key is stored only on the user's computer, encrypted via Windows DPAPI. Never sent to any third-party server except OpenRouter itself. The free version is open-source — can be verified directly.

**Q: What if I don't want to trust anyone with my text?**
A: Enable Ollama mode — fully local AI on the user's machine. Install Ollama from ollama.com, pull a model (e.g., `ollama pull gemma3`), switch CapyBro to Ollama. Needs 8+ GB RAM for small models (16+ GB preferred).

**Q: Where to contact?**
A: Email support@capybro.app. Or open an issue at [github.com/phantasmat2018/capy-bro/issues](https://github.com/phantasmat2018/capy-bro/issues).