{"id":16728273,"url":"https://github.com/tmc/righthand","last_synced_at":"2025-04-06T13:09:45.897Z","repository":{"id":180288421,"uuid":"663316943","full_name":"tmc/righthand","owner":"tmc","description":"RightHand - A GPT4 powered assistive tool.","archived":false,"fork":false,"pushed_at":"2025-01-14T05:15:29.000Z","size":75,"stargazers_count":109,"open_issues_count":2,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T12:09:07.734Z","etag":null,"topics":["assistive","assistive-technology","golang","gpt4","langchaingo"],"latest_commit_sha":null,"homepage":"","language":"Go","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/tmc.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}},"created_at":"2023-07-07T03:21:04.000Z","updated_at":"2025-03-15T09:16:55.000Z","dependencies_parsed_at":"2024-01-09T04:27:58.522Z","dependency_job_id":"361220d0-de78-432a-9f9e-b3576f7edf61","html_url":"https://github.com/tmc/righthand","commit_stats":null,"previous_names":["tmc/righthand"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmc%2Frighthand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmc%2Frighthand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmc%2Frighthand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmc%2Frighthand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmc","download_url":"https://codeload.github.com/tmc/righthand/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485287,"owners_count":20946398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["assistive","assistive-technology","golang","gpt4","langchaingo"],"created_at":"2024-10-12T23:09:35.022Z","updated_at":"2025-04-06T13:09:45.878Z","avatar_url":"https://github.com/tmc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RightHand - Voice Controlled Assistant for Mac\n\nRightHand is a voice controlled assistant for macOS, built using Go. With the power of RightHand, you can control your apps with voice commands, making your workflow smoother and more efficient. Whether it's opening a file, navigating through your apps, or even controlling your music player, everything can be done by your voice.\n\n## Quick Start (Copy/Paste)\n\n```bash\n# 1. Install Homebrew if you don't have it\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# 2. Install Go and PortAudio\nbrew install go portaudio\n\n# 3. Set up Go environment (if not already done)\necho 'export GOPATH=$HOME/go' \u003e\u003e ~/.zshrc\necho 'export PATH=$PATH:$GOPATH/bin' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n\n# 4. Install RightHand\ngo install github.com/tmc/righthand@latest\n\n# 5. Create config directory\nmkdir -p ~/.config/righthand\n\n# 6. Set your OpenAI API key (replace 'your-api-key-here' with your actual key)\necho 'export OPENAI_API_KEY=your-api-key-here' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n\n# 7. Run RightHand\nrighthand\n```\n\nAfter running, press Command+Control to start voice recognition. You may need to:\n1. Grant microphone permissions in System Settings \u003e Privacy \u0026 Security\n2. Replace 'your-api-key-here' with your actual OpenAI API key from https://platform.openai.com/api-keys\n\nRightHand leverages several powerful libraries such as `robotgo` for simulating keyboard input, `whisper` for voice recognition, `macdriver` for creating macOS applications using Go, and `langchaingo` for Language Learning Model interpretation. This software uses OpenAI's GPT-4 model to interpret transcriptions and generate corresponding commands.\n\nRighthand uses the lovely [macdriver](https://github.com/progrium/macdriver) project to enable MacOS api interactions.\n\n## Motivation\n\n\u003cimg width=\"218\" alt=\"cyborg-tmc\" src=\"https://github.com/tmc/righthand/assets/3977/5ac06331-48fc-4f53-8f0c-e1bfef000af8\"\u003e\n\nTwo weeks before initially publishing this I got into a pretty bad mountain biking accident. I built this for myself to better use my computer with a mix of one-handed typing and voice control.\n\n## Features\n\n1. **Voice Recognition**: Leveraging the `whisper` model, RightHand can accurately transcribe spoken words into text.\n2. **Natural Language Understanding**: RightHand uses `langchaingo` with OpenAI's GPT-4 model to understand the context of your speech and execute relevant actions.\n3. **Contextual Awareness**: RightHand adapts its responses based on the currently active application, providing a tailored user experience.\n4. **Hands-Free Control**: Perform actions such as opening files, navigating through apps, controlling media playback, and more using just your voice.\n\n## Installation\n\n### Prerequisites\n\n1. **Go**: Make sure you have Go 1.20 or later installed. You can download it from [golang.org](https://golang.org/dl/)\n\n2. **PortAudio**: Required for audio capture\n   - macOS: `brew install portaudio`\n   - Linux: `sudo apt-get install portaudio19-dev` (Ubuntu/Debian)\n\n3. **OpenAI API Key**: RightHand uses OpenAI's GPT-4 and Whisper models. You'll need an API key:\n   1. Get your API key from [OpenAI's website](https://platform.openai.com/api-keys)\n   2. Set it as an environment variable:\n      ```shell\n      export OPENAI_API_KEY='your-api-key-here'\n      ```\n\n### Installing RightHand\n\n1. Install the application:\n   ```shell\n   go install github.com/tmc/righthand@latest\n   ```\n\n2. Verify the installation:\n   ```shell\n   righthand -h\n   ```\n\n### Configuration\n\nRightHand will create a default configuration file at `~/.config/righthand/config.yaml` on first run. You can customize:\n\n- `llm_model`: The OpenAI model to use (default: \"gpt-4\")\n- `whisper_model`: The Whisper model to use (default: \"base.en\")\n- Program-specific voice commands\n\n### Troubleshooting\n\nIf you encounter issues:\n\n1. **Audio Capture Issues**:\n   - Ensure PortAudio is installed correctly\n   - Check microphone permissions in System Settings \u003e Privacy \u0026 Security \u003e Microphone\n\n2. **API Key Issues**:\n   - Verify your OpenAI API key is set correctly\n   - Check you have sufficient API credits\n\n3. **Build Issues**:\n   - Ensure all dependencies are installed: `go mod tidy`\n   - Make sure you're using a supported Go version\n\nFor more help, please [open an issue](https://github.com/tmc/righthand/issues).\n\n## Usage\n\n```shell\n$ righthand\n```\n\nYou can toggle the listening state of RightHand by pressing the control key while holding down the command key. RightHand will start transcribing your speech, interpret it, and execute commands on the active application.\n\n## Architecture\n\n```mermaid\ngraph TB\n  User[User] --\u003e|Voice Input + Hotkeys| RightHand\n\n  subgraph RightHand Application\n    RightHand --\u003e|Toggles Listening| Audio[audioutil]\n    Audio --\u003e|Collects Audio Data| Whisper[whisper.cpp]\n    Whisper --\u003e|Transcribes Audio| RightHand\n    RightHand --\u003e|Monitors Key Events| NSApp[macdriver/NSApp]\n    RightHand --\u003e|Handles Text| LLM[langchaingo]\n    RightHand --\u003e|Simulates Key Presses| Robotgo[robotgo]\n  end\n\n  LLM --\u003e|Interprets Transcription + Context| GPT4[OpenAI/GPT-4]\n  GPT4 --\u003e|Returns Key Presses| LLM\n\n  classDef library fill:#bbc;\n  class Audio,Cocoa,Robotgo,Whisper,LLM,NSApp library;\n```\n\n## Contributing\n\nContributions to RightHand are most welcome! If you have a feature request, bug report, or have developed a feature that you wish to be incorporated, please feel free to open a pull request.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmc%2Frighthand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmc%2Frighthand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmc%2Frighthand/lists"}