vikingowl
384dd016a0
BREAKING: Restructure from monolithic binary to modular plugin ecosystem Architecture changes: - Convert to Cargo workspace with crates/ directory - Create owlry-plugin-api crate with ABI-stable interface (abi_stable) - Move core binary to crates/owlry/ - Extract providers to native plugin crates (13 plugins) - Add owlry-lua crate for Lua plugin runtime Plugin system: - Plugins loaded from /usr/lib/owlry/plugins/*.so - Widget providers refresh automatically (universal, not hardcoded) - Per-plugin config via [plugins.<name>] sections in config.toml - Backwards compatible with [providers] config format New features: - just install-local: build and install core + all plugins - Plugin config: weather and pomodoro read from [plugins.*] - HostAPI for plugins: notifications, logging Documentation: - Update README with new package structure - Add docs/PLUGINS.md with all plugin documentation - Add docs/PLUGIN_DEVELOPMENT.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
331 lines
6.9 KiB
Markdown
331 lines
6.9 KiB
Markdown
# Available Plugins
|
|
|
|
Owlry's functionality is provided through a modular plugin system. This document describes all available plugins.
|
|
|
|
## Plugin Categories
|
|
|
|
### Static Providers
|
|
|
|
Static providers load their items once at startup (and on manual refresh). They're best for data that doesn't change frequently.
|
|
|
|
### Dynamic Providers
|
|
|
|
Dynamic providers evaluate queries in real-time. Each keystroke triggers a new query, making them ideal for calculations, searches, and other interactive features.
|
|
|
|
### Widget Providers
|
|
|
|
Widget providers display persistent information at the top of results (weather, media controls, timers).
|
|
|
|
---
|
|
|
|
## Core Plugins
|
|
|
|
### owlry-plugin-calculator
|
|
|
|
**Type:** Dynamic
|
|
**Prefix:** `:calc`, `=`, `calc `
|
|
**Package:** `owlry-plugin-calculator`
|
|
|
|
Evaluate mathematical expressions in real-time.
|
|
|
|
**Examples:**
|
|
```
|
|
= 5 + 3 → 8
|
|
= sqrt(16) → 4
|
|
= sin(pi/2) → 1
|
|
= 2^10 → 1024
|
|
= (1 + 0.05)^12 → 1.7958...
|
|
```
|
|
|
|
**Supported operations:**
|
|
- Basic: `+`, `-`, `*`, `/`, `^` (power), `%` (modulo)
|
|
- Functions: `sin`, `cos`, `tan`, `asin`, `acos`, `atan`
|
|
- Functions: `sqrt`, `abs`, `floor`, `ceil`, `round`
|
|
- Functions: `ln`, `log`, `log10`, `exp`
|
|
- Constants: `pi`, `e`
|
|
|
|
---
|
|
|
|
### owlry-plugin-system
|
|
|
|
**Type:** Static
|
|
**Prefix:** `:sys`
|
|
**Package:** `owlry-plugin-system`
|
|
|
|
System power and session management commands.
|
|
|
|
**Actions:**
|
|
| Name | Description | Command |
|
|
|------|-------------|---------|
|
|
| Shutdown | Power off | `systemctl poweroff` |
|
|
| Reboot | Restart | `systemctl reboot` |
|
|
| Reboot into BIOS | UEFI setup | `systemctl reboot --firmware-setup` |
|
|
| Suspend | Sleep (RAM) | `systemctl suspend` |
|
|
| Hibernate | Sleep (disk) | `systemctl hibernate` |
|
|
| Lock Screen | Lock session | `loginctl lock-session` |
|
|
| Log Out | End session | `loginctl terminate-session self` |
|
|
|
|
---
|
|
|
|
### owlry-plugin-ssh
|
|
|
|
**Type:** Static
|
|
**Prefix:** `:ssh`
|
|
**Package:** `owlry-plugin-ssh`
|
|
|
|
SSH hosts parsed from `~/.ssh/config`.
|
|
|
|
**Features:**
|
|
- Parses `Host` entries from SSH config
|
|
- Ignores wildcards (`Host *`)
|
|
- Opens connections in your configured terminal
|
|
|
|
---
|
|
|
|
### owlry-plugin-clipboard
|
|
|
|
**Type:** Static
|
|
**Prefix:** `:clip`
|
|
**Package:** `owlry-plugin-clipboard`
|
|
**Dependencies:** `cliphist`, `wl-clipboard`
|
|
|
|
Clipboard history integration with cliphist.
|
|
|
|
**Features:**
|
|
- Shows last 50 clipboard entries
|
|
- Previews text content (truncated to 80 chars)
|
|
- Select to copy back to clipboard
|
|
|
|
---
|
|
|
|
### owlry-plugin-emoji
|
|
|
|
**Type:** Static
|
|
**Prefix:** `:emoji`
|
|
**Package:** `owlry-plugin-emoji`
|
|
**Dependencies:** `wl-clipboard`
|
|
|
|
400+ searchable emoji with keywords.
|
|
|
|
**Examples:**
|
|
```
|
|
:emoji heart → ❤️ 💙 💚 💜 ...
|
|
:emoji smile → 😀 😃 😄 😁 ...
|
|
:emoji fire → 🔥
|
|
```
|
|
|
|
---
|
|
|
|
### owlry-plugin-scripts
|
|
|
|
**Type:** Static
|
|
**Prefix:** `:script`
|
|
**Package:** `owlry-plugin-scripts`
|
|
|
|
User scripts from `~/.local/share/owlry/scripts/`.
|
|
|
|
**Setup:**
|
|
```bash
|
|
mkdir -p ~/.local/share/owlry/scripts
|
|
cat > ~/.local/share/owlry/scripts/backup.sh << 'EOF'
|
|
#!/bin/bash
|
|
rsync -av ~/Documents /backup/
|
|
notify-send "Backup complete"
|
|
EOF
|
|
chmod +x ~/.local/share/owlry/scripts/backup.sh
|
|
```
|
|
|
|
---
|
|
|
|
### owlry-plugin-bookmarks
|
|
|
|
**Type:** Static
|
|
**Prefix:** `:bm`
|
|
**Package:** `owlry-plugin-bookmarks`
|
|
|
|
Browser bookmarks from Chromium-based browsers.
|
|
|
|
**Supported browsers:**
|
|
- Google Chrome
|
|
- Brave
|
|
- Microsoft Edge
|
|
- Vivaldi
|
|
- Chromium
|
|
|
|
---
|
|
|
|
### owlry-plugin-websearch
|
|
|
|
**Type:** Dynamic
|
|
**Prefix:** `:web`, `?`, `web `
|
|
**Package:** `owlry-plugin-websearch`
|
|
|
|
Web search with configurable search engine.
|
|
|
|
**Examples:**
|
|
```
|
|
? rust programming → Search for "rust programming"
|
|
web linux tips → Search for "linux tips"
|
|
```
|
|
|
|
**Configuration:**
|
|
```toml
|
|
[providers]
|
|
search_engine = "duckduckgo" # or: google, bing, startpage
|
|
# custom_search_url = "https://search.example.com/?q={}"
|
|
```
|
|
|
|
---
|
|
|
|
### owlry-plugin-filesearch
|
|
|
|
**Type:** Dynamic
|
|
**Prefix:** `:file`, `/`, `find `
|
|
**Package:** `owlry-plugin-filesearch`
|
|
**Dependencies:** `fd` (recommended) or `mlocate`
|
|
|
|
Real-time file search.
|
|
|
|
**Examples:**
|
|
```
|
|
/ .bashrc → Find files matching ".bashrc"
|
|
find config → Find files matching "config"
|
|
```
|
|
|
|
**Configuration:**
|
|
```toml
|
|
[providers]
|
|
file_search_max_results = 50
|
|
# file_search_paths = ["/home", "/etc"] # Custom search paths
|
|
```
|
|
|
|
---
|
|
|
|
### owlry-plugin-systemd
|
|
|
|
**Type:** Static (with submenu)
|
|
**Prefix:** `:uuctl`
|
|
**Package:** `owlry-plugin-systemd`
|
|
**Dependencies:** `systemd`
|
|
|
|
User systemd services with action submenus.
|
|
|
|
**Features:**
|
|
- Lists user services (`systemctl --user`)
|
|
- Shows service status (running/stopped/failed)
|
|
- Submenu actions: start, stop, restart, enable, disable, status
|
|
|
|
**Usage:**
|
|
1. Search `:uuctl docker`
|
|
2. Select a service
|
|
3. Choose action from submenu
|
|
|
|
---
|
|
|
|
## Widget Plugins
|
|
|
|
### owlry-plugin-weather
|
|
|
|
**Type:** Widget (Static)
|
|
**Package:** `owlry-plugin-weather`
|
|
|
|
Current weather displayed at the top of results.
|
|
|
|
**Supported APIs:**
|
|
- wttr.in (default, no API key required)
|
|
- OpenWeatherMap (requires API key)
|
|
- Open-Meteo (no API key required)
|
|
|
|
**Configuration:**
|
|
```toml
|
|
[plugins.weather]
|
|
provider = "wttr.in" # or: openweathermap, open-meteo
|
|
location = "London" # city name or "lat,lon" (empty for auto-detect)
|
|
# api_key = "..." # Required for OpenWeatherMap
|
|
```
|
|
|
|
**Features:**
|
|
- Temperature, condition, humidity, wind speed
|
|
- Weather icons from Weather Icons font
|
|
- 15-minute cache
|
|
- Click to open detailed forecast
|
|
|
|
---
|
|
|
|
### owlry-plugin-media
|
|
|
|
**Type:** Widget (Static)
|
|
**Package:** `owlry-plugin-media`
|
|
|
|
MPRIS media player controls.
|
|
|
|
**Features:**
|
|
- Shows currently playing track
|
|
- Artist, title, album art
|
|
- Play/pause, next, previous controls
|
|
- Works with Spotify, Firefox, VLC, etc.
|
|
|
|
---
|
|
|
|
### owlry-plugin-pomodoro
|
|
|
|
**Type:** Widget (Static)
|
|
**Package:** `owlry-plugin-pomodoro`
|
|
|
|
Pomodoro timer with work/break cycles.
|
|
|
|
**Configuration:**
|
|
```toml
|
|
[plugins.pomodoro]
|
|
work_mins = 25 # Work session duration (default: 25)
|
|
break_mins = 5 # Break duration (default: 5)
|
|
```
|
|
|
|
**Features:**
|
|
- Configurable work session duration
|
|
- Configurable break duration
|
|
- Session counter
|
|
- Desktop notifications on phase completion
|
|
- Persistent state across sessions
|
|
|
|
**Controls:**
|
|
- Start/Pause timer
|
|
- Skip to next phase
|
|
- Reset timer and sessions
|
|
|
|
---
|
|
|
|
## Bundle Packages
|
|
|
|
For convenience, plugins are available in bundle meta-packages:
|
|
|
|
| Bundle | Plugins |
|
|
|--------|---------|
|
|
| `owlry-essentials` | calculator, system, ssh, scripts, bookmarks |
|
|
| `owlry-widgets` | weather, media, pomodoro |
|
|
| `owlry-tools` | clipboard, emoji, websearch, filesearch, systemd |
|
|
| `owlry-full` | All of the above |
|
|
|
|
```bash
|
|
# Install everything
|
|
yay -S owlry-full
|
|
|
|
# Or pick a bundle
|
|
yay -S owlry-essentials owlry-widgets
|
|
```
|
|
|
|
---
|
|
|
|
## Runtime Packages
|
|
|
|
For custom user plugins written in Lua or Rune:
|
|
|
|
| Package | Description |
|
|
|---------|-------------|
|
|
| `owlry-lua` | Lua 5.4 runtime for user plugins |
|
|
| `owlry-rune` | Rune runtime for user plugins |
|
|
|
|
User plugins are placed in `~/.config/owlry/plugins/`.
|
|
|
|
See [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) for creating custom plugins.
|