Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

docs: update README with flexible LLM configuration and environment variable support

CJ Pais4b3eea54f7a2
diff --git a/README.md b/README.md
index 102e3668..b0cf7bf1 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,145 @@
-# Tauri + React + Typescript
+# Handy App
-This template should help get you started developing with Tauri, React and Typescript in Vite.
+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.
-## Recommended IDE Setup
+## Core Purpose
-- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+- πŸ“¦ 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
\ No newline at end of file