{"id":48343761,"url":"https://github.com/mizrael/keryxis","last_synced_at":"2026-04-05T06:01:56.110Z","repository":{"id":346076720,"uuid":"1188296438","full_name":"mizrael/keryxis","owner":"mizrael","description":"Local, privacy-first speech-to-text tool that injects dictated text into any application.","archived":false,"fork":false,"pushed_at":"2026-03-22T15:44:34.000Z","size":258,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T19:33:50.760Z","etag":null,"topics":["ai","local","privacy","rust","speech-to-text","whisper"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mizrael.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T22:05:01.000Z","updated_at":"2026-03-22T15:36:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mizrael/keryxis","commit_stats":null,"previous_names":["mizrael/keryxis"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mizrael/keryxis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizrael%2Fkeryxis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizrael%2Fkeryxis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizrael%2Fkeryxis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizrael%2Fkeryxis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizrael","download_url":"https://codeload.github.com/mizrael/keryxis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizrael%2Fkeryxis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31426193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","local","privacy","rust","speech-to-text","whisper"],"created_at":"2026-04-05T06:01:53.712Z","updated_at":"2026-04-05T06:01:56.081Z","avatar_url":"https://github.com/mizrael.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keryxis\n\n**The herald who proclaims your words** — a local, privacy-first speech-to-text tool that injects dictated text into any application.\n\nKeryxis runs as a background daemon with a floating overlay, using OpenAI's Whisper model locally on your machine. No cloud APIs, no data leaves your computer.\n\n## Features\n\n- **Three activation modes:**\n  - **Press to talk** — press a hotkey to start/stop recording\n  - **Auto-stop** — press a hotkey, recording stops automatically when you go silent\n  - **Hands-free** — always listening for a configurable wake word (e.g., \"hey terminal\")\n- **Works with any application** — injects text into whatever window is focused (terminal, editor, browser, etc.)\n- **Multi-language** — supports 99 languages with priority-based detection (try English first, then Italian, etc.)\n- **Background daemon** with floating overlay showing recording state and target application\n- **Settings panel** — change mode, hotkey, wake word, model size, and languages from the overlay UI\n- **Local \u0026 private** — Whisper runs entirely on your machine with Metal GPU acceleration on macOS\n- **Cross-platform** — runs on macOS, Linux, and Windows with pre-built binaries for all three\n- **Microphone selection** — choose from available input devices in the settings panel\n\n## Requirements\n\n- **macOS**, **Linux**, or **Windows**\n- **Microphone** access\n- **macOS Accessibility permission** — required for text injection (System Settings → Privacy \u0026 Security → Accessibility → add Keryxis or your terminal)\n- ~75MB disk space for the Whisper tiny model (more for larger models)\n\n## Installation\n\n### Pre-built release\n\nDownload the latest release for your platform from the [Releases](https://github.com/mizrael/keryxis/releases) page:\n\n| Platform | File | Notes |\n|----------|------|-------|\n| macOS (Apple Silicon) | `keryxis-macos-arm64.tar.gz` | M1/M2/M3/M4 Macs |\n| macOS (Intel) | `keryxis-macos-x86_64.tar.gz` | Older Intel Macs |\n| Linux (x86_64) | `keryxis-linux-x86_64.tar.gz` | |\n| Windows (x86_64) | `keryxis-windows-x86_64.zip` | |\n\nNo Rust toolchain needed.\n\n### Build from source\n\nRequires the [Rust toolchain](https://rustup.rs/).\n\n**macOS** (default features include Metal GPU acceleration + GUI):\n\n```bash\ncargo build --release\n```\n\n**Linux** (no Metal, GUI enabled):\n\n```bash\ncargo build --release --no-default-features --features gui\n```\n\n**Windows** (no Metal, GUI enabled):\n\n```bash\ncargo build --release --no-default-features --features gui\n```\n\n**Build without GUI** (headless/server, no overlay window):\n\n```bash\ncargo build --release --no-default-features --features metal  # macOS\ncargo build --release --no-default-features                   # Linux/Windows\n```\n\n**Build with CUDA** (Linux with NVIDIA GPU):\n\n```bash\ncargo build --release --no-default-features --features cuda,gui\n```\n\n## Setup\n\n### 1. Platform-specific setup\n\n**macOS:** Grant Accessibility permission — go to **System Settings → Privacy \u0026 Security → Accessibility** and add your terminal app (Terminal.app, iTerm2, or VS Code).\n\n**Windows:** No additional setup required. You may need to allow microphone access in Windows Settings → Privacy → Microphone.\n\n**Linux:** Ensure your user has access to audio devices (usually automatic).\n\n### 2. Start Keryxis\n\nSimply run the binary with no arguments:\n\n```bash\nkeryxis\n```\n\nThis starts the background daemon and opens the floating overlay. On first launch, the Whisper model (`tiny`, ~75MB) is downloaded automatically. On Windows, the console window hides automatically.\n\nYou can also start explicitly:\n\n```bash\nkeryxis daemon start\n```\n\nTo pre-download a specific model size (optional):\n\n```bash\nkeryxis download-model --size small\n```\n\nAvailable sizes: `tiny` (75MB, fastest), `base` (150MB), `small` (500MB), `medium` (1.5GB), `large` (3GB, most accurate).\n\n## Usage\n\n### Daemon commands\n\n```bash\n# Start daemon + overlay\nkeryxis daemon start\n\n# Check status\nkeryxis daemon status\n\n# Stop daemon + overlay\nkeryxis daemon stop\n\n# Open overlay separately\nkeryxis overlay\n```\n\n### Foreground mode (no daemon)\n\n```bash\n# Run in foreground with default settings\nkeryxis start\n\n# Run with specific mode\nkeryxis start --mode vad\nkeryxis start --mode wake-word\n\n# Run with a different hotkey\nkeryxis start --hotkey \"Ctrl+Shift+R\"\n```\n\n### Configuration via CLI\n\n```bash\n# Show current config\nkeryxis config --show\n\n# Change settings\nkeryxis config --mode vad\nkeryxis config --hotkey \"Alt+R\"\nkeryxis config --wake-word \"hey computer\"\nkeryxis config --model small\nkeryxis config --language it\n```\n\n## The Overlay\n\nThe floating overlay shows:\n\n```\n● RDY \u003e Terminal [Press to talk]  ≡ ⚙\n```\n\n- **Status indicator**: green (ready), red pulsing (recording), yellow (processing/disconnected), gray (paused — overlay focused)\n- **Target app**: which application will receive the text\n- **Mode label**: current activation mode\n- **≡** — toggle live daemon log viewer\n- **⚙** — open settings panel\n\n### Settings panel\n\nClick ⚙ to configure:\n\n- **Mode** — Press to talk / Auto-stop / Hands-free\n- **Hotkey** — click the field and press your desired key combination (e.g., Alt+Space, Cmd+R)\n- **Wake word** — the phrase that activates hands-free mode\n- **Microphone** — select from available input devices, or use system default (click ⟳ to refresh the list)\n- **Model** — Whisper model size (Tiny through Large)\n- **Languages** — ordered priority list; click `+ Language` to add, click a language to remove, `^` to reorder\n\nChanges auto-restart the daemon when you click Save.\n\n## Configuration\n\nConfig file location:\n- **macOS/Linux:** `~/.config/keryxis/config.toml`\n- **Windows:** `%APPDATA%\\keryxis\\config.toml`\n\n```toml\n[activation]\nmode = \"toggle\"           # toggle, vad, or wake_word\nhotkey = \"Alt+Space\"\nwake_word = \"hey terminal\"\n\n[whisper]\nmodel_size = \"tiny\"       # tiny, base, small, medium, large\nlanguage = \"\"             # single language override (legacy)\nlanguages = [\"en\", \"it\"]  # priority list — tried in order\n\n[vad]\nenergy_threshold = 0.01   # speech detection sensitivity (0.0 - 1.0)\nsilence_duration_ms = 1500\nmin_speech_duration_ms = 500\n\n[audio]\nsample_rate = 16000\nchannels = 1\n# device = \"Headset Microphone (Jabra)\"  # optional — omit for system default\n\n[daemon]\nauto_start_overlay = true\n\n[overlay]\nposition = \"top-right\"    # top-right, top-left, bottom-right, bottom-left\nopacity = 0.85            # overlay background opacity (0.0 - 1.0)\n```\n\n## How It Works\n\n1. **Audio capture** — records from your microphone via `cpal` (cross-platform)\n2. **Voice activity detection** — energy-based VAD detects speech onset and silence\n3. **Speech recognition** — local Whisper model (via `whisper-rs` / `whisper.cpp`) transcribes audio\n4. **Text injection** — `enigo` simulates keyboard input into the focused application\n5. **Daemon** — background process communicates state to the overlay via IPC (Unix socket on macOS/Linux, TCP on Windows) using newline-delimited JSON\n\n### Multi-language priority\n\nWhen multiple languages are configured (e.g., `[\"en\", \"it\"]`), Keryxis tries each in order. English is tried first — if the transcription is non-empty, it's used. Otherwise, Italian is tried. This is faster than auto-detect because each attempt with a specific language skips Whisper's language detection step.\n\n## Files \u0026 Paths\n\n### macOS / Linux\n\n| Path | Purpose |\n|------|---------|\n| `~/.config/keryxis/config.toml` | Configuration |\n| `~/.local/share/keryxis/models/` | Whisper model files |\n| `~/.local/state/keryxis/daemon.pid` | Daemon PID file |\n| `~/.local/state/keryxis/daemon.log` | Daemon log file |\n| `~/.local/state/keryxis/keryxis.sock` | Unix socket for IPC |\n\n### Windows\n\n| Path | Purpose |\n|------|---------|\n| `%APPDATA%\\keryxis\\config.toml` | Configuration |\n| `%APPDATA%\\keryxis\\models\\` | Whisper model files |\n| `%LOCALAPPDATA%\\keryxis\\daemon.pid` | Daemon PID file |\n| `%LOCALAPPDATA%\\keryxis\\daemon.log` | Daemon log file |\n| TCP `127.0.0.1:19457` | IPC (replaces Unix socket) |\n\n## Supported Hotkeys\n\nModifiers: `Alt` / `Option`, `Ctrl` / `Control`, `Shift`, `Cmd` / `Meta` / `Super`\n\nKeys: `A`-`Z`, `F1`-`F12`, `Space`, `Tab`, `Return`, `Escape`, `Backspace`\n\nExamples: `Alt+Space`, `Ctrl+Shift+R`, `Cmd+E`, `F5`\n\n## Troubleshooting\n\n**\"Accessibility permission required\"** (macOS) — Add your terminal to System Settings → Privacy \u0026 Security → Accessibility. Toggle it off and on if already listed.\n\n**Overlay shows \"OFF\"** — Daemon isn't running. Run `keryxis daemon start` or just `keryxis`.\n\n**Overlay shows \"PAUSED\"** — The overlay window is focused. Click on another application to resume.\n\n**Wrong microphone** — Open settings (⚙) and select the correct microphone from the dropdown. Click ⟳ to refresh the device list.\n\n**Wake word not detected** — Whisper may transcribe your wake word differently. Check the daemon log (`≡` button in overlay) to see what Whisper hears. Punctuation is stripped before matching.\n\n**Transcription is slow** — Use the `tiny` model. Ensure Metal GPU acceleration is working on macOS (check daemon log for \"using device Metal\").\n\n**No audio captured** — Check that your microphone is working and not muted. On macOS, ensure microphone permission is granted. On Windows, check Settings → Privacy → Microphone.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizrael%2Fkeryxis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizrael%2Fkeryxis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizrael%2Fkeryxis/lists"}