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

Platform & Session Support Matrix

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

Installing on Debian / Ubuntu (.deb)

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

# 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_0.4.0_all.deb
sudo apt-get install -f

# 3. Launch FlitKey
flitkey

Installing on Windows (10/11)

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

FlitKey-Setup-0.4.0-x64.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

Running From Source Code

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

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

Dynamic Placeholders Reference

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

Expansion Packs

Available from v0.5.0. Expansion packs are curated snippet collections bundled with FlitKey, so you can start with a working library instead of an empty one. Six packs ship with the app, totalling 46 snippets.

Loading a Pack

Open the snippet manager, click Expansion Packs, tick one or more packs, and choose Load Selected Packs. Two rules govern what actually gets added:

• Your triggers win. Packs are merged into your library, never over it. If a pack contains a trigger you already use, your existing snippet is kept and the pack's version is skipped. Loading the same pack twice adds nothing the second time.
• OS filtering. Each snippet declares a platform (all, linux, or windows). With Filter snippets incompatible with current operating system enabled (the default), snippets for the other OS — PowerShell one-liners on Linux, for instance — are left out. Untick it to load everything regardless.

After loading, FlitKey reports how many new snippets were added. All of them are ordinary snippets from that point on: edit, disable, or delete them like any other.

Writing Your Own Pack

A pack is a single JSON file. Drop one into the packs folder inside your config directory — ~/.config/flitkey/packs/ on Linux, %APPDATA%\flitkey\packs\ on Windows — and it appears in the dialog alongside the built-in packs. A user pack whose pack_id matches a built-in one replaces it, which is how you customise a shipped pack.

{
  "pack_id": "my-team",
  "name": "My Team Pack",
  "description": "Shared replies for the support rota.",
  "version": "1.0.0",
  "snippets": [
    {
      "label": "Git: Commit Message",
      "trigger_type": "keyword",
      "keyword": ":gcm",
      "expansion_text": "git commit -m \"{{clipboard}}\"",
      "platform": "all"
    }
  ]
}

Each snippet needs a label, an expansion_text, and either a keyword or a hotkey; entries missing any of those are skipped. trigger_type is keyword or hotkey, platform defaults to all, and enabled defaults to true. Expansions support the full placeholder set.

Importing Espanso & AutoHotkey Libraries

Migrate your existing snippet collection into FlitKey using the built-in configuration converter, available from the Import button in the snippet manager or on the command line:

# 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