Getting Started

FlitKey Documentation

FlitKey is a lightweight, open-source Linux and Windows desktop text expander designed to create reusable text snippets and insert them instantly using typed keywords, global hotkeys, or a searchable quick-insert picker.

Technical Specifications

Specification Details
Language / Runtime Python 3.10+
GUI Framework PyQt6
Supported Platforms Linux (X11 & Wayland), Windows 10/11 (64-bit)
Linux System Dependencies python3-pyqt6, xdotool, xinput, x11-xserver-utils
Local Config Storage Linux: ~/.config/flitkey/config.json
Windows: %APPDATA%\flitkey\config.json
License MIT License (Open-Source)

Platform & Session Support Matrix

FlitKey automatically detects your desktop environment (X11 vs Wayland vs Windows) on startup and selects the best expansion mechanism:

Feature X11 Desktop Wayland Desktop Windows 10/11
Typed Keyword Expansion ✓ Full Native ✓ Clipboard Fallback ✓ Full Native
Global Hotkeys ✓ xdotool ✓ Manual Bind ✓ Native Hooks
Search Picker Overlay ✓ Alt+Space ✓ Alt+Space ✓ Alt+Space
System Tray Menu ✓ Native Tray ✓ StatusIcon ✓ Win Tray

Installing on Debian / Ubuntu (.deb)

For Debian, Ubuntu, Linux Mint, and Pop!_OS, install using the pre-built .deb package:

Terminal Command 
# 1. Install system dependencies
sudo apt update
sudo apt install -y python3 python3-pyqt6 xdotool xinput x11-xserver-utils

# 2. Download and install FlitKey
sudo dpkg -i flitkey_2.4.1_amd64.deb
sudo apt-get install -f

# 3. Launch FlitKey
flitkey

Installing on Windows (10/11)

Download FlitKey-2.4.1.exe and run the setup wizard. IT administrators can execute silent background deployments:

Command Prompt (Silent Installation) 
FlitKey-2.4.1.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

Running From Source Code

You can clone and run FlitKey directly from source using Python 3.10+:

Bash 
git clone https://github.com/swarajnandedkar/FlitKey.git
cd FlitKey
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 run.py

Chrome Extension (Manifest V3)

To use FlitKey triggers inside web applications in Google Chrome, Brave, or Microsoft Edge:

  1. Open chrome://extensions in your browser.
  2. Enable Developer Mode (top-right toggle).
  3. Click Load unpacked and select the chrome_extension/ directory from the repository.

Dynamic Placeholders Reference

Incorporate live variables into your text snippets. FlitKey automatically parses placeholders at the time of expansion:

Placeholder Token Function Description Output Sample
{{date}} Injects current local date (YYYY-MM-DD) 2026-07-24
{{time}} Injects current 24-hour time (HH:MM) 14:30
{{datetime}} Injects ISO date and time timestamp 2026-07-24 14:30
{{clipboard}} Injects current text clipboard contents Clipboard text
$|$ or {{cursor}} Sets final cursor position after expansion Cursor moves to token location

Importing Espanso & AutoHotkey Libraries

Migrate your existing snippet collection into FlitKey using the built-in configuration converter (Pro feature or CLI tool):

Import Command Syntax 
# Import Espanso match YAML file
python3 -m text_expander.importers --espanso ~/.config/espanso/match/base.yml

# Import AutoHotkey script file
python3 -m text_expander.importers --ahk ~/my_hotkeys.ahk

# Import CSV snippet library
python3 -m text_expander.importers --csv ~/snippets.csv

Troubleshooting & FAQs

Why aren't triggers expanding on Linux Wayland?

On Wayland sessions, security restrictions prevent background global key injection. Ensure FlitKey is running with clipboard mode enabled, or use the Alt+Space search picker overlay.

Where is my snippet configuration file stored?

All snippets are stored in plain JSON format at ~/.config/flitkey/config.json on Linux and %APPDATA%\flitkey\config.json on Windows.

Does FlitKey send any data to external servers?

No. FlitKey is 100% offline and open-source. It contains zero network dependencies, telemetry trackers, or phone-home code.