bolo

Bolo is a macOS push-to-talk dictation app that transcribes speech and pastes the resulting text into any active text field, including Slack, Notion, Gmail, VS Code, terminals and browsers. The name comes from Hindi, where "bolo" means "speak". It targets macOS 12+ and Rust 1.88+ and is released under the MIT license, with a project website listed in the README. Setup and permissions: install.sh creates a private Python helper environment at ~/.bolo/venv, builds the Rust binary, looks for an existing Telnyx API key in ~/.codex/.env or the environment (prompting and saving to ~/.bolo/env when none is found), registers Bolo as a login item and starts it. On first launch an onboarding dialog asks which key to hold for dictation, offering options such as Right Option, Right Control, F19 and Caps Lock; the choice is stored in ~/.bolo/env. Bolo then needs macOS Microphone and Accessibility permissions, the latter granted to the managed Python interpreter at ~/.bolo/venv/bin/python3 that performs paste insertion. The README also provides a prompt that can be handed to a coding agent to walk through installation and permission granting. Dictation flow: hold the configured hotkey, speak, and release. Text is inserted at the cursor using the clipboard, and the previous clipboard contents are restored by default. A menu bar icon exposes recent transcripts for manual copying, plus commands such as Clear Transcript History, Run Health Check, Rewrite Selected Text, Add Vocabulary Term, Add Vocabulary Alias, Add Correction Rule and Check for Updates. Configuration: settings are read from the environment or ~/.bolo/env. Options include TELNYX_API_KEY; BOLO_HOTKEY for the push-to-talk key (right_option, right_control, right_shift, fn, f1 through f19, caps_lock); BOLO_PASTE_LAST_HOTKEY for re-pasting the latest transcript; BOLO_MICROPHONE; BOLO_MAX_RECORDING_SECONDS, with a 30-second watchdog default that auto-releases long recordings; BOLO_STT_MODEL and BOLO_STT_FALLBACK_MODEL; BOLO_STT_LANGUAGE for language or accent hints, with a fallback to English (US) if a non-US hint proves slow; BOLO_STT_FALLBACKS for a comma-separated provider chain that can include telnyx:model, xai and assemblyai; BOLO_STT_STREAMING, which controls Deepgram Nova-3 streaming versus batch transcription; BOLO_PRESERVE_CLIPBOARD; BOLO_LLM_CLEANUP; BOLO_AUTO_UPDATE; and BOLO_LOG_TRANSCRIPTS, off by default so dictated text is redacted from /tmp/bolo.log. Cleanup, vocabulary and corrections: LLM cleanup defaults to auto, skipping short clean dictations and engaging for longer or messier ones; the README notes Telnyx Qwen/Qwen3-235B-A22B with thinking disabled, or Kimi-K2.5 when LiteLLM is configured, and states that MiniMax is intentionally not used for cleanup. Cleanup can read the frontmost app and nearby cursor text through Accessibility for spacing and capitalization. Voice commands include "scratch that", "actually ...", "polish that" and "prompt that", guarded so they act only when the previous dictation is still immediately before the caret and matches exactly. Personal vocabulary lives in ~/.bolo_vocabulary.json and supports alias objects for common mishears; deterministic replacement rules live in ~/.bolo/replacements.json; per-app cleanup styles are stored in ~/.bolo/prompt_bindings.json with profiles default, email, chat and notes. Privacy and history: audio is sent to Telnyx APIs for transcription and processed in memory only, according to the README, and transcripts are not used for training. The ten most recent transcripts are stored locally at ~/.bolo/transcripts.json, keeping raw and cleaned variants when cleanup changes the text, and can be deleted from the menu bar. Limitations and maintenance: Bolo requires an internet connection, short dictation works well today while longer dictation and latency are still being improved, and cleanup is intentionally conservative to preserve literal meaning. Updates are checked at launch or on demand and are skipped when local files have uncommitted changes, GitHub is unreachable, Rust is missing, or the checkout cannot fast-forward cleanly. A small phrase-based evaluation harness (eval_dictation.py with prompts, init and score commands) is included, and troubleshooting focuses on /tmp/bolo.log, API key presence, permissions for the managed interpreter, and restart.sh.