https://github.com/cloudwerx-dev/ghostkey
A clipboard-free text insertion tool for Linux that securely types text directly into the target app (no clipboard involved). For Linux (Debian)
https://github.com/cloudwerx-dev/ghostkey
ahk autohotkey autokey clipboard hotkeys keyboard text
Last synced: 10 months ago
JSON representation
A clipboard-free text insertion tool for Linux that securely types text directly into the target app (no clipboard involved). For Linux (Debian)
- Host: GitHub
- URL: https://github.com/cloudwerx-dev/ghostkey
- Owner: CLOUDWERX-DEV
- License: apache-2.0
- Created: 2025-08-10T03:42:41.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-08-10T03:47:50.000Z (10 months ago)
- Last Synced: 2025-08-10T05:27:32.777Z (10 months ago)
- Topics: ahk, autohotkey, autokey, clipboard, hotkeys, keyboard, text
- Language: Python
- Homepage: http://cloudwerx.dev
- Size: 687 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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)
```bash
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.
```bash
chmod +x ./install.sh
./install.sh
```
After installation, you can launch GhostKey from your desktop menu or by running:
```bash
ghostkey
```
#### Option B: install via .deb package (system-wide)
Build the .deb (or download a release .deb if provided), then install it:
```bash
# 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:
```bash
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:
```bash
ghostkey
```
#### Option C: install via pipx from source (manual)
```bash
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:
```bash
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:
```bash
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:
```bash
python3 -c "import gi; from gi.repository import Gtk; print('GTK OK')"
```
- If that fails:
```bash
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:
```bash
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.