Enhance your OpenCode experience with nostalgic Warcraft II unit sounds!

This plugin plays authentic Warcraft II unit audio clips from both Alliance and Horde factions when your OpenCode session goes idle, bringing back memories of commanding orcs, knights, trolls, and mages in the classic RTS game.

Quick Start • Documentation • Contributing

• 🎵 110 Authentic Sounds: Complete collection of Warcraft II Alliance and Horde unit voices (56 Alliance, 54 Horde)
• 📦 Bundled Sounds: Includes pre-bundled WAV assets copied into a per-user data directory on first use (no runtime network dependency by default)
• 🎲 Random Selection: Plays a different sound each time for variety
• ⚔️ Faction Choice: Choose Alliance, Horde, or both factions
• 💻 Cross-Platform: Works on macOS and Linux
• 🎨 Toast Notifications: In-app toast notifications with authentic voice lines (e.g., "Yes, milord?" / "Work, work.")
• 🚀 Automated Releases: Fully automated CI/CD pipeline with AI-powered version management
• 📚 Comprehensive Documentation: Complete documentation suite for users, developers, and operators
• 🎮 Unit Variety: Includes voices from:
  • Alliance: Human Units (peasants, knights, mages), Elven Archers, Dwarven Demolition Squad, Naval Units
  • Horde: Orcs, Death Knights, Dragons, Goblin Sappers, Ogres, Ogre-Mages, Troll Axethrowers, Naval Units
  • Special completion sounds

This project includes comprehensive documentation for all users:

• 📚 Documentation Site - Complete documentation (recommended)
• [🗺️ Documentation Map](https://pantheon-org.github.io/opencode-warcraft-notifications/documentation-map/ - Navigation guide
• [⚡ Quick Reference](https://pantheon-org.github.io/opencode-warcraft-notifications/quick-reference/ - Common tasks and commands

• [User Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/user-guide/ - Installation, configuration, and usage
• FAQ - Common questions and answers
• [Troubleshooting](https://pantheon-org.github.io/opencode-warcraft-notifications/troubleshooting/ - Problem resolution

• [Development Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/development/ - Setup, workflow, and contributing
• [API Documentation](https://pantheon-org.github.io/opencode-warcraft-notifications/api/ - Complete technical reference
• [Architecture](https://pantheon-org.github.io/opencode-warcraft-notifications/architecture/ - System design and components
• [Onboarding](https://pantheon-org.github.io/opencode-warcraft-notifications/onboarding/ - New contributor guide

• [Deployment Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/deployment/ - Installation and operations
• [CI/CD Pipeline](https://pantheon-org.github.io/opencode-warcraft-notifications/pipeline/ - Complete pipeline technical reference
• [GitHub Workflows](https://pantheon-org.github.io/opencode-warcraft-notifications/github-workflows/ - CI/CD setup guides

• Security Policy - Security and vulnerability reporting
• Contributing Guide - How to contribute
• GitHub Releases - Version history and release notes

Add the plugin to your OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@pantheon-ai/opencode-warcraft-notifications"]
}

opencode

When your OpenCode session goes idle, you'll hear Warcraft II sounds and see a notification.

On first run, the plugin automatically copies bundled WAV files to your local plugin data directory (no network downloads required).

• Configure factions: See Configuration below
• Customize sounds: See User Guide - Customization
• Troubleshoot: See [Troubleshooting Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/troubleshooting/

Choose which faction sounds to play:

• "alliance" - Play only Alliance unit sounds
• "horde" - Play only Horde unit sounds
• "both" - Play random sounds from both factions (default)

Project-specific (.opencode/plugin.json):

{
  "@pantheon-ai/opencode-warcraft-notifications": {
    "faction": "alliance"
  }
}

Global (~/.config/opencode/plugin.json):

{
  "@pantheon-ai/opencode-warcraft-notifications": {
    "faction": "horde"
  }
}

By default, the plugin shows toast notifications with the Warcraft II voice line as the title when your session goes idle. You can disable this feature if you prefer silent mode (sound only):

{
  "@pantheon-ai/opencode-warcraft-notifications": {
    "showDescriptionInToast": false
  }
}

Example with toast enabled (default):

• Toast Title: "Yes, milord?"
• Toast Message: Created notification system with sound descriptions
• Sound plays: human_selected1.wav

Example with toast disabled:

• Sound plays: human_selected1.wav
• No visual notification shown

You can customize where sound files are stored:

{
  "@pantheon-ai/opencode-warcraft-notifications": {
    "soundsDir": "/path/to/custom/sounds",
    "faction": "both",
    "showDescriptionInToast": true
  }
}

1. Project-specific plugin.json soundsDir setting
2. SOUNDS_DATA_DIR environment variable
3. Platform-specific default directory

For complete configuration options and examples, see:

• User Guide - Configuration
• API Documentation - Configuration
• [Schemas Documentation](https://pantheon-org.github.io/opencode-warcraft-notifications/schemas/

1. Idle Detection: When your OpenCode session goes idle, the plugin triggers
2. Sound Selection: Randomly selects a Warcraft II unit sound from your configured faction(s)
3. Sound Playback: Plays the sound using platform-specific audio tools
4. Toast Notification: Shows an in-app toast with the voice line as the title (e.g., "Yes, milord?") and your session summary

The plugin includes 110+ authentic sounds from both factions, including:

• Unit selection sounds ("Yes, my lord?" / "Zug zug!")
• Acknowledgment sounds ("For the Alliance!" / "Lok tar!")
• Work completion sounds ("Work complete!" / "Jobs done!")

Alliance Units: Peasants, Knights, Mages, Elven Archers, Dwarven Demolition Squad, Naval Units

Horde Units: Orcs, Death Knights, Dragons, Goblin Sappers, Ogres, Ogre-Mages, Troll Axethrowers, Naval Units

For the complete list of sounds and examples, see:

• User Guide - Sound Factions
• Architecture - Sound Data

• macOS: ✅ Full support - Uses afplay for audio playback
• Linux: ✅ Full support - Uses canberra-gtk-play for audio playback
• Windows: ⚠️ Partial support - Toast notifications work, sound playback planned for future release
• Toast Notifications: ✅ Cross-platform using OpenCode's built-in toast system

Current: Partial support

• Plugin loads and initializes on Windows
• Configuration and sound file management work
• Toast notifications work via OpenCode TUI
• Sound playback not yet implemented (logs warning)

Planned: Full sound playback support in future release

For detailed platform-specific setup and troubleshooting, see:

• User Guide - Installation
• Deployment Guide - Platform-Specific Setup

All sound files are bundled with the plugin from Warcraft II archives. The plugin:

• Includes 110+ pre-bundled WAV files in the data/ directory
• Copies files to local storage on first use
• No network downloads required during runtime
• Ensures authentic game audio quality

For technical details, see:

• Architecture - Bundled Sounds
• Deployment - Sound Management

To get the latest version:

(cd ~ && sed -i.bak '/"@pantheon-ai\/opencode-warcraft-notifications"/d' .cache/opencode/package.json && \
rm -rf .cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications && \
echo "Plugin update script finished successfully.")

opencode  # Reinstalls latest

For more details, see the User Guide - Updating.

For development instructions, see the [Development Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/development/.

Quick start:

# Run tests
bun test

# Run type checking
bun run type-check

# Run linting
bun run lint

This project uses a two-directory approach for documentation:

• ./docs/ - Source documentation (markdown files)
• ./pages/ - Astro Starlight build configuration

To work with documentation:

# Transform docs from source to build directory
bun run pages:transform

# Start development server with live reload
bun run pages:dev

# Build static site for production
bun run pages:build

# Preview production build
bun run pages:preview

Documentation Flow:

1. Edit markdown files in ./docs/
2. Run bun run pages:transform to copy to ./pages/src/content/docs/
3. Run bun run pages:build to generate static site in ./pages/dist/
4. GitHub Actions automatically deploys to docs branch → GitHub Pages

For more details, see the Development Guide - Documentation.

To debug the plugin and see detailed logging:

# Enable debug logging
DEBUG_OPENCODE=1 opencode

# Test toast notifications manually
bun run test-toast-manual.ts

The debug mode will log:

• All event types received by the plugin
• Message text saved for idle summaries
• Session idle events and handling
• Toast notification attempts and results
• Sound file selection and playback

See the [Development Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/development/ for complete development workflow, testing strategies, and contributing guidelines.

Having issues? Check these resources:

• [Troubleshooting Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/troubleshooting/ - Common issues and solutions
• User Guide - FAQ - Frequently asked questions
• Deployment Guide - Troubleshooting - Deployment and configuration issues

We welcome contributions! Please see:

• Contributing Guide - How to contribute
• [Development Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/development/ - Development setup and workflow
• [Onboarding Guide](https://pantheon-org.github.io/opencode-warcraft-notifications/onboarding/ - New contributor onboarding
• [Architecture Documentation](https://pantheon-org.github.io/opencode-warcraft-notifications/architecture/ - System design
• [API Documentation](https://pantheon-org.github.io/opencode-warcraft-notifications/api/ - Technical reference

MIT License - see LICENSE file for details.

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Live Documentation
• Source Docs: Documentation Source

"Work complete!" - Warcraft II Peasant
"Zug zug!" - Warcraft II Orc