Process clipboard content and show helpful overlays or notifications based on the content, e.g. parse UNIX timestamps, AWS account IDs, VINs, base64 strings and more.
All parsing & decoding is done locally. The clipboard content is not sent to any external service.
Install into userspace, create a userspace systemd service & enable it (via installer script):
curl -L -o install-clipboard-processor https://raw.githubusercontent.com/tom-mi/clipboard-processor/main/scripts/install
# review & adapt the installer as needed
chmod +x install-clipboard-processor
./install-clipboard-processorSome features require additional libraries to be installed (see below).
Install with required dependencies only:
pip install clipboard-processorInstall with all optional dependencies (recommended):
pip install clipboard-processor[all]clipboard-processorShow help:
clipboard-processor --helpRun with xclip-primary input mode:
clipboard-processor --input xclip-primaryCheck out the autogenerated demo text which contains example strings for most supported inputs.
There are different input modes available:
| Mode | Description |
|---|---|
auto |
Use pyperclip for cross-platform clipboard access. This is the default. |
xclip-primary |
Use the primary selection on linux via xclip. No explicit copy operation is needed – selecting the text is sufficient. Requires xclip command in the search path. |
All decoding functionality is provided via plugins. Per default, all available plugins are enabled.
| Plugin | Description | External library |
|---|---|---|
aws-account-id |
Show AWS account name for given AWS account ID by parsing ~/.aws/config
|
- |
base64 |
Decode base64 strings | - |
cron |
Print human readable description of cron expressions | cron-descriptor |
hex-utf8 |
Decode printable UTF-8 strings from hexadecimal representation | - |
jwt |
Decode JSON web tokens (JWTs) | PyJWT |
oui |
Show vendor name for given MAC address or OUI (see IEEE OUI database) | netaddr |
ulid |
Parse ULIDs and show the encoded timestamp | python-ulid |
unixtime |
Parse UNIX timestamps and show the human-readable (ISO 8601) time | - |
vin |
Decode Vehicle Identification Numbers (VINs) | vininfo |
well-known |
Show explanation for well known "magic" strings. |
There are different output modes available:
| Mode | Description |
|---|---|
ui |
Use tkinter overlay near the current mouse position to show the output. This is the default. |
notify |
Use desktop-notifier to show the output in a desktop notification. |
stdout |
Print the result of the processing to the standard output. This is mostly intended for debugging and testing. |
This project uses Hatch for managing the development environment.
Install xvfb for running the snapshot tests.
TODO: some more effort might be necessary to support Windows and macOS.
hatch test --all
hatch run test-minimal:run
hatch run test-snapshot:runCreate a development environment in .venv/ which can easily be used by IntelliJ or other IDEs:
hatch env create devhatch shell
clipboard-processoror
hatch run clipboard-processorIn case dependencies are not synced into an existing env, try removing all environments:
hatch env pruneDraft a new release on GitHub.
