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.
1 maintainer
Release files for clipboard-processor 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| clipboard_processor-0.3.1.tar.gz | 46.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| clipboard_processor-0.3.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 65.0 kB
Release files / clipboard_processor-0.3.1.tar.gz
| Download URL | clipboard_processor-0.3.1.tar.gz |
|---|---|
| Size | 46.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
067963b78ef10646accc622de4e9376a58dfd5f8b28a1ee6540ae12f2f2252df
|
|
BLAKE2b-256 checksum How to use checksums |
9ac4986fc444ae2edbe3f4224ca2ab376169f73d51eeee9f6635f823de0cf810
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 9, 2025.
Transparency logRelease files / clipboard_processor-0.3.1-py3-none-any.whl
| Download URL | clipboard_processor-0.3.1-py3-none-any.whl |
|---|---|
| Size | 18.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
223bd613dc0afc5422905c21ad448c038e71d3d2f5d41aba940e827f4b9fb4b9
|
|
BLAKE2b-256 checksum How to use checksums |
aab78a21c77dbd40504448f33d2afde0dea4e88068f436b11960a2dd9b0790c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 9, 2025.
Transparency log
