Clipboard Transformer #

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.
<plugin-id>/<rule-type>	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.