GhostKey

A clipboard-free text insertion tool for Linux that securely types text directly into the target app (no clipboard involved).

Highlights

• Clipboard-free text typing (secure; no clipboard usage)
• Per-pad hotkeys (global “type current pad” hotkey removed)
• Rich insert tokens (dates/times, UUID, system info, randoms, Tab/Enter, etc.)
• Import from text/code files; export pad to a file (.ghk by default)
• Editor enhancements: optional line numbers, highlight current line, font, and style scheme
• System tray integration with Show/Hide and Settings…
• Built-in Help dialog (header button)

Installation

GhostKey uses GTK via system-provided PyGObject (gi). You must install OS packages and install GhostKey in an environment that can see system packages.

1) Install system prerequisites (Debian/Ubuntu/Linux Mint)

sudo apt-get update
sudo apt-get install \
  python3-gi \
  gir1.2-gtk-3.0 \
  gir1.2-appindicator3-0.1 \
  python3-venv \
  python3-pip \
  pipx \
  python3-dev \
  gcc

Notes:

• python3-gi and gir1.2-gtk-3.0 provide gi and GTK bindings
• gir1.2-appindicator3-0.1 enables the tray icon

2) Install options

Choose ONE of the following methods:

• Option A: install.sh (user install via pipx)
• Option B: .deb package (system-wide install)
• Option C: pipx from source (manual)

Option A: install via install.sh (recommended for users)

The script installs GhostKey with pipx (exposing system GTK/gi) and registers the desktop entry/icons for your user.

chmod +x ./install.sh
./install.sh

After installation, you can launch GhostKey from your desktop menu or by running:

ghostkey

Option B: install via .deb package (system-wide)

Build the .deb (or download a release .deb if provided), then install it:

# Build .deb from source (inside the repo)
dpkg-buildpackage -us -uc -b

# Install the generated package from the parent directory
sudo apt-get install ./ghostkey_*_amd64.deb

This installs the desktop file to /usr/share/applications and icons to the hicolor theme. If the launcher doesn’t appear immediately, refresh caches:

sudo update-desktop-database /usr/share/applications
sudo gtk-update-icon-cache -f -t /usr/share/icons/hicolor
xdg-desktop-menu forceupdate || true

Launch from your menu or run:

ghostkey

Option C: install via pipx from source (manual)

python3 -m pip install --user pipx
python3 -m pipx ensurepath

# The --system-site-packages flag is REQUIRED so gi/GTK are visible
pipx install --system-site-packages .

If you previously installed without the flag, fix it with:

pipx uninstall ghostkey
pipx install --system-site-packages .

Development: Run from source

run.sh creates a venv that shares system packages (for gi), installs deps, and starts the app:

chmod +x ./run.sh
./run.sh

Usage

• Create or select a pad on the left.
• Set a Name, choose a Hotkey, and enter Content.
• Click Save to persist changes and rebind hotkeys.
• To type the pad’s content into any app:
  • Click Run, or
  • Use the pad’s configured hotkey.
• Use Import/Export to load or save pad content as files.
• Click the Help button in the header for a quick guide.

Pads (Profiles)

• Each pad has: Name, Hotkey, and Content
• Select a pad in the left panel to edit it
• Add pads with +; remove with – (you cannot remove the last remaining pad)
• Sorting by Name or Hotkey helps organize your list

Per-pad hotkeys

• Set the Hotkey field on a pad
• Hotkeys must include a modifier (Ctrl/Alt/Shift/Super)
• Hotkey changes take effect after clicking Save

Insert Tokens

Use the Insert dropdown to add tokens that expand at type-time. Examples:

• Date/time: [[[DATE]]], [[[DATE_US]]], [[[TIME]]], [[[TIME_12H]]], [[[TIME_SECONDS]]], [[[DATETIME]]], [[[DATETIME_US]]], [[[DATETIME_SECONDS]]], [[[ISO8601]]], [[[RFC3339]]], [[[RFC2822]]], [[[YEAR]]], [[[MONTH_NUM]]], [[[MONTH_NAME]]], [[[DAY]]], [[[WEEKDAY]]], [[[ISO_WEEK]]]
• Epoch: [[[EPOCH]]], [[[EPOCH_MS]]]
• Identity/system: [[[UUID]]], [[[USERNAME]]], [[[HOSTNAME]]], [[[PUBLIC_HOSTNAME]]]
• Network: [[[INTERNAL_IP]]], [[[EXTERNAL_IP]]], [[[MAC_ADDR]]]
• Environment/paths: [[[HOME]]], [[[CWD]]], [[[PATH]]], [[[SHELL]]]
• Random: [[[RAND_INT]]], [[[RAND_HEX8]]]
• Control keys: [[[TAB]]], [[[ENTER]]]

Tokens are triple-bracketed. They’re replaced just before typing.

Import / Export

• Import:
  • Click Import, choose a text/code file (.txt, .md, .csv, .json, .css, .html, .py, .js, .ts, .yml, .yaml, .ini, .conf, .sh, .go, .java, .cpp, .c, .rb, .rs, .toml, .xml, .log, …)
  • File is read as UTF-8 (errors replaced) and loaded into the current pad
• Export:
  • Click Export, choose a path/filename (default extension .ghk)
  • Current pad content is saved as UTF-8

Settings

Open from header (gear) or tray.

• General:
  • Confirm before deleting a pad
  • Auto-save changes
• Editor:
  • Show line numbers (requires GtkSourceView)
  • Highlight current line
  • Font (Pango description, e.g. “Monospace 11”)
  • Style scheme: Auto, Classic, Oblivion, None
• Behavior:
  • Minimize to tray on close
  • Start minimized to tray
  • Typing delay (seconds between simulated keystrokes)

Settings are saved to: ~/.config/ghostkey/config.json and apply without restart. Hotkey changes are applied when you click Save.

Wayland/Xorg notes

• On Wayland, GhostKey prefers the “uinput” backend for pynput to improve reliability; on Xorg, the default backend is used
• Some applications restrict simulated input; results can vary by desktop environment and security policy

Optional dependency: GtkSourceView

If installed (gir1.2-gtksource-3.0), the editor shows line numbers and supports style schemes. Without it, GhostKey falls back to a plain Gtk TextView. Tip messages will suggest installing GtkSourceView to enable line numbers.

Troubleshooting

• Verify GTK/gi is importable:

  python3 -c "import gi; from gi.repository import Gtk; print('GTK OK')"

• If that fails:

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

• Tray not visible: sudo apt-get install gir1.2-appindicator3-0.1
• Reinstall with system packages visible when using pipx:

  pipx uninstall ghostkey
  pipx install --system-site-packages .

• Hotkey not triggering: ensure you clicked Save after editing the hotkey; avoid conflicts with system/global shortcuts; try another combo
• Typing goes into GhostKey: the app will try to hide/minimize before typing; ensure your window manager allows it

Security

GhostKey avoids the clipboard. Text stays in-memory and is typed directly via simulated keystrokes.

Contributing

Issues and PRs are welcome!

License

Apache-2.0 — see LICENSE for details.