Simple Program Launcher

Lightning-fast program launcher triggered by simultaneous L+R mouse click.

---

Why Another Launcher?

Problem	Solution
Keyboard shortcuts conflict with apps	Mouse trigger - L+R click never conflicts
Alt+Tab is slow for 20+ windows	Instant popup at cursor position
Start menu requires multiple clicks	One gesture opens everything
Clipboard managers are separate apps	Built-in clipboard with 10,000 entry history

---

Features

Core

• L+R Mouse Trigger - Press both buttons simultaneously (50ms threshold)
• Instant Popup - <50ms latency, appears at cursor
• Smart Tracking - Learns your most-used programs (7-day recency weighting)
• Keyboard Shortcuts - Press 1-9 to launch instantly

Clipboard Manager

• 10,000 Entry History - Never lose copied text again
• Fuzzy Search - Type hlo to find hello world
• Pin Important Items - Keep frequently-used snippets accessible
• Usage Tracking - Items sorted by paste frequency
• Smart Eviction - Least-used items removed first when at limit
• Math Preview - See 2+2 = 4 for math expressions
• Tooltips - Hover for full text on long entries
• Persistent History - Survives restarts (~/.config/.../clipboard.json)
• Password Detection - Auto-skips password-like content

Customization

• Pin Favorites - Lock programs/documents to top
• Custom Shortcuts - Add commands like Lock/Sleep/Shutdown
• Hot-Reload Config - Changes apply without restart
• Dark Theme - Easy on the eyes

---

Performance

+------------------+--------+--------+
| Metric           | Target | Actual |
+------------------+--------+--------+
| Memory (idle)    | <10 MB |  ~8 MB |
| CPU (idle)       | <0.1%  | <0.05% |
| Popup latency    | <50 ms |  ~30ms |
| Binary size      |  <5 MB |  ~4 MB |
| Startup time     | <100ms |  ~50ms |
+------------------+--------+--------+

---

Installation

Linux (Recommended: Rust)

git clone https://github.com/RMANOV/simple-program-launcher.git
cd simple-program-launcher
./scripts/install_linux.sh

Note: On Linux, add your user to the input group:

sudo usermod -aG input $USER
# Log out and back in

Windows (Python - Zero Dependencies)

# Requires Python 3.8+ (tkinter included)
pip install pynput pywin32
.\scripts\install_windows.ps1

macOS

./scripts/install_macos.sh
# Grant accessibility permissions when prompted

---

Usage

Action	How
Open launcher	Press L+R mouse buttons together
Launch item	Click or press number key (1-9)
Pin item	Click pin button
Search clipboard	Type in search box
Add shortcut	Click [+ Add Shortcut]
Close	Press Escape or click outside

---

Architecture

simple_program_launcher/
├── crates/
│   ├── core/           # Config, usage tracking, platform APIs
│   │   └── platform/   # Linux: xbel, Windows: Registry, macOS: plist
│   ├── ui/             # egui dark-themed popup
│   └── bin/            # evdev mouse listener + main loop (Wayland + X11)
├── launcher.pyw              # Python cross-platform (requires pynput)
├── python_simple_windows/    # Python Windows-only (zero dependencies!)
│   ├── launcher.pyw
│   ├── config.example.json
│   └── README.md
├── config/                   # Default configuration
└── scripts/                  # Install scripts (systemd/Registry/launchd)

---

Python Versions

Cross-Platform (launcher.pyw)

Full-featured launcher with pynput for mouse events:

• Requires: pip install pynput pywin32 (Windows) or pip install pynput (Linux/macOS)
• Features: Structured config, pinned programs/documents/clipboard, usage tracking with recency weighting, fuzzy search
• Config: ~/.config/launcher/config.json (or %APPDATA%\launcher\config.json)

Simple Windows-Only (python_simple_windows/)

Minimal launcher with zero pip dependencies - uses Windows API directly:

• Requires: Python 3.8+ only (tkinter built-in)
• Features: MFU tracking, clipboard history, math preview, inline add form
• Config: Same directory as script (config.json, usage.json, clipboard.json)
• Best for: Portable use, restricted environments, quick setup

# Just run it!
cd python_simple_windows
pythonw launcher.pyw

Technology Stack

Component	Rust (Linux/macOS)	Python (Windows)
GUI	egui + glow	tkinter
Mouse Events	evdev (Wayland + X11)	pynput
Clipboard	arboard	ctypes/win32
Config	serde_json + notify	json
Recent Files	recently-used.xbel	Recent folder

---

Configuration

Location:

• Linux: ~/.config/launcher/config.json
• Windows: %APPDATA%\launcher\config.json
• macOS: ~/Library/Application Support/launcher/config.json

{
  "pinned_programs": [
    {"name": "VS Code", "path": "code", "item_type": "program"}
  ],
  "pinned_clipboard": ["frequently used snippet"],
  "shortcuts": [
    {"name": "Lock", "path": "loginctl", "args": ["lock-session"]}
  ],
  "max_clipboard_history": 10000,
  "trigger": {
    "simultaneous_threshold_ms": 50,
    "debounce_ms": 500
  }
}

---

How It Works

┌─────────────────────────────────────────────────────────┐
│                    Mouse Event Loop                      │
│  ┌─────────┐    ┌─────────┐    ┌─────────────────────┐  │
│  │ L Click │───►│ Within  │───►│ Trigger! Show Popup │  │
│  └─────────┘    │  50ms?  │    └─────────────────────┘  │
│  ┌─────────┐    └─────────┘                              │
│  │ R Click │───►     │                                   │
│  └─────────┘         │ No                                │
│                      ▼                                   │
│               Reset timer                                │
└─────────────────────────────────────────────────────────┘

Recency-Weighted Scoring

Programs are ranked by usage with exponential decay:

Score = Σ 2^(-age_days / 7)

A launch today = 1.0 points, a week ago = 0.5, two weeks = 0.25, etc.

---

Development

# Build
cargo build --release

# Run with logging
RUST_LOG=info cargo run

# Check for errors
cargo check

# Run tests
cargo test

---

Roadmap

• L+R mouse trigger
• Smart program tracking
• Clipboard history (10K entries)
• Instant clipboard search
• Pin clipboard entries
• Fuzzy search
• Clipboard usage tracking & smart sorting
• Math expression preview
• Persistent clipboard history
• Tooltips for long entries

---

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

---

License

MIT License - Use freely, attribution appreciated.

---

Press L+R to launch!