Shortcut Sage

Context-aware keyboard shortcut suggestions for KDE Plasma (Wayland)

Shortcut Sage is a lightweight, privacy-first desktop tool that watches your workflow and suggests relevant keyboard shortcuts at the perfect moment. Think of it as "autocomplete for your hands."

Features

• Context-aware suggestions: Suggests up to 3 shortcuts based on your recent actions
• Privacy by design: Only symbolic events (no keylogging), all local processing
• Config-driven: Rules defined in YAML, not hard-coded
• Minimal UI: Small always-on-top overlay, top-left corner
• KDE Plasma integration: Native KWin script for event monitoring

Architecture

KWin Script → DBus → Daemon (rules engine) → DBus → Overlay UI

• KWin Event Monitor: JavaScript script that captures desktop events
• Daemon: Python service that matches contexts to suggestions
• Overlay: PySide6 window displaying suggestions

Requirements

• OS: Linux with KDE Plasma (Wayland) 5.27+
• Python: 3.11 or higher
• Dependencies: DBus, PySide6, Pydantic

Installation

Development Setup

# Clone repository
git clone https://github.com/Coldaine/ShortcutSage.git
cd ShortcutSage

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Install KWin script
bash scripts/install-kwin-script.sh

Configuration

Create your config files in ~/.config/shortcut-sage/:

shortcuts.yaml: Define your shortcuts

version: "1.0"
shortcuts:
  - key: "Meta+D"
    action: "show_desktop"
    description: "Show desktop"
    category: "desktop"

rules.yaml: Define context-based suggestion rules

version: "1.0"
rules:
  - name: "after_show_desktop"
    context:
      type: "event_sequence"
      pattern: ["show_desktop"]
      window: 3
    suggest:
      - action: "overview"
        priority: 80
    cooldown: 300

Usage

# Start the daemon with your config directory
shortcut-sage daemon --config ~/.config/shortcut-sage

# Or use the repo sample config for quick demos
shortcut-sage daemon --config ./config

# Launch the overlay UI (separate terminal)
shortcut-sage overlay

# Need a standalone visual check? Use demo mode
shortcut-sage overlay --demo

Overlay UI

• Always-on-top PySide6 window that renders up to 3 suggestion “chips”
• Positioned in the top-left corner with translucent background and fade animations
• Listens for DBus Suggestions signals from the daemon; --demo fills placeholder data without DBus
• Honors Qt.WindowDoesNotAcceptFocus so it never steals focus while you work

Development

Running Tests

# All tests with coverage
pytest

# Unit tests only
pytest tests/unit

# Integration tests
pytest tests/integration

# End-to-end tests (requires KDE)
pytest tests/e2e

Code Quality

# Lint
ruff check sage tests

# Format
ruff format sage tests

# Type check
mypy sage

Project Status

Currently implementing MVP (PR-00 through PR-06):

• ✅ PR-00: Repository & CI Bootstrap
• ✅ PR-01: Config & Schemas
• ✅ PR-02: Engine Core
• ✅ PR-03: DBus IPC
• ✅ PR-04: KWin Event Monitor
• 🚧 PR-05: Overlay UI
• ⏳ PR-06: End-to-End Demo

See implementation-plan.md for full roadmap.

Documentation

• Product Bible: Vision, principles, and architecture
• Implementation Plan: Phased development plan
• Agent Prompt: Instructions for autonomous development

Privacy & Security

• No keylogging: Only symbolic events (window focus, desktop switch)
• Local processing: No cloud, no telemetry
• Redacted by default: Window titles not logged
• Open source: Audit the code yourself

Contributing

Contributions welcome! Please read our Contributing Guide first.

License

MIT License - see LICENSE for details.

Acknowledgments

Built with:

• PySide6 - UI framework
• Pydantic - Data validation
• pytest - Testing framework
• ruff - Linting & formatting

---

Status: 🚧 Alpha - Active Development

For questions or issues, please open an issue on GitHub.