clipboard-processor

clipboard-processor

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.

Installation

Quickstart

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-processor

Manual installation

Some features require additional libraries to be installed (see below).

Install with required dependencies only:

pip install clipboard-processor

Install with all optional dependencies (recommended):

pip install clipboard-processor[all]

Usage

clipboard-processor

Show help:

clipboard-processor --help

Run with xclip-primary input mode:

clipboard-processor --input xclip-primary

Check out the autogenerated demo text which contains example strings for most supported inputs.

Functionality

Input

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.

Plugins

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.

Output

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.

Development

This project uses Hatch for managing the development environment.

Prerequisites

Install xvfb for running the snapshot tests.

TODO: some more effort might be necessary to support Windows and macOS.

Run all tests

hatch test --all
hatch run test-minimal:run
hatch run test-snapshot:run

Create environment for IntelliJ

Create a development environment in .venv/ which can easily be used by IntelliJ or other IDEs:

hatch env create dev

Run development version

hatch shell
clipboard-processor

or

hatch run clipboard-processor

Troubleshooting

In case dependencies are not synced into an existing env, try removing all environments:

hatch env prune

Release a new version

Draft a new release on GitHub.