Clipboard-To-Path

Turn Windows clipboard images into local file paths, letting text-only models (e.g., DeepSeek / WorkBuddy) recognize images via the path — bypassing the chat client's image-attachment restriction.

中文文档: 简体中文 | English (current)

---

1. Background & Problem

Many AI tools / text-only models (e.g., DeepSeek) cannot receive images directly. In clients like WorkBuddy:

• When you screenshot and press Ctrl+V, the client detects the "image attachment" and checks whether the current model supports vision
• If the model is text-only (e.g., deepseek-v4-flash), the entire message is rejected — even though the image was saved locally

This tool solves it via "image → path": when you paste after a screenshot, it automatically saves the clipboard image as a local PNG and replaces the clipboard content with a plain-text file path. A plain-text path is not treated as an image attachment, so the message sends normally; you then simply tell the model "recognize this image" and it (with a vision API) reads the path to complete recognition.

Screenshot (Win+Shift+S) → Ctrl+V → auto-save PNG → clipboard becomes path → message sends → model reads path & recognizes

2. Key Features

• 🎯 Whitelist mechanism: converts only in specified apps (e.g., WorkBuddy, WeChat); all other apps behave normally (system behavior, images paste as-is)
• 📁 Per-app directories: each whitelisted app can have its own save sub-directory
• ⚡ Event-driven listening: AutoHotkey v2 OnClipboardChange event, zero polling overhead
• 🧹 Auto cleanup (disk protection): cleans every 30 minutes by default; images unchanged for over 60 minutes are auto-deleted, max 100 files kept (all configurable)
• 📝 Logging with rotation & compression: logs split by day and by size (max 100 MB per file, rolls to -001, -002...); logs older than 7 days auto-compressed to .zip then deleted — no disk bloat
• 🖱️ Tray menu: open save directory / clean now / pause-resume / auto-start / view log / restart / exit
• 🔒 Plain path output: clipboard is replaced with the path text only, no prefix (operation instructions are given by the user to the model)
• 🛡️ Config safety: local config.ini is git-ignored; no API keys/tokens are ever stored in the project
• 📝 Logging: every hit / failure / cleanup is logged for troubleshooting

3. Requirements

Dependency	Version	Notes
Windows	10 / 11	clipboard API required
AutoHotkey v2	≥ 2.0	core runtime (install below)
PowerShell	5.1+	built-in, used for clipboard image saving

4. Directory Structure

The repository is organized by file type and platform, ready for future macOS / Linux support:

Clipboard-To-Path/
├── README.md                 English docs (this page)
├── README.zh.md              Chinese docs
├── LICENSE                   MIT
├── .gitignore
├── docs/                     documentation & references
│   └── references/           third-party reference scripts (not committed)
├── configs/                  config files (cross-platform)
│   ├── config.example.ini    config template (committed)
│   └── config.ini            local config (copied from template, git-ignored)
├── src/                      source code (per-platform)
│   └── windows/
│       └── clipboard-to-path.ahk   main script (AutoHotkey v2)
└── scripts/                  launchers & helper scripts (per-platform)
    └── windows/
        └── start.bat         launcher (auto-locates AutoHotkey v2)
└── tests/                    quality checks (per platform)
    └── windows/
        └── self-check.ahk    quality-check script (8 automated checks)

Future platforms: add src/macos/, src/linux/, scripts/macos/, scripts/linux/; configs/ stays shared.

5. Installation (3 steps)

Step 1: Install AutoHotkey v2

winget install --id AutoHotkey.AutoHotkey --source winget

Note: must explicitly use --source winget (default msstore source may fail with a certificate error). Install location: %LOCALAPPDATA%\Programs\AutoHotkey\v2\ (user-level, no admin needed).

Step 2: Create config

copy configs\config.example.ini configs\config.ini

Edit configs\config.ini as needed (see section 6).

Step 3: Run

Option A (recommended): double-click src\windows\clipboard-to-path.ahk (the .ahk file association is created by AHK v2 setup).

Option B: double-click scripts\windows\start.bat (auto-locates AHK v2 and runs the main script).

On success, a green H tray icon appears in the system tray.

6. Configuration (config.ini)

[General]
SaveRoot=                 ; save root (empty = MyDocuments\Pictures\ClipboardShots)
PasteTemplate=            ; empty = plain path (recommended); ASCII only, e.g. [OCR] {path}
KeepHistory=1             ; 1=save screenshot files, 0=convert without saving
MaxAgeMinutes=60          ; auto-delete files unchanged for this many minutes (0=off)
MaxFiles=100              ; max files kept (0=unlimited)
CleanupIntervalMin=30     ; periodic cleanup interval in minutes
ShowNotification=1        ; tray notification on convert
EnableLog=1               ; write log
LogRetainDays=7           ; delete log files older than this many days
LogMaxSizeMB=100          ; roll over to a new log file beyond this size (MB)
LogCompressOld=1          ; compress expired logs to .zip before deletion (1=on, 0=off)
LogFile=                  ; log path (empty = %TEMP%\clipboard-to-path-YYYYMMDD.log, rotated daily)

[Apps]
; One line per app: name=process_name(wildcard * ok)|window_title_keyword(optional)|save_subdir
; Match rule: active window's process name contains OR title contains the keyword
WorkBuddy=WorkBuddy.exe|WorkBuddy|workbuddy
WeChat=WeChat.exe||wechat

Add an app: add one line under [Apps], then restart the script.

Find an app's process name: Task Manager → Details → Image Name (e.g., WorkBuddy.exe); or tasklist | findstr /i name.

7. Usage

Scenario	Behavior
Screenshot → paste in WorkBuddy	saved to <SaveRoot>\workbuddy\, pastes plain path, message sends normally
Screenshot → paste in WeChat	saved to <SaveRoot>\wechat\, pastes plain path
Screenshot → paste in non-whitelisted app	untouched — normal image paste (system behavior)
Clipboard is not an image (plain text)	always passthrough, never touched

Recognize an image: after the path is pasted, tell the model "recognize this image" / "describe it" / "extract text" (requires the model to read local files and have vision capability, e.g., Aliyun Bailian CLI bl vision describe).

8. Tray Menu

Item	Action
Open save directory	opens the screenshot root in Explorer
Clean now	cleans old files per retention policy
Pause / Resume	one-click passthrough (when not needed temporarily)
Auto-start: on/off	register/unregister HKCU Run entry
View log	opens log (%TEMP%\clipboard-to-path.log)
Restart	reloads the script (apply config changes without manual exit)
Exit	stops the script

9. Quality Check (self-check)

A built-in quality-check script verifies all core features in your real desktop environment (not a sandbox), including the ones that are hard to test elsewhere:

tests/windows/self-check.ahk

Double-click it and wait a few seconds, then open the report: %TEMP%\clipboard-selfcheck-YYYYMMDD.log

#	Check	What it verifies
1	Environment	AHK v2 version, main script file exists
2	Config parsing	whitelist count, SaveRoot, key retention/log settings
3	Log write	daily-named log file creation
4	Clipboard save	clipboard image → PNG save chain (same logic as main script)
5	Size rollover	log file rolls to -001 when over size limit
6	Compression	Compress-Archive produces a .zip
7	Expiry cleanup	DateDiff + delete of files older than retention days
8	Restart	Reload() completes and the script re-enters correctly

All test files live in an isolated %TEMP%\clipboard-selfcheck-tmp\ directory and are cleaned up automatically — no real data is touched. Run it after every code change to catch regressions.

10. FAQ

Q1: No tray icon? Check the "hidden icons" area (^ arrow). If still missing, verify the log file is created after double-clicking the .ahk: %TEMP%\clipboard-to-path.log.

Q2: The launcher window flashes and closes? Double-click src\windows\clipboard-to-path.ahk directly (not start.bat); if using start.bat, make sure it's the pure-ASCII version (a bat containing Chinese may fail under GBK codepage).

Q3: Pasting shows garbled prefix? PasteTemplate with Chinese in config.ini gets misread as GBK. Leave it empty (uses the built-in plain path), or use ASCII only.

Q4: Paste still inserts the image (no conversion)? ① Confirm the tray icon is running; ② confirm the active window's process/title matches the whitelist; ③ check the log for a [hit] record.

Q5: Log shows [fail] save failed? PowerShell is disabled or the save directory is not writable. Verify system PowerShell works and SaveRoot is writable.

Q6: Files pile up and eat disk? Auto-cleanup is built in: every 30 minutes, PNGs unchanged for over 60 minutes are deleted (max 100 kept). Tune MaxAgeMinutes / MaxFiles / CleanupIntervalMin.

11. Design Reference

This tool's design is inspired by:

• cpulxb/WSL-Image-Clipboard-Helper (Rust "clipboard image → path" tool for WSL terminal AI CLIs like Codex / Claude Code / OpenCode)

Key differences: this tool targets Windows-native GUI clients (WorkBuddy), uses whitelist-based auto interception (not a manual hotkey), and adds per-app directories, pause/resume, auto-start, restart and logging.

12. Security

• No key storage: this project contains no API keys / tokens. Model keys (e.g., DASHSCOPE_API_KEY) should live in system environment variables, read by the model-side CLI.
• Local config isolation: config.ini is git-ignored and never committed.
• Whitelist only: clipboard behavior of non-whitelisted apps is completely unaffected.

13. License

MIT.