Skip to content
Get packs

Guide · Open source

How to use watermarks-remover: install the skill and clean files

Updated · written with AI from the project's own documentation and checked against our catalogue data

watermarks-remover is an open-source tool that removes hidden AI provenance marks from text and files, such as invisible Unicode characters, C2PA metadata, and EXIF or XMP fields. It is built for content you own, and it is split into an agent skill plus a small local Python service. This guide walks through installing the skill, starting the service, and using the hook and CI options so you can clean files on purpose.

watermarks-removerguillaumemeyer/watermarks-remover · ★ 25.9k · MIT

Quick start

  1. 1Check the prerequisites. Confirm you have Python 3.10 or newer and an agent host such as Claude Code, Codex, or Cursor.
  2. 2Clone the repository. Download the watermarks-remover repository from GitHub to a local folder.
  3. 3Install the skill. Run python3 install_skill.py --skill remove-ai-marks --target claude-code from the repository root.
  4. 4Start the service. Run make serve from the repository so the skill can reach the local HTTP service.
  5. 5Confirm the URL. Leave WATERMARKS_SERVICE_URL at its default http://127.0.0.1:8765 or set it to your own address.
  6. 6Choose a hook mode. Pick check to only report marks, or clean to strip them in place, if you wire the PostToolUse hook.

What watermarks-remover does and what it does not do

The project works on two layers. Layer A covers invisible Unicode characters, exotic spaces, bidi controls and tag characters, handled by deterministic Python scripts. Layer B covers statistical text watermarks, which are handled by an agent rewrite plus an optional rewrite_text.py hook.

For files, it targets C2PA, EXIF, XMP and document properties across formats including PNG, JPEG, WebP, PDF, DOCX, XLSX, PPTX, MP4, WAV and MP3. The README frames the tool as a privacy and hygiene aid for content you own, and it explicitly scopes out removing marks from content you do not own.

  • Deterministic: invisible Unicode and file metadata (Layer A and Files).
  • Best-effort: statistical text watermarks, which depend on model rewriting (Layer B).

Install the Claude Code skill

You need Python 3.10 or newer and an agent host such as Claude Code, Codex, or Cursor. Clone the repository, then run the bundled installer from the repository root. The installer uses only the Python standard library, so there are no dependencies to install.

The installer supports several targets. For personal Claude Code use, the target is claude-code, which places the skill in ~/.claude/skills/. Existing installs are kept unless you pass --force, and --link symlinks the checkout so edits are picked up live.

  • Use --list to print the shipped skills: remove-ai-marks (service-backed) and clean-user-facing-text (self-contained).
  • On Windows, use py install_skill.py instead of python3.
  • Cowork, claude.ai and cloud sessions need the zip at dist/<skill>.zip, uploaded under Customize → Skills.
python3 install_skill.py --skill remove-ai-marks --target claude-code

Start the local service

The remove-ai-marks skill is a thin client. It sends work to the service over HTTP, so the agent host does not need Python itself. Start the service from the repository before using the skill.

The skill reads WATERMARKS_SERVICE_URL, which defaults to http://127.0.0.1:8765, and checks the /health endpoint. If the service requires an API key, set WATERMARKS_SERVER_API_KEY for the client. Without make, on Windows, run the server script directly.

  • Default URL: http://127.0.0.1:8765 (change it with WATERMARKS_SERVICE_URL).
  • Endpoints the client calls: /health, /inspect and /clean.
  • Windows without make: py service/scripts/server.py --host 127.0.0.1 --port 8765
make serve

Automate checks with a PostToolUse hook

A skill depends on the model deciding to use it. A hook runs on every matching tool call, so it is the deterministic option. The plugin registers a PostToolUse hook on Write, Edit, MultiEdit and NotebookEdit that runs hook_written_file.py against the file the agent just wrote.

The hook has two modes. check, the default, reports marks and leaves the file alone. clean strips the marks in place. You can set the mode with the plugin's Hook mode setting or with WATERMARKS_HOOK_MODE=clean in the environment. Without the plugin, add the hook to ~/.claude/settings.json or a project .claude/settings.json yourself.

  • check (default): findings go to the model so it can offer to clean them.
  • clean: writes to a temp file and swaps only on a real difference, so already-clean files keep their modification time.
  • Hooks cannot rewrite the assistant's chat message before you read it, so text that only exists in the transcript still depends on the skill workflow.
{"hooks":{"PostToolUse":[{"matcher":"Write|Edit|MultiEdit|NotebookEdit","hooks":[{"type":"command","command":"python3","args":["/path/to/watermarks-remover/service/scripts/hook_written_file.py","--mode","check"],"timeout":30}]}]}}

Use the Claude Code plugin or the pre-commit and CI checks

In Claude Code, the repository is also a single-plugin marketplace, so you can install both skills with two commands and no clone. The skills then load namespaced as /watermarks-remover:remove-ai-marks and /watermarks-remover:clean-user-facing-text.

The same detection code backs the pre-commit gate and the CI export, so the hook, the gate and the SARIF report agree on what counts as actionable. The README describes a CI check that reports actionable provenance marks as SARIF.

  • Plugin install: /plugin marketplace add guillaumemeyer/watermarks-remover, then /plugin install watermarks-remover@watermarks-remover.
  • Pre-commit gate: catches marks on their way into git.
  • CI: SARIF output for reporting actionable marks.
/plugin marketplace add guillaumemeyer/watermarks-remover /plugin install watermarks-remover@watermarks-remover

What people use it for

  • Scrubbing provenance metadata from text and files an AI coding agent wrote.
  • Removing embedded C2PA or EXIF data from your own images or documents before sharing them.
  • Running a deterministic check on files through a PostToolUse hook or a pre-commit gate.
  • Adding a CI step that reports actionable provenance marks as SARIF.

Frequently asked questions

Is watermarks-remover free to use?

The repository is licensed under MIT. The README does not mention pricing, so the license is the relevant fact to check before use.

What do I need to install watermarks-remover?

You need Python 3.10 or newer and an agent host such as Claude Code, Codex, or Cursor. The installer uses the Python standard library and has no dependencies.

How do I install the Claude Code skill?

Clone the repository and run python3 install_skill.py --skill remove-ai-marks --target claude-code. Then start the service with make serve.

Why does the skill need a local service?

The skill is a thin client that sends work to the service over HTTP. The service does the cleaning, so the agent host does not need Python installed.

Can it remove watermarks from someone else's images?

No. The README scopes the tool to content you own and explicitly excludes removing marks from content you do not own.

Does it remove statistical text watermarks reliably?

Not deterministically. Statistical token-sampling watermarks depend on model rewriting, so removal is best-effort.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

watermarks-remover suits developers who use AI coding agents and creators who want to strip C2PA or EXIF data from their own files. It is a poor fit for non-technical users, since setup involves cloning, running a local HTTP service and editing settings files. Anyone who needs guaranteed removal of statistical text watermarks should look elsewhere.

Install options & downloads