A native desktop app that quietly cleans copied text and links using rules you
control.
Clipboard Transformer can remove tracking parameters, normalize URLs, rewrite
text, and run ordered groups of rules. The desktop app handles the clipboard
automatically; the separate CLI is available for terminals, scripts, and
diagnostics.
Install
See the installation guide for every supported macOS,
Windows, and Linux installation method, followed by direct downloads for each
platform. The desktop app does not require CLI setup.
Desktop app (GUI)
The desktop app is the recommended way to use Clipboard Transformer. Launch it
from Applications, the Start menu, or your desktop launcher; no terminal setup
is required.
On first launch it creates a YAML config and editor schema automatically. It
then lives in the tray and provides:
- automatic clipboard transformations;
- pause and resume;
- recent transformations and Undo;
- config and plugin reload;
- open or reveal config;
- autostart and diagnostics.
There is intentionally no large settings window. Most everyday customization
is a small edit to the generated config.yaml.
A small YAML config
# $schema: ./clipboard-transformer.schema.json
config:
recent_items_count: 5
rules:
- type: url-cleanup
id: remove-tracking
name: Remove tracking parameters
formats: [url, text]
remove_query_prefixes: [utm_]
remove_query_params: [fbclid, gclid]
- type: regexp
id: youtube-shorts
name: Normalize YouTube Shorts
formats: [url, text]
from: '^https://www\.youtube\.com/shorts/([A-Za-z0-9_-]{11})$'
to: 'https://youtu.be/$1'
Each rule has an id and a type; the remaining fields describe when and how
it transforms a copied value. The generated schema provides completion and
typo checking in compatible editors.
Read Configuration and the
Rule guide when you want to add or organize rules.
More rule examples
As a bonus, you can browse
the maintainer's personal rules gist.
Copy only the rules you understand, or import the hosted file directly:
rules:
- import: https://gist.github.com/jag-k/3f9cd197776ab5db24150f5cd23026ea/raw/rules.yaml
A remote import can change when its owner updates it. Review the gist before
using it; for a stable personal setup, copy the rules locally or pin a specific
gist revision. See Imports.
Command-line interface (CLI)
The standalone clipboard-transformer command is optional. It shares the same
config and rules but does not own the tray, autostart, notifications, or
continuous clipboard transformation.
Use it for explicit terminal workflows:
# Find files and diagnose native capabilities.
clipboard-transformer paths
clipboard-transformer doctor
# Validate the active config.
clipboard-transformer config check
# Discover rule types available to the active config.
clipboard-transformer rules list --available-only
# Preview the current clipboard without writing the result.
clipboard-transformer transform --preview
# Transform the current clipboard once.
clipboard-transformer transform
# Use the rule engine as a stdin/stdout filter.
printf '%s' 'https://example.com/?utm_source=test&id=42' |
clipboard-transformer transform -
The CLI never starts a hidden daemon. See the complete
CLI reference.
Rules
| Type | Purpose |
|---|
regexp | Text matching and replacement. |
url | Encoding-safe structural URL changes. |
url-cleanup | Query-parameter cleanup. |
ruleset | Ordered composition and match policies. |
shell | Explicitly trusted local scripts. |
/ | Sandboxed WASM extensions. |
Rules may be limited by clipboard format or source application. YAML and TOML
configs may also split rule sets across local or remote imports.
Agent skill
The repository includes an installable clipboard-transformer-rules skill for
agents that help write and validate configs:
npx skills add jag-k/clipboard-transformer \
--skill clipboard-transformer-rules
It has one canonical copy under
.agents/skills/clipboard-transformer-rules.
See Agent setup for Codex, Claude Code, Cursor, Gemini
CLI, GitHub Copilot, and OpenCode.
Support and development
macOS, Windows, and Linux are supported targets. See
Platform support, the detailed
Linux guide, and Troubleshooting.
The documentation index links the full user guide.
Contributors should read CONTRIBUTING.md; active work is
tracked in TODO.md.
Security reports belong in SECURITY.md. The project is licensed
under MPL-2.0.
