AI agent integrations for GeminiWatermarkTool — Claude-like skill, Codex-like skill, and a shared MCP server

This repo provides specialized skill entrypoints for different agent families plus one shared MCP server.

The skill entrypoints are intentionally specialized. The mcp/ directory remains shared across all clients.

This repo uses distinct skill entrypoints:

• Root skill layout: for Claude-like agents
• skills/gwt/: for Codex-like agents

This avoids forcing both agent families to share the exact same prompt wording and installer defaults.

In other words, the skill layer is split by agent family, while the MCP layer stays shared.

gwt-integrations/
├── SKILL.md           ← Claude-like skill entrypoint
├── install.py         ← Claude-like skill installer
├── skills/
│   └── gwt/           ← Codex-like skill entrypoint
├── mcp/
│   ├── server.py      ← Shared MCP server (4 tools)
│   └── pyproject.toml
└── LICENSE

The root skill and skills/gwt/ skill are intentionally different. They can be tuned for their respective agent families without splitting the MCP server.

              ┌──────────────────┐
              │  install.py (x2) │  Each skill has its own installer
              └────────┬─────────┘  (Claude → ~/.claude, Codex → ~/.codex)
                       │
     ┌─────────────────┼─────────────────┐
     │                 │                 │
   ┌─▼───────────┐  ┌──▼──────────┐  ┌───▼─────────────────┐
   │ Claude-Like │  │ Codex-Like  │  │    MCP Server       │
   │  SKILL.md   │  │ skills/gwt/ │  │  mcp/server.py      │
   │  (root)     │  │  SKILL.md   │  │                     │
   │             │  │             │  │  Agent calls tools, │
   │ Agent reads │  │ Agent reads │  │  server builds args,│
   │ docs, execs │  │ docs, execs │  │  execs binary       │
   └─────────────┘  └─────────────┘  └─────────────────────┘
    Claude-like       Codex-like        Any MCP client

Binary discovery order (default behavior):

1. GWT_BINARY_PATH environment variable
2. System PATH
3. ~/.codex/skills/gwt/bin/
4. ~/.claude/skills/gwt/bin/
5. ./bin/ at the repo root (local validation / fallback)
6. ./mcp/bin/ relative to server.py (legacy fallback)

If the binary is missing, each skill entrypoint can invoke its own install.py while the MCP server remains shared at the repo root.

cd ~/.claude/skills
git clone https://github.com/allenk/gwt-integrations gwt

Claude Code finds SKILL.md at ~/.claude/skills/gwt/SKILL.md automatically.

When the binary is missing, the agent can run install.py automatically. In a Claude-style install, this defaults to ~/.claude/skills/gwt/bin/:

# or run manually
python ~/.claude/skills/gwt/install.py

Open Claude Code and ask: "What skills do you have?"

For Codex's GitHub skill installer, use the dedicated subdirectory:

python install-skill-from-github.py --repo allenk/gwt-integrations --path skills/gwt

After installation, Codex will load the skill from ~/.codex/skills/gwt/, and the bundled install.py will default to ~/.codex/skills/gwt/bin/.

Open Codex and confirm that the gwt skill is available.

To keep the repo self-contained during validation, install the binary locally instead of an agent skill directory:

python ./install.py --dir ./bin
# then: export GWT_LOCAL_VALIDATION=1

Remove the Gemini watermark from this image.
Remove the watermark from all images in ~/Downloads/
The bottom-right corner still has artifacts, fix it
The image keeps getting skipped, try snap search

git clone https://github.com/allenk/gwt-integrations
cd gwt-integrations
pip install -e ./mcp

pip install -e ./mcp
python ./install.py --dir ./bin

The MCP server will detect a missing binary on first use and return an install_command the agent can execute immediately:

{
  "found": false,
  "install_command": "python /path/to/gwt-integrations/install.py --dir /path/to/gwt-integrations/bin"
}

The MCP server is shared across agent families, so its install_command always targets the repo-local bin/ directory — it does not assume any particular skill directory (~/.claude/ or ~/.codex/).

GWT_LOCAL_VALIDATION=1 still controls the search order in find_gwt_binary(): when set, the repo-local bin/ is searched before the skill directories.

Claude Code:

claude mcp add gwt -- python /path/to/gwt-integrations/mcp/server.py

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "gwt": {
      "command": "python",
      "args": ["/path/to/gwt-integrations/mcp/server.py"]
    }
  }
}

Zed (~/.config/zed/settings.json):

{
  "context_servers": {
    "gwt": {
      "command": { "path": "python",
                   "args": ["/path/to/gwt-integrations/mcp/server.py"] }
    }
  }
}

OpenAI Codex CLI:

codex --mcp-server "python /path/to/gwt-integrations/mcp/server.py"

This repo is most useful when the user does not want to manually build CLI arguments. Instead, they describe the image problem in natural language, and the agent maps that request to either the Skill path or the MCP tool path.

User says:

Remove the Gemini watermark from this image.
Remove the Gemini watermark from the bottom-right corner of this image.

Agent behavior:

• Skill: runs standard GWT detection with no advanced flags
• MCP: calls remove_watermark(input_path, output_path)

Best for:

• Typical Gemini output
• Normal bottom-right watermark
• Images that were not resized after generation

User says:

This image keeps getting skipped. Try snap search.
This image was resized. Use snap search to find the watermark.

Agent behavior:

• Skill: adds --fallback-region ... --snap
• MCP: calls remove_watermark_snap(...)

Best for:

• JPEG recompression
• Social-media reposts
• Screenshots or edited exports
• Cases where standard detection returns [SKIP]

User says:

The watermark is mostly gone but the corner still looks dirty.
There are still artifacts in the bottom-right corner. Increase the strength a bit.

Agent behavior:

• Keeps the same detected/custom region
• Increases denoise settings, for example sigma=75, strength=180
• Escalates further only if needed, for example sigma=100, strength=250

Best for:

• Faint edge residue
• Partial removal
• Watermark halo or dirty corners

User says:

The watermark is not in the normal bottom-right position.
Search the bottom-left 600x600 area with snap.
The watermark size looks unusual. Search the bottom-right 200x200 area.

Agent behavior:

• Uses region-constrained search instead of whole-image assumptions
• Skill: uses --fallback-region br:... or bl:... with --snap
• MCP: calls remove_watermark(...) with fallback_region, snap, snap_max_size, and snap_threshold

Best for:

• Cropped images
• Layout-shifted watermark positions
• Smaller or larger than expected watermark sizes

User says:

Use custom region 683,1297,52,52 and remove it directly.
Do not use snap. Use custom region 683,1297,52,52 directly.

Agent behavior:

• Skips broad search
• Applies GWT directly to the supplied region
• Useful when a human has already visually identified the watermark

Best for:

• Repeated images from the same source
• Fine-grained cleanup
• Cases where broad snap search drifts to a wrong candidate

User says:

Remove Gemini watermarks from every image in this folder.
Batch remove Gemini watermarks from every image in this folder.

Agent behavior:

• Skill: calls GWT in directory mode
• MCP: calls remove_watermark_batch(input_dir, output_dir)

Best for:

• Download folders
• Image exports from a single generation session
• Mixed folders where only some images contain a watermark

The highest-signal instructions are:

• Describe whether the image is standard, resized, cropped, or recompressed
• Mention which corner to search: bottom-right, bottom-left, etc.
• Mention whether the watermark size looks normal, smaller, or larger
• If known, provide a region directly: x,y,w,h
• If artifacts remain, say whether you want a mild cleanup or stronger cleanup

Examples:

Remove the Gemini watermark from this file.
Try snap search in the bottom-right 200x200 area.
Use custom region 683,1297,52,52.
The first pass worked, but increase strength slightly.
Process this whole folder and skip files with no watermark.

• Use the Skill when you want the agent to infer the CLI flags from normal conversation in a skill-enabled agent.
• Use MCP when you want structured tool calls, explicit arguments, and easier integration with Cursor, Zed, Codex CLI, or any other MCP client.
• In both cases, the user-facing request can stay natural-language; the integration layer is what translates that request into GWT arguments.

Image keeps getting [SKIP] — image was resized/recompressed after generation. Tell the agent: "try snap search" or use remove_watermark_snap.

Residual artifacts still visible — tell the agent: "increase the strength". Escalation: sigma=75, strength=180 → sigma=100, strength=250.

macOS Gatekeeper:

xattr -dr com.apple.quarantine ~/.codex/skills/gwt/bin/GeminiWatermarkTool
# or:
xattr -dr com.apple.quarantine ~/.claude/skills/gwt/bin/GeminiWatermarkTool

Windows SmartScreen:

Unblock-File $env:USERPROFILE\.codex\skills\gwt\bin\GeminiWatermarkTool.exe
# or:
Unblock-File $env:USERPROFILE\.claude\skills\gwt\bin\GeminiWatermarkTool.exe

• GeminiWatermarkTool — core C++ tool
• Technical writeup on Medium — reverse alpha blending deep dive
• SynthID Research Report — why Google's invisible watermark cannot be removed

MIT — see LICENSE