Snippitor

by FOSSCharlie

Score 0

Issues Website Download

UUID: snippitor@FOSSCharlie

Last edited:

2 weeks ago 2026-07-22, 14:02

Last commit: [8a2e2c0c] Add Snippitor applet (#8892)

Expand short triggers into full text system-wide (e.g. fc# -> FOSSCharlie)

README

Snippitor (Cinnamon applet)

A panel applet + background daemon that expands short triggers into full text anywhere on your desktop — type tel# then a space/enter/punctuation and it becomes 01234567890.

How it's put together (and why)

A Cinnamon applet on its own can only see clicks/keys inside its own panel widget — it has no way to intercept what you type into Firefox, a terminal, LibreOffice, etc. So this is three pieces:

applet.js — the panel icon. Click it to start/stop Snippitor, right-click for "Edit Expansions...".
snippitor_daemon.py — a small Python background process using pynput that watches your keystrokes system-wide (X11 only) and does the actual find-and-replace.
snippitor_gui.py — a GTK window (opened from the applet's menu) where you add/edit/remove trigger → expansion pairs. It saves to data/expansions.json inside this applet's own folder, which the daemon polls every ~2 seconds and reloads automatically — no restart needed. Storing data inside the applet folder (rather than ~/.config) means removing the applet - by any method, including ones that don't run this applet's own cleanup code - naturally deletes its data too.

Requirements

Snippitor bundles its own copy of pynput, so there's nothing to pip install. The only requirement is GTK3's Python bindings for the editor GUI — these are virtually always already present on a Cinnamon desktop (Cinnamon Settings, Nemo, and most Mint tools depend on them too), but if the "Edit Expansions..." window doesn't open, install them with:

sudo apt install python3-gi gir1.2-gtk-3.0

X11 only. If you're on a Wayland session (check with echo $XDG_SESSION_TYPE), the global keyboard hook won't work — this is a limitation of Wayland's security model, not something fixable in the script. Cinnamon defaults to X11 on most distros (Linux Mint especially), but it's worth checking.

Install

mkdir -p ~/.local/share/cinnamon/applets
cp -r snippitor@FOSSCharlie ~/.local/share/cinnamon/applets/

Then:

Restart Cinnamon: Ctrl+Alt+Esc, or run cinnamon --replace &
Right-click the desktop → Applets (or open Cinnamon Settings → Applets)
Find "Snippitor" in the list and click + to add it to a panel

No pip installs, no terminal commands beyond the copy above — the whole thing works out of the box once it's in the applets folder.

Use

Click the panel icon to start Snippitor (icon changes to indicate it's running). Click again to stop it - though it also auto-starts on its own, so this is optional.
Right-click → Edit Expansions... opens the GUI editor. Add, edit, remove, export, or import rows - everything saves automatically as you go, no Save button needed. Only one editor window can be open at a time.
Type a trigger (e.g. tel#) followed by a space, tab, enter, or punctuation character, and it's replaced with the expansion.

A starter expansion (tel# → 01234567890) is included by default, stored at data/expansions.json inside this applet's own folder.

Known limitations

X11 only, not Wayland (see above).
The trigger must be followed by a boundary character to fire — same behavior as tools like AutoKey or espanso, so it doesn't mangle words you're still typing (e.g. tel# inside a longer word won't fire until you hit a space/punctuation after it).
Snippitor doesn't currently auto-start on login — you start it from the panel icon each session. If you want it running automatically, the simplest option is to add python3 ~/.local/share/cinnamon/applets/snippitor@FOSSCharlie/snippitor_daemon.py to Cinnamon Settings → Startup Applications.
This is a personal-use utility script, not hardened security software — pynput sees literally everything you type while the daemon runs (that's inherent to how tools like this work, including AutoKey and espanso).

License

Snippitor is free software, licensed under the GNU General Public License v3.0 (or, at your option, any later version). See the LICENSE file for the full text.

Disclaimer

This software is provided "as is", without warranty of any kind, express or implied — see sections 15-16 of the LICENSE for the exact legal terms. You use this applet entirely at your own risk. Given that Snippitor works by watching keystrokes system-wide in order to detect triggers, please read the "Known limitations" section above before installing, and back up anything important before relying on it.

CHANGELOG

Open

Changelog

All notable changes to Snippitor are documented here.

[1.8.0]

Added

GPL v3 license (LICENSE), with a short header in every source file and a License/Disclaimer section in the README.

Security

Config data (which can include personal info like phone numbers) is now restricted to owner-only permissions (600 on the file, 700 on its folder), re-applied on every load/save so it self-heals on upgrade.
The daemon's keystroke callback is now wrapped in a broad exception guard - previously, a single malformed config entry (e.g. from a bad import) could silently kill the entire daemon with no visible error.
Import now validates that trigger/expansion values are plain text before accepting them, rather than trusting an external file blindly.
Exported files default to owner-only permissions too.

[1.7.0]

Changed

Renamed the whole project from "Text Expander" to Snippitor, including both script files (expander_daemon.py → snippitor_daemon.py, expander_gui.py → snippitor_gui.py), internal class names, and every reference in the UI, comments, and docs.
New default starter trigger: tel# → 01234567890 (was c# → Charlie).
Applet description example updated to fc# -> FOSSCharlie.
Panel icon is now icon-only (switched from TextIconApplet to IconApplet) - no more "ON"/"OFF" text label next to the icon.

Fixed

Duplicate triggers are now rejected in the editor instead of silently colliding into one entry on save; clicking "Add" repeatedly no longer produces multiple identical placeholder rows either.
The editor GUI now closes automatically when the applet is removed via Cinnamon's normal removal flow, instead of being left orphaned.
Disabled GtkTreeView's built-in "type to search" popup in the editor - it was capturing stray keystrokes into a floating search box, and since the daemon runs system-wide it would even try to expand triggers typed into that popup.

[1.6.0]

Added

Auto-save on every edit in the GUI editor - no Save button.
In-progress cell edits are force-committed if the window is closed mid-edit.
Single-instance editor window via Gtk.Application - opening it again just brings the existing window forward.
Export and Import buttons (merge-on-import, with a file chooser dialog).
The applet now auto-starts the daemon on load instead of requiring a manual click.

Changed

Data storage moved inside the applet's own folder (data/ next to the scripts) instead of ~/.config/snippitor. Whichever way the applet is removed, deleting its folder now deletes its data with it. Includes one-time migration of existing data from the old location.
Removing the applet from the panel now also deletes any leftover data at the old ~/.config location, and stops the daemon.

Fixed

A real rendering bug: the editor window opened completely blank after the move to Gtk.Application, because show_all() was never called on it - present() alone doesn't recurse into showing child widgets.

[1.5.0]

Fixed

Custom triggers using symbols outside a small hardcoded set (e.g. % in a tel%-style trigger) silently failed to match. Which characters count as "still typing a trigger word" is now computed dynamically from the user's actual configured triggers instead of a fixed list.

[1.4.0]

Fixed

Off-by-one in the trigger-replacement logic: only the boundary character was being deleted, not the trigger itself (or vice versa depending on the case), producing garbled output like cFOSSCharlie instead of a clean expansion.
Shift and other modifier keys were incorrectly treated as "interrupt the current word" keys, breaking any trigger containing a shifted symbol (e.g. # on a US layout) or capital letter.
Retyping the boundary character (space/tab/enter) via a raw key press/release was found to silently fail to register on at least one real system; switched to retyping it as a literal character via the same method already used for the expansion text.
A genuine race condition where fast/continuous typing could scramble output, caused by sending corrective keystrokes on the same thread that needed to stay responsive to detect them. Replaced a blocking "wait and retry" approach (which turned out to be structurally incapable of working, since it blocked the very thread it needed) with a non-blocking timer-based approach.
Backspace timing tuned to avoid X11 generating spurious duplicate backspace events when sent with no gap between them.

[1.3.0]

Changed

pynput and its dependencies (python-xlib, six) are now bundled directly inside the applet folder. No separate pip install step is required anymore.

[1.2.0]

Fixed

# (and other shifted/symbol characters) in a trigger only matched partially, because pressing Shift to type them was incorrectly clearing the in-progress trigger buffer.

[1.1.0]

Fixed

Applet showed a generic Cinnamon warning ("could cause cinnamon to crash or freeze") due to a synchronous blocking call (spawn_command_line_sync) in the applet's init path; replaced with an async, non-blocking status check.
Applet failed to load at all (Unknown role definition error) due to an invalid "role" field in metadata.json; removed it.

[1.0.0]

Added

Initial release: Cinnamon panel applet + background daemon + GTK editor for a simple system-wide text expander, with one example trigger (c# → Charlie).

Log In To Comment!

1 Comments

FOSSCharlie-1 week ago

A super simple alternative to AutoKey and Espanso. For example, add "adr" and your address, and you never have to type your address again. You can even use it for typos, such as "thier" can become "their" instantly.