opencode-avatar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenCode Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# OpenCode Avatar Plugin
+
+A dynamic desktop avatar plugin for OpenCode that displays animated character reactions based on your coding activities.
+
+<div align="center"><img src="avatar.png" alt="Avatar" width="200" /></div>
+
+## Features
+
+- **Dynamic Avatar Display**: Desktop character that reacts to your OpenCode usage
+- **Thinking Animation**: Shows "thinking hard" when you send messages
+- **Tool-Based Reactions**: Avatar changes pose based on which tools are being used
+- **Smart Caching**: Generated avatars are cached for instant loading
+- **Non-Intrusive**: Appears without stealing focus, stays on top
+- **Auto-Shutdown**: Automatically closes when OpenCode exits
+- **Toast Notifications**: Shows progress for avatar generation
+
+## Installation
+
+### Option 1: From NPM (Recommended)
+
+```bash
+npm install -g opencode-avatar
+```
+
+Then add to your OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-avatar"]
+}
+```
+
+### Option 2: Local Development
+
+1. Clone this repository
+2. Run `npm install`
+3. Run `npm run build`
+4. Copy to your OpenCode plugins directory:
+   - Project: `.opencode/plugins/`
+   - Global: `~/.config/opencode/plugins/`
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the plugin directory:
+
+```env
+FAL_KEY=your_fal_ai_api_key_here
+```
+
+Get your FAL.ai API key from [fal.ai](https://fal.ai).
+
+### Avatar Images
+
+The plugin comes with a default avatar (`avatar.png`). Place custom avatars in the plugin directory:
+
+- `avatar.png` - Default avatar (required)
+- `avatar.svg` - Fallback avatar (optional)
+
+## How It Works
+
+### Avatar States
+
+| State | Trigger | Description |
+|-------|---------|-------------|
+| **Default** | Session idle | Neutral pose, waiting for input |
+| **Thinking** | User message | "Thinking hard" animation while processing |
+| **Tool Active** | Tool execution | Pose based on current tool (write, read, etc.) |
+
+### Tool Mappings
+
+The avatar automatically detects which tools you're using and shows appropriate reactions:
+
+| Tool | Avatar Pose |
+|------|-------------|
+| `write` | Writing with pencil |
+| `read` | Reading a book |
+| `edit` | Editing with scissors |
+| `glob` | Searching with magnifying glass |
+| `grep` | Detective searching |
+| `bash` | Hacker typing |
+| `webfetch` | Surfing the web |
+
+### File Naming
+
+Avatar images are cached with predictable filenames:
+- `avatar_write.png` - Writing tool
+- `avatar_read.png` - Reading tool
+- `avatar_thinking_hard.png` - Thinking state
+
+## Usage
+
+### Basic Usage
+
+1. Install the plugin
+2. Configure your FAL.ai API key
+3. Start OpenCode - avatar appears automatically
+4. Send messages - avatar shows thinking animation
+5. Use tools - avatar reacts to each tool
+
+### Manual Control
+
+The avatar responds automatically, but you can also:
+
+- **Show/Hide**: Click the system tray icon
+- **Quit**: Right-click tray icon → Quit
+- **Move**: Drag the avatar window to reposition
+
+### Logs and Debugging
+
+Check the console output for detailed information.
+
+The output shows:
+- Plugin initialization
+- Avatar generation requests
+- Tool execution detection
+- Electron process lifecycle
+
+## Architecture
+
+### Components
+
+```
+├── index.ts          # Main plugin logic
+├── electron.ts       # Desktop window management
+├── avatar.png        # Default avatar image
+└── dist/            # Compiled output
+```
+
+### Communication Flow
+
+1. **Plugin** detects OpenCode events (messages, tool usage)
+2. **HTTP** requests sent to Electron process
+3. **Electron** generates/updates avatar via FAL.ai API
+4. **Window** displays new avatar image
+5. **Heartbeat** ensures Electron stays alive
+
+### Safety Features
+
+- **Duplicate Prevention**: Only one avatar instance runs
+- **Multi-Instance Support**: Multiple OpenCode instances share the same avatar window
+- **Auto-Shutdown**: Closes when OpenCode exits
+- **Focus Protection**: Never steals keyboard focus
+- **Error Handling**: Graceful fallbacks on failures
+
+## API Reference
+
+### Plugin Hooks
+
+- `chat.message` - Detects user input
+- `tool.execute.before` - Detects tool usage
+- `event` - Handles session state changes
+
+### HTTP Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/heartbeat` | POST | Keep-alive signal |
+| `/set-avatar` | POST | Change displayed avatar |
+| `/generate-avatar` | POST | Generate new avatar |
+| `/shutdown` | POST | Graceful shutdown |
+
+## Troubleshooting
+
+### Avatar Not Showing
+
+1. Check console output for errors
+2. Verify FAL.ai API key in `.env`
+3. Ensure port 47291 is available
+4. Try restarting OpenCode
+
+### Avatar Generation Failing
+
+1. Check FAL.ai API key validity
+2. Verify internet connection
+3. Check available disk space for cache
+4. Look for API rate limits
+
+### Focus Issues
+
+- Avatar should never steal focus
+- If it does, check Electron window settings
+- Try `focusable: false` in window config
+
+### Performance Issues
+
+- First avatar generation takes ~10-30 seconds
+- Subsequent loads are instant (cached)
+- Reduce avatar size for faster generation
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+# Test Electron window
+npm run start
+
+# Test with thinking avatar
+npm run start:thinking
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Credits
+
+- **FAL.ai** - AI image generation
+- **Electron** - Desktop application framework
+- **OpenCode** - Plugin ecosystem
+
+## Changelog
+
+### v0.1.0
+- Initial release
+- Basic avatar display
+- Thinking animation
+- Tool-based reactions
+- Caching system
+- Auto-shutdown
+- Focus protection