{"id":50266583,"url":"https://github.com/second-state/vibekeys_app","last_synced_at":"2026-05-27T14:11:36.681Z","repository":{"id":335184944,"uuid":"1144587128","full_name":"second-state/vibekeys_app","owner":"second-state","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-15T08:11:42.000Z","size":113,"stargazers_count":5,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T09:42:32.338Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://vibekeys.dev/","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/second-state.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-01-28T20:34:27.000Z","updated_at":"2026-05-12T00:39:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/second-state/vibekeys_app","commit_stats":null,"previous_names":["second-state/vibekeys_app"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/second-state/vibekeys_app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/second-state%2Fvibekeys_app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/second-state%2Fvibekeys_app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/second-state%2Fvibekeys_app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/second-state%2Fvibekeys_app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/second-state","download_url":"https://codeload.github.com/second-state/vibekeys_app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/second-state%2Fvibekeys_app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33569222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-27T14:11:35.894Z","updated_at":"2026-05-27T14:11:36.669Z","avatar_url":"https://github.com/second-state.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VibeKeys\n\nA BLE CLI tool for controlling the [VibeKeys MAX](https://github.com/L-jasmine/vibekeys) keyboard device. Connects via Bluetooth Low Energy (BLE) to send text, keymap configurations, ASR settings, and WiFi settings.\n\n[中文文档](docs/README.zh.md)\n\n## Installation\n\n### Download Pre-built Binary\n\nDownload the latest release from [GitHub Releases](https://github.com/second-state/vibekeys_app/releases).\n\n**Linux:**\n```bash\nwget https://github.com/second-state/vibekeys_app/releases/latest/download/vibekeys-linux-x64\nchmod +x vibekeys-linux-x64\nsudo mv vibekeys-linux-x64 /usr/local/bin/vibekeys\n```\n\n**macOS (ARM64):**\n```bash\nwget https://github.com/second-state/vibekeys_app/releases/latest/download/vibekeys-macos-arm64\nchmod +x vibekeys-macos-arm64\nsudo mv vibekeys-macos-arm64 /usr/local/bin/vibekeys\n```\n\n**Windows (PowerShell):**\n```powershell\nInvoke-WebRequest -Uri \"https://github.com/second-state/vibekeys_app/releases/latest/download/vibekeys-windows-x64.exe\" -OutFile \"vibekeys.exe\"\n# Add to PATH or move to a directory in PATH\n```\n\n### Build from Source\n\n```bash\n# Install dependencies (Linux)\nsudo apt-get install libudev-dev libdbus-1-dev pkg-config\n\n# Build\ncargo build --release\n\n# The binary will be at target/release/vibekeys\n```\n\n### Install Claude Code Plugin\n\nAlternatively, install the [VibeKeys plugin](https://github.com/second-state/marketplace) for Claude Code to automatically display status on your keyboard.\n\nRun these commands in your terminal:\n```bash\n# Add Second State marketplace\nclaude plugin marketplace add second-state/marketplace\n\n# Install VibeKeys plugin\nclaude plugin install vibekeys@second-state-tools\n```\n\n## Usage\n\n### Server Mode\n\nVibeKeys runs as a background server. Commands automatically start the server if it's not running, or communicate with the existing server instance.\n\n```bash\n# Start the server explicitly\nvibekeys start\n\n# Stop the server\nvibekeys stop\n```\n\n### Send text to keyboard display\n\n```bash\nvibekeys send \"Hello World\"\n```\n\n### Configure key mapping\n\n```bash\nvibekeys keymap \u003cKEY\u003e \u003cBINDING\u003e\n```\n\nConfigures one key at a time. The device merges it into the existing keymap.\n\n## Keymap Reference\n\n### Supported Keys\n\n| Key | Description |\n|-----|-------------|\n| `MIC` | Microphone key |\n| `CUSTOM` | Custom key |\n| `ESC` | Escape key |\n| `NEXT` | Next key |\n| `BACKSPACE` | Backspace key |\n| `YOLO` | Yolo key |\n| `ACCEPT` | Accept key |\n| `ROTATE` | Rotate key |\n\n### Binding Types\n\nBindings support two types: **combo** (keyboard shortcut) and **text** (text macro).\n\n#### Combo\n\nMaps a key to a keyboard shortcut.\n\n```bash\n# Single key\nvibekeys keymap ESC A          # Map to A key\nvibekeys keymap NEXT 1         # Map to digit 1\n\n# With modifiers\nvibekeys keymap ESC Ctrl+C     # Map to Ctrl+C\nvibekeys keymap CUSTOM Alt+Tab # Map to Alt+Tab\nvibekeys keymap NEXT Shift+A    # Map to Shift+A\n\n# Supported modifiers\n# Ctrl, Alt, Shift, Meta, Win, Cmd\n# Win and Cmd are automatically converted to Meta\n```\n\nGenerated JSON format:\n\n```json\n{\n  \"ESC\": {\n    \"type\": \"combo\",\n    \"modifiers\": [\"ctrl\"],\n    \"key\": \"C\",\n    \"raw\": \"Ctrl+C\"\n  }\n}\n```\n\n#### Text Macro\n\nMaps a key to a text string that gets typed when pressed.\n\n```bash\n# Use quotes to explicitly specify a text macro\nvibekeys keymap CUSTOM '\"hello world\"'\n\n# Input not recognized as a combo is treated as text\nvibekeys keymap CUSTOM \"some text here\"\n```\n\nGenerated JSON format:\n\n```json\n{\n  \"CUSTOM\": {\n    \"type\": \"text\",\n    \"value\": \"hello world\",\n    \"raw\": \"\\\"hello world\\\"\"\n  }\n}\n```\n\n#### Binding Resolution Rules\n\nInput is parsed with the following priority:\n\n1. **Quoted string** — content wrapped in `\"` or `'` is parsed as text\n2. **`+` separated combo** — parsed as combo when all modifier parts are valid (e.g. `Ctrl+Alt+Delete`)\n3. **Single uppercase letter or digit** — parsed as combo with no modifiers\n4. **Anything else** — defaults to text\n\n### Full Configuration Example\n\n```bash\n# MIC key → type text\nvibekeys keymap MIC '\"I am using Claude Code\"'\n\n# ESC key → Ctrl+C interrupt\nvibekeys keymap ESC Ctrl+C\n\n# NEXT key → open command palette\nvibekeys keymap NEXT Ctrl+Shift+P\n\n# CUSTOM key → Alt+Tab switch window\nvibekeys keymap CUSTOM Alt+Tab\n\n# BACKSPACE key → backspace\nvibekeys keymap BACKSPACE Backspace\n```\n\n## Hook Mode\n\nReads hook JSON events from stdin and forwards them to the keyboard display.\n\n```bash\n# For Claude Code (alias: hook)\nvibekeys claude\n\n# For Codex\nvibekeys codex\n```\n\n### Supported Events\n\n| Event | Display |\n|-------|---------|\n| `UserPromptSubmit` | `[user] \u003cfirst 80 chars of prompt\u003e` |\n| `Stop` | `[stopped]` or `[done] \u003clast message\u003e` |\n| `Notification` | `[notify] \u003cfirst 80 chars of message\u003e` |\n| `PreToolUse` | `[tool] \u003ctool name\u003e` |\n| `PostToolUse` | `[done] \u003ctool name\u003e` |\n| `SessionStart` | `[working]` |\n| `StopFailure` | `[error] \u003cerror type\u003e` |\n\n### Claude Code Configuration\n\nAdd to `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"vibekeys hook\" }]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"vibekeys hook\" }]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"vibekeys hook\" }]\n      }\n    ]\n  }\n}\n```\n\n## ASR Configuration\n\nConfigure the ASR (Automatic Speech Recognition) service for voice features:\n\n```bash\n# Interactive mode - prompts for provider selection and API key\nvibekeys asr-config\n\n# Direct configuration\nvibekeys asr-config --uri \u003cURI\u003e --api-key \u003cKEY\u003e --model \u003cMODEL\u003e\n\n# Example with OpenAI\nvibekeys asr-config --uri \"https://api.openai.com/v1/audio/transcriptions\" --api-key sk-xxxx --model whisper-1\n```\n\n### Supported Providers (for interactive mode)\n\n| Provider | Default URI | Default Model |\n|----------|-------------|---------------|\n| `openai` | `https://api.openai.com/v1/audio/transcriptions` | `whisper-1` |\n| `bytefuture` | `https://models.bytefuture.ai/v1/audio/transcriptions` | `groq/whisper-large-v3` |\n| `groq` | `https://api.groq.com/openai/v1/audio/transcriptions` | `whisper-large-vurbo` |\n| `glm` | `https://open.bigmodel.cn/api/paas/v4/audio/transcriptions` | `glm-asr-2512` |\n| `custom` | (required) | (required) |\n\n**Note:** The `platform` field sent to the device is always `\"whisper\"`. The provider selection in interactive mode only affects the default URI and model values for convenience.\n\n### Examples\n\n```bash\n# Interactive mode (recommended) - select from provider list with pre-configured defaults\nvibekeys asr-config\n\n# Configure with Groq (fast, often has free tier)\nvibekeys asr-config --uri \"https://api.groq.com/openai/v1/audio/transcriptions\" --api-key gsk_xxxx --model whisper-large-vurbo\n\n# Configure with OpenAI (specify URI and model explicitly)\nvibekeys asr-config --uri \"https://api.openai.com/v1/audio/transcriptions\" --api-key sk-xxxx --model whisper-1\n```\n\n## WiFi Configuration\n\nConfigure WiFi settings for the device:\n\n```bash\n# Interactive mode - prompts for SSID and password\nvibekeys wifi-config\n\n# Direct configuration\nvibekeys wifi-config \u003cSSID\u003e --pass \u003cPASSWORD\u003e\n\n# Open network (no password)\nvibekeys wifi-config MyNetwork\n```\n\n### Examples\n\n```bash\n# Interactive mode\nvibekeys wifi-config\n\n# Configure with password\nvibekeys wifi-config \"MyWiFi-5G\" --pass \"mypassword\"\n\n# Configure open network\nvibekeys wifi-config \"PublicWiFi\"\n```\n\n## HTTP API\n\nWhen the server is running, you can also use HTTP endpoints:\n\n```bash\n# Send text\ncurl -X POST http://127.0.0.1:42837/send -d \"Hello\"\n\n# Configure keymap\ncurl -X POST http://127.0.0.1:42837/keymap -d '{\"KEY\":\"value\"}'\n\n# Configure ASR\ncurl -X POST http://127.0.0.1:42837/asr-config -d '{\n  \"platform\": \"whisper\",\n  \"uri\": \"https://api.openai.com/v1/audio/transcriptions\",\n  \"api_key\": \"sk-xxxx\",\n  \"model\": \"whisper-1\"\n}'\n\n# Configure WiFi\ncurl -X POST http://127.0.0.1:42837/wifi-config -d '{\n  \"ssid\": \"MyWiFi\",\n  \"pass\": \"password\"\n}'\n```\n\n## ASR Result Handling\n\nWhen the device sends ASR transcription results via BLE notifications:\n- The text is automatically copied to your clipboard\n- An acknowledgement is sent back to the device\n\n## Logs\n\nVibeKeys stores log files in the following locations:\n\n- **Linux/macOS**: `~/.vibekeys/logs/`\n- **Windows**: `%USERPROFILE%\\.vibekeys\\logs` (usually `C:\\Users\\\u003cUsername\u003e\\.vibekeys\\logs`)\n\nLogs are automatically rotated:\n- Maximum 10MB per file\n- Keeps the 5 most recent log files\n\nYou can also view logs in real-time on stderr. Set the log level with the `RUST_LOG` environment variable.\n\n## Development\n\n```bash\n# Run with debug logging\nRUST_LOG=debug vibekeys send \"test\"\n\n# Build release\ncargo build --release\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecond-state%2Fvibekeys_app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecond-state%2Fvibekeys_app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecond-state%2Fvibekeys_app/lists"}