VibeMouse

Speak into code with your mouse side buttons.

VibeMouse is a Linux / Hyprland-first voice dictation daemon for VibeCoding. Hold a side button, talk, release — the transcript lands in the focused input. No floating mic window. No alt-tabbing into a dictation app.

中文文档：README.zh-CN.md

Status: Apache-2.0 · Beta · Linux / Hyprland supported.
Windows / macOS adapters exist in code but are not release targets yet.

---

Daily workflow

Action	Result
Front side button	Start / stop recording
Rear side button (idle)	Send Enter
Rear side button (recording)	Stop + type/paste the transcript

While it runs, a status file tracks idle → recording → processing so your top bar (e.g. Waybar) can mirror the state. Failures get a desktop notification; successful typed/pasted output stays quiet.

---

Why it exists

Coding speech is bursty: short phrases, product names, “send that.” Keyboard hotkeys fight muscle memory; phone-style dictation apps steal focus. VibeMouse keeps dictation on the mouse you already hold, with local ASR by default and optional cloud profiles when you need them.

Design rules we keep:

• Low friction for dozens of takes per day
• Clear failure modes (no silent downgrade between ASR backends)
• Graceful output fallback (type → paste → clipboard)

---

Install (Linux)

One-command deploy (recommended)

bash scripts/auto-deploy.sh --preset stable

Creates a venv, installs VibeMouse, writes a systemd --user unit, and runs vibemouse doctor.

Presets: stable · fast · low-resource

Manual install

Debian / Ubuntu

sudo apt update
sudo apt install -y python3-gi gir1.2-atspi-2.0 portaudio19-dev libsndfile1

Arch

sudo pacman -Syu --needed python python-pip python-gobject portaudio libsndfile

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
export VIBEMOUSE_BACKEND=funasr_onnx
export VIBEMOUSE_DEVICE=cpu
vibemouse

Default install is ONNX-first (smaller footprint). Optional extras:

pip install -e ".[pt]"            # PyTorch / FunASR enhanced path
pip install -e ".[translation]"   # local Opus-MT translation toast
pip install -e ".[npu]"           # Intel NPU

---

ASR profiles

Pick a profile, not a transport stack:

Profile	Best for	Backend
fast	Daily low-latency	SenseVoice (local)
enhanced	Accuracy + hotwords	FunASR (local)
paraformer	Cloud accuracy	Alibaba DashScope Paraformer-v2
cloud	Alternate cloud	Unisound U2-ASR

vibemouse profile list
vibemouse profile set enhanced
vibemouse profile menu          # wofi/rofi picker (Waybar-friendly)

Unavailable profiles fail loudly — they never silently fall back.

Cloud keys (settings UI or env): VIBEMOUSE_PARAFORMER_API_KEY, VIBEMOUSE_CLOUD_ASR_API_KEY. Read docs/PRIVACY.md before enabling online paths.

Starter config: shared/examples/config.example.json.

Personal dictionary

{
  "term": "Codex",
  "phrases": ["codex", "code x", "扣带思"],
  "weight": 8,
  "scope": "both",
  "enabled": true
}

enhanced uses phrases as decode hotwords; local profiles normalize hits back to term.

---

Desktop controls

Settings console

vibemouse settings --open-browser   # loopback only: 127.0.0.1

Edit profiles, keys, dictionary, buttons/gestures, and inspect live status without leaking secrets into the status JSON. Save writes disk first, then requests a daemon reload.

Waybar (optional)

Wire the indicator so left/right/middle clicks match your muscle memory. Example module + status script: docs/WAYBAR_PROFILE_SWITCH.md

Typical mapping used in the docs:

• Left → open settings
• Right → vibemouse profile menu
• Middle → restart the user service

Local availability probes are cached; force a refresh with vibemouse profile list --refresh.

Gesture-only mode

Need workspace/Enter gestures without loading ASR?

vibemouse gesture

Do not run it alongside the voice daemon on the same input device.

---

Keep it healthy

vibemouse doctor          # env, mic, input ACL, Hyprland binds, service
vibemouse doctor --fix    # safe auto-remediations, then re-check
vibemouse smoke           # software integration checks (isolated temp workspace)
vibemouse deploy --preset stable

Logs (after deploy):

tail -f ~/.local/state/vibemouse/service.log

---

Button map & common env

Defaults: front = x1, rear = x2. Swap if your hardware is reversed:

export VIBEMOUSE_FRONT_BUTTON=x2
export VIBEMOUSE_REAR_BUTTON=x1

Variable	Default	Purpose
VIBEMOUSE_ENTER_MODE	enter	Rear-idle action (enter / ctrl_enter / shift_enter / none)
VIBEMOUSE_AUTO_PASTE	false	Auto-paste when output falls back to clipboard
VIBEMOUSE_PREWARM_ON_START	true	Preload ASR after start
VIBEMOUSE_STATUS_FILE	$XDG_RUNTIME_DIR/vibemouse-status.json	Bar / widget status
VIBEMOUSE_COMMAND_AUTH_TOKEN	unset	Auth for local reload/command clients
VIBEMOUSE_PARAFORMER_API_KEY	unset	Alibaba cloud ASR
VIBEMOUSE_CLOUD_ASR_API_KEY	unset	Unisound cloud ASR

Source of truth: vibemouse/config/schema.py.

---

Troubleshooting

Everything “dead” but service is active — usually side-button event codes, not a crashed daemon. x1 matches {BTN_SIDE, BTN_BACK}; x2 matches {BTN_EXTRA, BTN_FORWARD}. Check: systemctl --user is-active vibemouse.service → vibemouse doctor → confirm VIBEMOUSE_FRONT_BUTTON / REAR_BUTTON in the service environment.

Enter still fires while recording — remove Hyprland hard binds like bind = , mouse:275, sendshortcut, , Return, activewindow, then hyprctl reload config-only.

Settings don’t apply — inspect status + doctor:

cat "${XDG_RUNTIME_DIR:-/tmp}/vibemouse-status.json"
vibemouse doctor

No side-button events on Linux

sudo usermod -aG input $USER   # then re-login

---

Docs & policies

Doc	For
docs/PRIVACY.md	Data / cloud paths
SECURITY.md	Vulnerability reporting
CONTRIBUTING.md	Patches
SUPPORT.md	Support boundaries
CHANGELOG.md	Releases
docs/AI_ASSISTANT_DEPLOYMENT.md	AI / platform adapters
docs/AI_DEBUG_RUNBOOK.md	Debug playbook
THIRD_PARTY_NOTICES.md	Models & deps

Architecture for adapters lives in the AI deployment guide — this README stays focused on using VibeMouse day to day.

License

Apache-2.0. See LICENSE and THIRD_PARTY_NOTICES.md.