Skip to content

README.md

Latest commit

 

History

History
203 lines (161 loc) · 6.74 KB

README.md

File metadata and controls

203 lines (161 loc) · 6.74 KB

GhostKey

GhostKey Logo

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.