GeminiWatermarkTool Skill for Claude-Like Agents

Overview

GeminiWatermarkTool (GWT) removes visible Gemini AI watermarks from images using mathematically accurate reverse alpha blending, with optional AI denoising (FDnCNN + NCNN Vulkan GPU) for residual cleanup.

Source: https://github.com/allenk/GeminiWatermarkTool

Binary Location

Search in this order:

1. Environment variable: GWT_BINARY_PATH
2. System PATH: GeminiWatermarkTool (or .exe on Windows)
3. Claude skill bin directory:
   • Windows: %USERPROFILE%\.claude\skills\gwt\bin\GeminiWatermarkTool.exe
   • Linux/macOS: ~/.claude/skills/gwt/bin/GeminiWatermarkTool
4. Repo-local bin directory (validation mode / fallback):
   • Windows: .\bin\GeminiWatermarkTool.exe
   • Linux/macOS: ./bin/GeminiWatermarkTool

If not found, run the installer:

python ~/.claude/skills/gwt/install.py

For local validation inside this repo only:

python ~/.claude/skills/gwt/install.py --dir ./bin

Always pass --no-banner when calling GWT — suppresses ASCII art that wastes tokens.

Watermark Profile Selection (v0.3.1+)

GWT ships with two watermark profiles. The default targets Gemini 3.5 and later, with automatic legacy fallback.

This means remove_watermark(input, output) already handles mixed Gemini-3.5+ and pre-3.5 inputs without supervision — the CLI tries the current profile, and on skip retries with the legacy profile before reporting the final outcome. Two opt-out paths exist for the rare case where you need to pin a profile:

• no_legacy=True parameter — disable the automatic fallback (current only)
• remove_watermark_legacy / remove_watermark_batch_legacy — pin legacy only

Always start with remove_watermark / remove_watermark_batch. The auto-fallback handles the common case. The dedicated *_legacy tools are mostly there for callers that have side knowledge an image is pre-3.5 and want to skip the V2 attempt entirely.

What to do when detection fails ("skipped")

A skipped=True result from the default tool means both profiles tried their best and neither matched. The two indistinguishable causes are:

1. The image was generated by Gemini, but its watermark has been destroyed by heavy editing/resizing/re-encoding.
2. The image was not generated by Gemini at all.

Do NOT silently re-invoke remove_watermark_legacy — the automatic fallback has already attempted that. Instead, surface the result to the user and ask whether to escalate:

"I couldn't detect a Gemini watermark on this image (confidence X% on the current profile, Y% on legacy). Either it isn't a Gemini output, or the watermark has been damaged by post-processing. I can try forcing removal at a custom region if you can point me at one — otherwise there's nothing to do."

Escalation paths the agent can offer:

• --fallback-region br:64,64,500,500 --snap — multi-scale search in a user-supplied area (good for resized / cropped images)
• Lower --threshold (e.g. 0.15) — relaxes the safety gate; risky on non-Gemini files but legitimate when the user is certain
• Custom region in the GUI — most user-friendly for one-off cleanup

Decision Logic

Pipeline selection (automatic, based on flags)

Case A — Standard image (not resized after generation)

GeminiWatermarkTool --no-banner -i input.jpg -o clean.jpg

Detection on by default (threshold 25%). Non-watermarked images are skipped safely.

Case B — Image was resized or recompressed

--fallback-region --snap together skips standard detection and goes straight to multi-scale snap search:

GeminiWatermarkTool --no-banner \
  -i input.jpg -o clean.jpg \
  --fallback-region br:64,64,500,500 \
  --snap --snap-max-size 320 --snap-threshold 0.60 \
  --denoise ai --sigma 50 --strength 120

Case C — Unknown image (try standard first, fallback on failure)

Use --fallback-region without --snap. Standard detection runs first; fallback region only activates if standard detection fails:

GeminiWatermarkTool --no-banner \
  -i input.jpg -o clean.jpg \
  --fallback-region br:64,64,500,500 \
  --denoise ai --sigma 50 --strength 120

Full CLI Reference

Core options

Region options

Region spec formats:

Snap engine

Denoise / inpaint

Watermark Size Auto-Detection

Override with --force-small or --force-large. Profile is selected by --legacy (off = V2, on = V1).

Parameter Tuning Guide

Exit Codes (v0.3.1+)

Batch directory mode keeps lenient semantics (exit 0 unless something actually fails) since partial skips are expected when scanning a folder.

Important Notes

1. AI denoise GPU fallback: Vulkan GPU used when available, falls back to CPU automatically. If AI init fails entirely, GWT falls back to NS inpainting.
2. SynthID cannot be removed: Statistically embedded during generation, inseparable from image content.
3. Supported formats: jpg, jpeg, png, webp, bmp
4. Batch mode: -i dir/ -o dir/ processes all images; non-watermarked files are skipped safely by default.
5. Profile auto-fallback (v0.3.1+): by default the CLI tries the current profile, then automatically retries with the legacy profile on skip. Pin a single profile with --legacy (V1 only) or --no-legacy (V2 only) if the auto-fallback isn't what you want.