From 4b3eea54f7a29ea093fbe44d53a5647cae1d12f6 Mon Sep 17 00:00:00 2001
From: CJ Pais <cj@cjpais.com>
Date: Wed, 12 Feb 2025 18:13:12 -0800
Subject: [PATCH] docs: update README with flexible LLM configuration and
 environment variable support

---
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 142 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 102e366..b0cf7bf 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