145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
# Handy (it's a handy app)
|
|
|
|
A user-friendly desktop application that makes the [Handy voice assistant](https://github.com/cjpais/handy) more accessible and easier to distribute. This app provides a native interface for voice-controlled AI interactions, making it simple for users to get started without dealing with Python setup.
|
|
|
|
## Core Purpose
|
|
|
|
- 📦 Make Handy easily distributable and installable for everyone
|
|
- 🎯 Provide the same powerful voice-controlled AI capabilities as the CLI version
|
|
- 🧠 Support flexible LLM configuration (local or remote)
|
|
- ⚙️ Offer simple configuration for keyboard shortcuts
|
|
- 🪟 Enable floating windows for AI chat interactions
|
|
|
|
## Key Features
|
|
|
|
### V1 (Primary Focus)
|
|
- 🎙️ Voice-to-text transcription using MLX Whisper
|
|
- 🤖 Flexible AI model support:
|
|
- Remote APIs (OpenRouter, OpenAI, Anthropic, etc.)
|
|
- Local models (llama.cpp, MLX models, etc.)
|
|
- Custom API endpoints
|
|
- 💬 Floating chat windows for AI interactions
|
|
- ⚡ Native desktop app experience
|
|
- ⚙️ User-friendly configuration UI
|
|
|
|
### Future Enhancements
|
|
- 📋 Smart clipboard management for context
|
|
- 📸 Screenshot capabilities
|
|
- 🔄 MCP provider functionality
|
|
- 📝 Extended context window management
|
|
|
|
## Requirements
|
|
|
|
- macOS (currently macOS-only)
|
|
- Internet connection for remote AI services (optional)
|
|
- API keys for remote services (optional)
|
|
|
|
## Quick Start
|
|
|
|
1. Download the latest release from the releases page
|
|
2. Install the application
|
|
3. Launch and grant necessary permissions
|
|
4. Configure your AI preferences:
|
|
- Use existing environment variables if set
|
|
- Configure through UI:
|
|
- Select local or remote models
|
|
- Add API keys if needed
|
|
- Customize model parameters
|
|
5. Start using voice commands with the default shortcuts!
|
|
|
|
## Environment Variables
|
|
|
|
The app automatically detects and uses common environment variables:
|
|
```bash
|
|
# Remote API Keys
|
|
OPENAI_API_KEY=your_openai_key
|
|
OPENROUTER_API_KEY=your_openrouter_key
|
|
ANTHROPIC_API_KEY=your_anthropic_key
|
|
|
|
# Model Configuration
|
|
DEFAULT_MODEL=gpt-4 # Example model choice
|
|
MODEL_BASE_URL=http://localhost:8080 # For custom API endpoints
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The app allows you to configure:
|
|
- AI Model Settings:
|
|
- Model provider (local or remote)
|
|
- API endpoints and keys
|
|
- Model parameters (temperature, context length, etc.)
|
|
- Keyboard shortcuts
|
|
- Window preferences for AI chat
|
|
- Transcription settings
|
|
|
|
## Development Setup
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone [repository-url]
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
# Using npm
|
|
npm install
|
|
|
|
# Or using Bun
|
|
bun install
|
|
```
|
|
|
|
3. Run the development version:
|
|
```bash
|
|
npm run tauri dev
|
|
# or
|
|
bun run tauri dev
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **Frontend**: React + TypeScript for the user interface
|
|
- **Backend**: Rust-based Tauri for system integration
|
|
- **Key Plugins**:
|
|
- `@tauri-apps/plugin-global-shortcut`: Keyboard shortcut management
|
|
- `tauri-plugin-macos-permissions-api`: System permissions
|
|
- `@tauri-apps/plugin-window`: Multi-window management
|
|
|
|
## Comparison with CLI Version
|
|
|
|
This desktop app provides the same core functionality as the [original Handy CLI](https://github.com/cjpais/handy) but with these improvements:
|
|
- No Python setup required
|
|
- Easy installation process
|
|
- Native desktop experience
|
|
- Configurable through UI
|
|
- Floating chat windows
|
|
- More flexible LLM configuration
|
|
- Future support for visual features
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! The priority is currently on:
|
|
1. Core functionality parity with CLI version
|
|
2. Installation and configuration experience
|
|
3. Chat window implementation
|
|
4. Model configuration interface
|
|
|
|
## Roadmap
|
|
|
|
### V1
|
|
- [ ] Core voice-to-text functionality
|
|
- [ ] Flexible AI model integration
|
|
- [ ] Settings configuration
|
|
- [ ] Easy installation process
|
|
- [ ] Environment variable support
|
|
|
|
### Future
|
|
- [ ] Basic chat windows
|
|
- [ ] Clipboard management integration
|
|
- [ ] Screenshot capabilities
|
|
- [ ] MCP provider functionality
|
|
- [ ] Extended context management
|
|
- [ ] Multiple chat window layouts
|
|
|
|
## Related Projects
|
|
|
|
- [Handy CLI](https://github.com/cjpais/handy) - The original command-line interface version
|