Native Launcher features a powerful plugin system that extends its functionality beyond simple application launching.

The plugin system is designed around these principles:

• Priority-based: Plugins are sorted by priority (highest first)
• Keyword-driven: Use @prefix commands to target specific plugins
• Extensible: Add new plugins without modifying core code
• Performance-focused: Plugins are optimized for fast startup and search

Priority: 1000 (highest)
Command: @app
Description: Searches desktop applications from /usr/share/applications and ~/.local/share/applications.

Features:

• Fuzzy matching on app name, generic name, and keywords
• Usage tracking for frecency-based scoring
• Icon support with caching
• Desktop actions support (inline)
• Pins/Favorites support (Ctrl+P) to surface pinned apps first on empty query and slightly boost during typed searches

Example:

firefox              → Launch Firefox
@app code            → Launch VS Code

Priority: 10000 (note: lower number in code = higher display priority)
Command: @cal
Description: Evaluates mathematical expressions using evalexpr.

Features:

• Basic arithmetic: +, -, *, /, ^, %
• Parentheses support
• Mathematical functions: sqrt(), sin(), cos(), etc.
• Auto-detection (no prefix needed)

Example:

2+2*5                → 12
@cal sqrt(16)        → 4
5^2                  → 25

Priority: 850
Commands: @calc, @convert, @time, @currency
Description: Natural language calculations with clipboard integration.

Features:

• Time calculations: Past/future times, timezone info
• Unit conversions: Time, distance, weight, temperature
• Currency exchange: 10+ major currencies
• Clipboard copy: Press Enter to copy with notification

Examples:

1 hour ago                   → 2024-10-21 21:30:00
150 days to years            → 0.41 years
5 km to miles                → 3.11 miles
100 USD to EUR               → 92.00 EUR
32 fahrenheit to celsius     → 0°C
now in UTC                   → Current time in timezones

See Advanced Calculator for complete guide.

Priority: 800
Commands: @shell, $
Description: Execute shell commands directly from the launcher.

Features:

• Run any shell command
• Terminal launch for interactive commands
• Command history (future)

Example:

@shell ls -la        → Execute ls -la
$ pwd                → Show current directory

Security Note: Commands are executed in your default shell with your user permissions.

Priority: 650
Commands: @code, @zed, @editor
Description: Find and open recent workspaces from code editors.

Supported Editors:

• VS Code / VSCodium
• Zed
• Sublime Text (planned)

Features:

• Parses editor storage for recent workspaces
• Shows project paths
• Direct workspace opening

Example:

@code native-launcher → Open native-launcher workspace
@zed project         → Search Zed workspaces

Priority: 650
Command: @files
Description: Browse recent files and directories.

Features:

• Parses ~/.local/share/recently-used.xbel
• File type icons
• Size formatting
• Directory navigation
• xdg-open integration

Example:

@files document      → Search recent files
@files ~/Downloads   → Browse directory

Priority: 700
Command: @ssh
Description: Launch SSH connections to configured hosts.

Features:

• Parses ~/.ssh/config
• Shows hostname, user, port
• IdentityFile support
• Terminal launch with SSH command

Example:

@ssh server          → Connect to server
@ssh user@host       → SSH with specific user

Priority: 900
Commands: @tabs, @history, or just type (global search)
Description: Search across browser history and bookmarks from 6 browsers.

Supported Browsers:

• Chrome / Chromium
• Brave
• Firefox
• Microsoft Edge
• Vivaldi
• Opera

Features:

• Global search: Type any query to search browser history (4+ characters)
• Persistent index: SQLite database for <5ms queries (~/.cache/native-launcher/browser_index.db)
• Hourly refresh: Background daemon updates index automatically
• Favicons: Browser-specific favicons displayed in results
• Bookmarks: Search saved bookmarks alongside history
• Performance: Limited to 2 results in global mode, full results with @tabs / @history

Examples:

rust documentation   → Finds "The Rust Book" from history (if you visited it)
@tabs github         → Search open/recent tabs explicitly
@history tutorial    → Search full browser history

Performance Note: Global search activates at 4+ characters to prevent keystroke lag.

Priority: 300
Command: @clip
Description: Access clipboard history via cliphist integration.

Requirements:

• cliphist installed (Wayland clipboard manager)
• One of: wl-copy (Wayland) / xclip / xsel (X11)

Features:

• Browse clipboard history items
• Copy items back to clipboard
• MIME type display (text, image, etc.)
• Graceful degradation with installation instructions if missing

Examples:

@clip                → List recent clipboard items
@clip password       → Search for "password" in clipboard history

Installation:

# Arch Linux
sudo pacman -S cliphist wl-clipboard

# Ubuntu/Debian
sudo apt install cliphist wl-clipboard

Setup: Configure cliphist to store clipboard history in your compositor startup.

Priority: 300
Command: @emoji
Description: Search and copy emojis to clipboard.

Features:

• Keyword-based search (e.g., "smile", "heart", "fire")
• Clipboard integration (auto-copy on selection)
• Visual emoji display in results
• Embedded dataset (10 common emojis, expandable)

Examples:

@emoji smile         → 😀 😊 😁
@emoji heart         → ❤️ 💙 💚
@emoji fire          → 🔥

Keyboard Shortcut: Press Enter to copy emoji and close launcher.

Priority: 600
Command: @web or Ctrl+Enter
Description: Search the web using configured search engines.

Features:

• Multiple search engines (Google, DuckDuckGo, Bing, Wikipedia, Brave Search)
• Configurable default engine
• Browser selection
• Fallback to Google for unknown queries

Example:

@web rust tutorial   → Search "rust tutorial"
firefox → Ctrl+Enter → Search "firefox" on web

Keyboard Shortcut: Press Ctrl+Enter on any query to search the web.

Plugins are sorted by priority to determine result ordering:

Note: Lower priority numbers in code translate to higher display priority.

When you use a command prefix (e.g., @code), only that plugin handles the query:

@code native    → Only searches editor workspaces
@files test     → Only searches files
@ssh server     → Only searches SSH hosts

When you search without a prefix, all enabled plugins participate:

firefox         → Applications plugin matches Firefox app
                  Web Search plugin offers to search "firefox"

Results are sorted by:

1. Score (match quality)
2. Priority (plugin importance)
3. Usage (frecency for applications)

Enable/disable plugins in ~/.config/native-launcher/config.toml:

[plugins]
applications = true  # Always enabled (core functionality)
calculator = true    # Basic + advanced calculator
shell = true         # Shell command execution
editors = true       # VS Code/Zed workspace detection
files = true         # Recent files and directories
ssh = true           # SSH connection launcher
web_search = true    # Web search with Ctrl+Enter

# Command prefix customization
shell_prefix = "$"   # Alternative: "@shell"

[plugins]
calculator = true  # Enables both basic and advanced

[plugins.web_search]
default_engine = "duckduckgo"  # or "google", "bing", "wikipedia"
browser = "firefox"             # or "chromium", "brave", etc.

[plugins]
shell_prefix = "$"  # Can be "$" or "@shell"

Native Launcher supports loading external plugins at runtime. See Dynamic Plugins for complete guide.

Quick Summary:

• Compile plugins to .so shared libraries
• Place in ~/.config/native-launcher/plugins/
• Automatically loaded on startup
• C ABI for stability
• Performance monitoring included

Monitor plugin performance with RUST_LOG=debug:

RUST_LOG=debug native-launcher 2>&1 | grep "plugin"

Performance Targets:

• Load time: <10ms per plugin
• Search time: <1ms per query
• Memory: <5MB per plugin

See Plugin Performance for monitoring and optimization.

Add a new plugin to Native Launcher by:

1. Create src/plugins/my_plugin.rs
2. Implement the Plugin trait
3. Register in src/plugins/manager.rs
4. Add to src/plugins/mod.rs

See Plugin Development for complete guide.

Create external plugins without modifying Native Launcher:

1. Use the plugin template: examples/plugin-template/
2. Implement the C FFI interface
3. Compile to .so shared library
4. Place in plugin directory

See Dynamic Plugins for complete guide.

All plugins implement the Plugin trait:

pub trait Plugin: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn enabled(&self) -> bool;
    fn priority(&self) -> i32;
    fn command_prefixes(&self) -> Vec<&str>;
    fn should_handle(&self, query: &str) -> bool;
    fn search(&self, query: &str, context: &PluginContext) -> Result<Vec<PluginResult>>;
    fn handle_keyboard_event(&self, event: &KeyboardEvent) -> KeyboardAction;
}

Plugins return results with:

• Title: Main display text
• Subtitle: Additional context
• Command: Shell command to execute
• Icon: Icon name or path
• Score: Relevance score (0-10000)
• Desktop path: Optional desktop file path when the result corresponds to an application (enables pin overlay and persistence)

Plugins can intercept keyboard events:

fn handle_keyboard_event(&self, event: &KeyboardEvent) -> KeyboardAction {
    if event.key == "Return" && event.has_ctrl() {
        // Custom Ctrl+Enter behavior
        return KeyboardAction::Execute(command);
    }
    KeyboardAction::None
}

• Keep should_handle() fast (simple string checks)
• Cache expensive computations
• Use lazy initialization
• Avoid blocking I/O in search

• Provide clear titles and subtitles
• Use relevant icons
• Score results appropriately
• Handle errors gracefully

• Use standard command prefixes (@)
• Respect plugin priorities
• Don't override core functionality
• Document your plugin's behavior

1. Check if enabled in config: ~/.config/native-launcher/config.toml
2. Verify should_handle() returns true for your query
3. Check logs: RUST_LOG=debug native-launcher

1. Adjust plugin priority in code or config
2. Improve score calculation in search()
3. Check if other plugins have higher scores

1. Profile with debug logs
2. Optimize should_handle() and search()
3. Move expensive operations to background threads
4. See Plugin Performance

• Plugin marketplace: Discover and install community plugins
• Plugin sandboxing: Security boundaries for untrusted plugins
• Plugin configuration UI: Configure plugins from launcher
• Plugin statistics: Usage and performance analytics
• Hot reload: Update plugins without restart

• Clipboard history: Search clipboard items
• Window switcher: Switch between open windows
• System commands: Shutdown, restart, logout
• Bookmarks: Browser bookmark search
• Emoji picker: Quick emoji insertion
• Color picker: Visual color selection
• Password manager: Integration with pass/bitwarden

• Advanced Calculator - Time and unit calculations
• Dynamic Plugins - External plugin development
• Plugin Development - Built-in plugin creation
• Plugin Performance - Performance monitoring
• Configuration - Plugin configuration options
• Keyboard Shortcuts - Plugin-specific shortcuts

Last Updated: October 2025
Plugins: 8 built-in + dynamic loading support
Status: Active development