Native Launcher Wiki

Welcome to the Native Launcher documentation! This wiki provides comprehensive guides for using and developing Native Launcher.

📚 Table of Contents

Getting Started

• Installation - Build from source, prerequisites, and package installation
• Quick Start - First-time setup and basic usage
• Keyboard Shortcuts - Complete keyboard reference

User Guides

• Configuration - Customizing Native Launcher behavior and appearance
• Compositor Integration - Setting up hotkeys in Sway, Hyprland, etc.
• UI Design - Design system, animations, and theming guide
• Theming - Custom CSS themes and styling
• Troubleshooting - Common issues and solutions

Features

• Plugin System - Overview of built-in plugins
• Script Plugins - Create plugins in any language without compiling Rust
• Advanced Calculator - Time calculations, unit conversions, currency exchange with clipboard
• Web Search - Using web search functionality
• Desktop Actions - Inline application actions
• Workspace Detection - Finding code editor workspaces

Development

• Plugin Development - Creating custom plugins
• Script Plugin Development - Complete guide for script plugins (Bash, Python, etc.)
• Dynamic Plugins - Loading external plugins at runtime
• Plugin Performance - Monitoring and optimizing plugin load times
• Architecture - Technical design and internals
• Contributing - How to contribute to Native Launcher
• API Reference - Plugin trait and API documentation

Additional Resources

• Performance - Benchmarks and optimization tips
• FAQ - Frequently asked questions
• Changelog - Version history and updates

🚀 Quick Links

• GitHub Repository
• Issue Tracker
• Discussions

⭐ About Native Launcher

Native Launcher is a modern, fast, and beautifully designed application launcher for Linux, written in Rust. Built natively for Wayland with GTK4, it features:

• ⚡ Lightning Fast: <35ms startup, <10ms search latency with smart debouncing
• 🎨 Modern Design: Rounded UI with smooth animations, 7 accent colors, density modes
• 🪟 Session Management: Switch windows and workspaces (@switch, @wm)
• 🔧 Git Projects: Find and open repositories (@git)
• 💾 File Search: System-wide indexing with recent documents (@files, @recent)
• 🧮 Advanced Calculator: Time, units, currency conversions (@cal)
• 🔌 Plugin System: Extensible with 15+ built-in plugins + dynamic loading
• 📜 Script Plugins: Create plugins in any language without compiling Rust
• 🎯 Smart Icons: Category-based fallback for 150+ app types
• 🏷️ Icon Badges: Visual indicators (terminal, web, file, folder)
• ⌨️ Quick Actions: Alt+Enter (open folder), Ctrl+Enter (copy path)
• 📸 Screenshots: Capture and annotate with Swappy integration
• 🎬 Smooth Animations: 60fps+ with cubic-bezier easing
• 🌊 Wayland Native: Built on gtk4-layer-shell

📖 Documentation Status

This wiki is actively maintained and updated. Last major update: November 2025

Version 0.2.0 Updates:

• Session Switcher: Window and VS Code workspace management
• Window Management: Move, center, fullscreen, float, pin operations
• Git Projects Plugin: Repository search with branch detection
• Usage Learning v2: Hour-of-day boost and time-decay ranking
• Icon Badges: Visual result type indicators
• Category Icons: Intelligent fallback for apps without icons
• Inline Actions: Alt+Enter folder, Ctrl+Enter copy path
• UI Customization: Density modes and 7 accent colors
• Screenshot Annotation: Swappy integration for editing
• Recent Documents: Access recently opened files
• Enhanced Search: Acronym matching and word boundaries
• 150 Tests: Comprehensive test coverage

📖 Documentation Status

This wiki is actively maintained and updated. Last major update: October 2025

Recent Updates:

• Added system-wide file search integration
• Enhanced performance with smart debouncing and two-pass search
• New modern UI with rounded design and smooth animations
• Comprehensive E2E testing framework
• Pins/Favorites: Ctrl+P to pin apps, star overlay on icons, pinned-first default view

Missing a topic? Open an issue or start a discussion!