FlitKey Documentation

FlitKey is an open-source text expander for Linux and Windows. Create reusable snippets, trigger them by keyword or hotkey on supported sessions, or find them in the searchable picker.

Technical details

Platform & Session Support Matrix

At startup, FlitKey checks whether it is running on Windows, X11, or Wayland and selects the matching input path:

Technical Architecture

FlitKey uses a PyQt6 interface with separate runtime backends for Windows, Linux X11, and Wayland. The backend is selected once at startup from the detected operating system and session. Snippets and settings are stored locally in config.json; no FlitKey-hosted account or synchronization service is involved.

On X11, the runtime uses xinput to observe keyboard events and xdotool to insert expansions. On Windows, it uses the Win32 keyboard-hook and input APIs. On Wayland, FlitKey disables typed triggers and global hotkeys and uses Quick Insert with clipboard paste.

Installing on Debian / Ubuntu (.deb)

For Debian, Ubuntu, Linux Mint, and Pop!_OS, install using the pre-built flitkey_0.6.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.6.0_all.deb
sudo apt-get install -f

# 3. Launch FlitKey
flitkey

Installing on Windows (10/11)

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

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

Running from source

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

Add placeholders to a snippet when the output needs a date, time, clipboard value, or cursor position:

Expansion Packs

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 supported records with the Import button in the main snippet-manager toolbar. FlitKey does not provide a command-line importer.

Espanso: .yml or .yaml with static trigger/replace matches
AutoHotkey: .ahk with supported hotstring or hotkey lines
Tabular: .csv or .tsv with trigger/expansion or label/trigger/expansion
FlitKey: .json containing snippet objects

Import a copied sample first. Complex scripts, Espanso variables, forms, regular expressions, rich text, images, and application-specific rules are not feature-equivalent. See the Espanso migration guide for backup, verification, and rollback steps.

Troubleshooting & FAQs