Bzz Free and Open Source Desktop App CookApps CookApps Marketplace

Bzz

Automatic keyboard layout switcher for macOS. Types "ghbdtn" in QWERTY by mistake? Bzz instantly converts it to "привет" before you hit Enter.

Bzz is the open-source MIT alternative to Caramba Switcher for macOS users who need automatic Cyrillic↔Latin layout switching — a 98K-word morphological dictionary, on-device only (no telemetry), and a one-time 490 ₽ price for Pro features instead of a yearly subscription. It also fills the gap left by Punto Switcher, which has been abandoned for macOS since 2017.

Features

Instant auto-correction: Detects wrong keyboard layout and fixes on the fly

Smart dictionary: 98K Russian words with Snowball stemmer for accurate detection

Fuzzy matching: Catches typos within 1 character edit distance

Undo in 5 seconds: Cmd+Z to revert the last correction

Context-aware: Understands Russian/English context to avoid false positives

Zero configuration: Works out of the box with sensible defaults

System tray: Pause/resume with a single click (⚡ active, 💤 paused)

Auto-start: Launches automatically at login via LaunchAgent

Lightweight: ~4 MB binary, minimal CPU usage

Requirements

macOS 10.15+

Accessibility permission (required for keyboard interception)

Windows support is planned.

Installation

Download Pre-built Binary (Recommended)

Download the latest .dmg from Releases

Open the DMG and drag Bzz to Applications

Launch Bzz from Applications

Important: First launch requires granting Accessibility permission:

macOS will prompt you to allow Bzz in System Settings → Privacy & Security → Accessibility

If prompted by Gatekeeper ("Cannot open because it is from an unidentified developer"):

Right-click Bzz.app → Open Anyway

Or: xattr -d com.apple.quarantine /Applications/Bzz.app

Build from Source

Requirements: Go 1.26+ and make

bash

git clone https://github.com/zlopixatel/bzz.git
cd bzz
make app          # Creates Bzz.app in ./build/
make install      # Copies to ~/Applications/

Or build the binary only:

bash

go build -ldflags="-s -w" -o Bzz .
./Bzz

First Run

Grant Accessibility permission:

Go to System Settings → Privacy & Security → Accessibility

Add Bzz to the allowed apps list

Restart Bzz if needed

Configure (optional):

Bzz creates ~/Library/Application Support/Bzz/config.yaml on first run

Default settings work for most users — no action required

Check tray icon:

Look for the Bzz icon in the menu bar (top-right corner)

⚡ icon = active, 💤 icon = paused

Usage

Automatic Correction

Just type normally. Bzz watches for wrong keyboard layout:

terminal

Type: ghbdtn [Space]     → Auto-corrects to: привет
Type: GHBDTN [Space]     → Auto-corrects to: ПРИВЕТ
Type: Lfvecz, [Enter]    → Auto-corrects to: Привет, [then submits]

When does it correct?

When you press Space, Enter, or punctuation (. , ! ? ; : ' ")

If the word is in the Russian dictionary

Or within 1 typo of a known Russian word (6+ characters)

Undo

Press Cmd+Z within 5 seconds of a correction to revert:

terminal

ghbdtn [Space] → привет
[Cmd+Z]        → ghbdtn (reverted)

The undo window closes after 5 seconds or if you type something else.

Pause/Resume

Click the tray icon to toggle:

⚡ Active (normal operation)

💤 Paused (Bzz is disabled)

Or quit from the tray menu.

Configuration

Edit ~/Library/Application Support/Bzz/config.yaml:

yaml

enabled: true                    # Enable/disable the app
primary_language: ru             # Primary language (ru or en)
min_word_length: 2               # Minimum word length to check
excluded_apps:                   # Apps where Bzz is disabled
  - idea                         # Example: JetBrains IDEs

Changes take effect immediately — no restart needed.

Architecture

Core Components

Hook (hook_darwin.go): CGEventTap intercepts keyboard events in real-time

Detector (detector.go): Analyzes text to determine if layout switch occurred

Dictionary (dict.go): 98K Russian words + Snowball stemmer for lemmatization

Replacer (replacer_darwin.go): Sends backspace/character events to fix text

Tray (tray_darwin.go): System menu bar integration for pause/resume

Buffer (buffer.go): Accumulates characters to form words at phrase boundaries

Detection Algorithm

Script detection: Identifies if text is Latin or Cyrillic

Dictionary lookup: Checks if the converted word exists in Russian dictionary

Stem matching: Uses Snowball stemmer for verb/noun variations

Fuzzy matching: For 6+ character words, finds corrections within 1 edit distance (Levenshtein)

Context tracking: Remembers recent language to avoid false positives

Trailing punctuation: Handles mixed QWERTY/Russian punctuation correctly

Example Detection

terminal

Input:      "ghbdtn"
Convert:    "привет" (QWERTY → Russian keymap)
Lookup:     ✓ Found in dictionary
Result:     Correct to "привет"

Input:      "ghbdtna" (typo: extra 'a')
Convert:    "приветf" 
Fuzzy:      Within 1 edit of "приветф" or "привет"?
Result:     Correct to "привет"

Building from Source

macOS Binary

bash

go build -ldflags="-s -w" -o Bzz .

macOS App Bundle

bash

make app      # Creates Bzz.app with icon

macOS Installer (DMG)

bash

make dmg      # Creates Bzz.dmg

Windows Executable (Cross-compile from macOS)

Windows support requires MinGW on macOS:

bash

brew install mingw-w64
make build-windows

Creates Bzz.exe.

Release Artifacts

bash

make release  # Builds both macOS .dmg and Windows .exe

Testing

Run the test suite:

bash

go test ./... -v

Key tests:

detect_test.go: Dictionary lookup and fuzzy matching logic

shifted_test.go: Shifted key handling (Caps Lock, numbers)

integration_test.go: End-to-end behavior with buffer

Contributing

Bzz is open-source under the MIT license. Contributions welcome!

Adding Support for Other Languages

Add a dictionary file to dicts/_freq.txt (one word per line)

Add stemmer support in dict.go if available

Update keymap in keymap.go for the target language

Test with detect_test.go

Improving Russian Dictionary

The dictionary at dicts/ru_freq.txt is frequency-ranked. To improve:

Submit PRs with additional common Russian words

Include frequency data if available

Test with real-world usage patterns

Architecture Decisions

CGEventTap: Chosen over Quartz Event Services for consistent, low-latency event interception

Snowball Stemmer: Preferred over hand-written rules for Russian morphology

Active undo (5s window): Short enough to not interfere with typing, long enough for reflexive corrections

Exact EN match: Prevents "if", "the", "and" from being corrected when typed on Russian layout

Lightweight dictionary: Embedded (no network calls), fast in-memory lookup with 98K words covering 99% of common Russian

Open Core Model

Bzz core is free under the MIT License — forever. This includes auto-correction,

fuzzy matching, Cmd+Z undo with per-app learning, Cmd+Shift+X manual selection

conversion, tray icon, LaunchAgent auto-start, and per-app exclusions via

config.yaml. None of these will ever move to a paid tier.

Bzz Pro (v0.4, planned Q3 2026) — one-time 490 ₽ purchase, lifetime:

Custom Dictionary — add your own terms, client names, professional jargon

the auto-corrector should respect

Additional layouts — Ukrainian, Kazakh, Belarusian, German, French

(one included in Pro, others +200 ₽ upgrade)

Per-app exception UI — graphical management of the rules Cmd+Z learns

See marketing/PRO_FEATURES.md for the canonical

list and rationale. Pro will be sold through a Telegram bot with offline

Ed25519-signed license files — no servers, no telemetry, no recurring charges.

Until Pro ships, you can support development via Boosty / GitHub Sponsors

(TBA) — supporters do not get extra features (so we stay honest about

what Pro will be).

Privacy

Bzz processes keystrokes locally only. There is no HTTP client in the

binary — grep -rE "net/http|net.Dial" *.go returns nothing. Read the

full Privacy Policy.

Troubleshooting

"Bzz cannot be opened" (Gatekeeper)

bash

xattr -d com.apple.quarantine /Applications/Bzz.app
open /Applications/Bzz.app

Or: Right-click Bzz.app → Open Anyway

Accessibility permission not working

Go to System Settings → Privacy & Security → Accessibility

Remove Bzz if listed

Restart Bzz — it will re-request permission

Grant access and restart

Corrections not happening

Check the tray icon (is it ⚡ or 💤)?

Verify Accessibility permission is granted

Check system logs: log stream | grep Bzz

Ensure your keyboard layout is set to Russian (Cmd+Space to switch)

Performance or crashes

Check ~/Library/Application Support/Bzz/config.yaml for typos

Try resetting config: Delete the file and restart (defaults will be recreated)

Report issues with system details at GitHub Issues

License

MIT License — see LICENSE for details.

Competitors

Caramba Switcher: Closed-source, subscription model ($29.99/year)

Punto Switcher: Legacy Windows-first design, limited macOS support

Bzz: Free, open-source, macOS-native

Русский / Russian

О проекте

Bzz — автоматический переключатель раскладки клавиатуры для macOS. Типите "ghbdtn" вместо "привет"? Bzz исправит это прямо при вводе.

Возможности

Автоматическое исправление: Обнаруживает ошибку раскладки и исправляет на лету

Словарь из 98K слов: С лемматизацией Snowball для точного обнаружения

Нечёткий поиск: Находит опечатки в расстоянии Левенштейна до 1

Отмена за 5 секунд: Cmd+Z для отката последней коррекции

Контекстная обработка: Понимает русский/английский контекст

Без конфигурации: Работает сразу из коробки

Иконка в трее: Пауза/возобновление одним кликом

Автозапуск: Запускается при входе в систему

Установка

#### Готовый бинарник

Скачайте последний .dmg с Releases

Откройте DMG и перетащите Bzz в Applications

Запустите Bzz

Системе потребуется разрешение доступа в System Settings → Privacy & Security → Accessibility

#### Сборка из исходников

bash

git clone https://github.com/zlopixatel/bzz.git
cd bzz
make app      # Создаёт Bzz.app
make install  # Копирует в ~/Applications/

Использование

#### Автоматическое исправление

Просто пишите. Bzz следит за ошибками раскладки:

terminal

Печатаете: ghbdtn [Space]     → Исправляет на: привет
Печатаете: Lfvecz, [Enter]    → Исправляет на: Привет, [отправляет]

Исправляет когда:

Нажимаете Space, Enter или пунктуацию (. , ! ? ; : ' ")

Слово есть в русском словаре

Или в одной опечатке от русского слова (6+ букв)

#### Отмена

Cmd+Z в течение 5 секунд после исправления:

terminal

ghbdtn [Space] → привет
[Cmd+Z]        → ghbdtn (отменено)

#### Пауза/возобновление

Клик на иконку в трее:

⚡ Активно (работает)

💤 Пауза (отключено)

Конфигурация

Отредактируйте ~/Library/Application Support/Bzz/config.yaml:

yaml

enabled: true              # Включено/отключено
primary_language: ru       # Основной язык (ru или en)
min_word_length: 2         # Минимальная длина слова
excluded_apps:             # Приложения, где отключено
  - idea                   # Пример: JetBrains IDEs

Проблемы и решения

"Bzz cannot be opened":

bash

xattr -d com.apple.quarantine /Applications/Bzz.app

Нет разрешения на доступ:

System Settings → Privacy & Security → Accessibility

Удалите Bzz из списка

Перезапустите Bzz и снова разрешите доступ

Исправления не работают:

Проверьте иконку в трее (⚡ или 💤?)

Убедитесь, что раскладка установлена на Русский

Посмотрите логи: log stream | grep Bzz

Лицензия

MIT — см. LICENSE

Bzz

Bzz

Features

Requirements

Installation

Download Pre-built Binary (Recommended)

Build from Source

First Run

Usage

Automatic Correction

Undo

Pause/Resume

Configuration

Architecture

Core Components

Detection Algorithm

Example Detection

Building from Source

macOS Binary

macOS App Bundle

macOS Installer (DMG)

Windows Executable (Cross-compile from macOS)

Release Artifacts

Testing

Contributing

Adding Support for Other Languages

Improving Russian Dictionary

Architecture Decisions

Open Core Model

Privacy

Troubleshooting

"Bzz cannot be opened" (Gatekeeper)

Accessibility permission not working

Corrections not happening

Performance or crashes

License

Competitors

Русский / Russian

О проекте

Возможности

Установка

Использование

Конфигурация

Проблемы и решения

Лицензия

How to Use & Getting Started

Ready to run Bzz?

More in system-utilities

Plonk

Kawa

WhatCable