CSCB/vibe-mouse: a Python input router that turns any device into an AI IDE shortcut

What vibe-mouse actually routes, and who ends up using it

The problem is narrower than the README's framing suggests. If you write code with an AI IDE, you repeat the same keyboard chords all day: open the chat panel, accept a suggestion, run a review prompt, explain a selection. Those chords are tied to one physical input, usually a keyboard, and to one application. vibe-mouse decouples the input from the shortcut. Its stated purpose is a "coding-based human-computer interaction paradigm that breaks the operational limitations of traditional mice", and the practical effect is that a button on a gamepad, a foot pedal exposed as HID, an IR remote, or an MQTT message can fire the same shortcut your keyboard fires.

The intended audience is stated in the README: individual development, laboratory projects, smart device retrofitting, and robotics scenario development. That list is honest about the shape of the project. This is not a consumer driver you install and forget. It is a Python process that sits between your devices and your IDE, and it expects you to configure the mapping. The repository also ships two sibling modules, actuator/ and monitor/, described as independently open-sourced and freely combinable, so the same event layer is meant to reach hardware as well as software.

The adapter pipeline: Device Event to Adapter to Event to DeviceManager to Executor

The README gives the data flow in one line: Device Event -> Adapter -> Event (unified) -> DeviceManager -> Executor (keyboard shortcut). Each stage has a file. Adapters live in core/adapters/ and inherit from core/adapters/base.py, which is described as the abstract base class for all adapters. An adapter's job is to translate whatever its device emits into the unified event abstraction in core/event.py, which defines DeviceType, InputType and Event. That is the whole portability trick: mouse_adapter.py uses pynput, gamepad_adapter.py uses pygame, bluetooth_adapter.py uses bleak or pybluez, and none of them need to know what a shortcut is.

core/device_manager.py owns the adapters and routes events to core/executor.py, which parses and executes shortcut combinations and fires feedback. core/feedback.py handles the return path: system sound, screen overlay, tray notification, LED indicator, or vibration motor. The README notes that hardware feedback requires custom setup, which is the first hint that the feedback layer is not uniform across channels.

Above the executor sits the Skill system, marked Beta. A Skill is described as a complete work mode: bind a button or key to "skill:<name>", or let voice keywords auto-match. A Skill can override shortcuts, feedback configuration, device activation and system prompt in one package, and it accepts YAML or JSON files plus built-in templates named quick-code, code-review, presentation and explain-code. core/skill_engine.py parses and matches these. core/tool_switcher.py records a full state snapshot on every tool switch, so returning to a previous tool restores the active Skill, shortcut overrides and feedback config. That snapshot design is the most interesting decision in the repository: it treats configuration as session state rather than a static file.

Installing vibe-mouse and getting one button to fire an IDE shortcut

The README does not contain a step-by-step install section, so the following is assembled from requirements.txt and the entry point named in the feature list. Start by installing the pinned core dependencies. The file lists pynput 1.7.6, pystray 0.19.5, Pillow 10.2.0 and pyinstaller 6.4.0 as core, with pywin32 306 and psutil 5.9.8 for window detection. Everything else in the file is commented out and must be enabled per adapter.

pip install -r requirements.txt

After that installs, the README states the entry point is core/main.py, and that running it with --gui opens a desktop panel showing the current tool, active Skill, switch history and the auto-detection toggle.

python core/main.py --gui

Expect a tkinter window, since core/gui_client.py is described as a tkinter panel. Without --gui the program runs in the system tray, and the README says a right-click on the icon switches Vibe tools. Configuration is persisted by core/config.py, which holds tool shortcuts and multi-device input mappings; the repository root includes config.example.json as the starting shape and config-tool.html as a browser-based visual editor that the README says needs no backend. Open config-tool.html directly in a browser to set tools, devices, mappings, feedback, Token Plan and Skills.

For a device beyond mouse and keyboard, uncomment the matching line in requirements.txt. A gamepad needs pygame, BLE needs bleak, serial IR needs pyserial, Broadlink WiFi IR needs broadlink, HID devices need hidapi or pywinusb, and network or IoT work needs paho-mqtt, websockets or flask. Voice input needs SpeechRecognition and pyaudio, with pocketsphinx for offline recognition or pvporcupine for wake-word mode, which the file notes requires an access_key. Nothing in the README states which Python version these pins target, so that is worth checking before you build a workflow on top of them.

Where vibe-mouse breaks down: adapters without documentation, and a beta surface

The clearest limitation is documentation depth per adapter. The README lists eight adapters and the optional dependency each one needs, but it does not document the configuration schema for any of them. If you want an MQTT button to trigger a code review Skill, you know paho-mqtt is the dependency and that core/adapters/network_adapter.py is the file, and that is roughly where the trail ends. You will be reading the adapter source. The same applies to the IR and HID paths, where the dependency list offers three alternatives (pyserial, broadlink, lirc for IR; hidapi, pywinusb for HID) without saying which one the shipped adapter imports.

The second limitation is the beta label, which the README applies to the project as a whole and separately to the Skill system and auto window detection. Features, APIs and configurations may change. No releases were retrieved, so there is no versioned artifact to pin against; the last push to main was on 2026-07-24, which makes the repository recent but gives you no stability contract. Auto window detection is a good example of the risk. It detects which AI IDE is in focus among Trae, Cursor, Windsurf, VS Code, DevEco and CodeArts, and switches shortcuts accordingly. On Windows that path depends on pywin32 306; the README does not describe the detection mechanism on macOS or Linux, so cross-platform behaviour there is unverified by the documentation.

Finally, the feedback layer is not equivalent across channels. Sound, overlay and tray notification are software. LED and vibration are listed as requiring custom setup, which means the hardware feedback feature is a hook rather than a finished capability.

vibe-mouse against AutoHotkey and Karabiner-Elements

AutoHotkey on Windows and Karabiner-Elements on macOS both remap input to actions, and both are mature, widely deployed and documented in far more detail than vibe-mouse. The difference is where the logic lives. AutoHotkey scripts are per-machine text files that describe key sequences and window conditions; Karabiner-Elements works at the driver level and rewrites keyboard events before applications see them. Neither ships an adapter abstraction, a unified event type, or a concept of a work mode that carries its own system prompt and feedback settings.

vibe-mouse's bet is that the interesting boundary is no longer the keyboard. Its adapter list reaches gamepads, BLE devices, IR remotes, Stream Deck style HID hardware and MQTT or WebSocket endpoints, and it pushes the result into an LLM-facing workflow through core/voice_llm.py and core/token_plan.py. That voice path is where the comparison gets concrete: the README says speech recognition results can be sent to Huawei Cloud Token Plan or MaaS running GLM, DeepSeek or Kimi, with an optional Prompt Refine step that converts colloquial speech into structured prompts and corrects homophones, accents and technical terminology. AutoHotkey can send keystrokes to a chat box; it has no opinion about what happens between your sentence and the model. If your need is purely remapping keys on one machine, AutoHotkey or Karabiner-Elements will be less work. If your need is one event model across heterogeneous hardware feeding an LLM workflow, that is the gap vibe-mouse is aimed at.

Licence, upgrade cost and the build script

vibe-mouse is AGPL-3.0. The README restates the practical consequence in its own words: all derivative works must remain open-source in compliance with the specified license. For a personal or laboratory setup this changes nothing. For a team that wants to embed the event router in a product, or to run a modified version as a network service, the copyleft obligation is the first thing to settle internally. This is a description of the licence, not legal advice; the LICENSE file at the repository root is the authoritative text.

Upgrade cost is hard to estimate because no releases were retrieved and there is no changelog. The dependency pins are exact (pynput==1.7.6, pystray==0.19.5, Pillow==10.2.0, pyinstaller==6.4.0, pywin32==306, psutil==5.9.8), which means upgrading one library is a deliberate edit rather than a range bump, and the beta warning means a pull from main can move the configuration schema under you. The repository does provide build.py, described as a one-click script that generates .exe or .app files, so packaging for distribution is at least anticipated. Whether a frozen build and a source run behave identically is not something the README addresses.

Editorial conclusion

Adopt vibe-mouse if you already drive an AI IDE by keyboard and want the same shortcuts reachable from a gamepad, a Stream Deck, an MQTT button or a voice command, and if AGPL-3.0 fits your distribution plans. Do not adopt it if you need a stable, documented API surface, a published release, or a tool whose install path is fully spelled out; the README is explicit that features, APIs and configurations may change, and no releases were retrieved. Before committing, verify three things yourself: whether pip install -r requirements.txt completes on your Python version, whether core/window_detector.py identifies your IDE on your OS, and whether the Skill templates under skills/ match the workflow you intend to bind to a button.

Frequently asked questions

Official sources

1. CSCB/vibe-mouse on GitHub
2. Issues
3. License: AGPL-3.0
4. README