WSL-Image-Clipboard-Helper: Windows 클립보드 이미지를 AI CLI 도구용 WSL 경로로 변환하는 도구

Windows 클립보드의 이미지를 AI CLI 도구에서 즉시 사용할 수 있는 WSL 경로로 변환하는 하나의 단축키.

현재 많은 지능형 프로그래밍 CLI Agent (예: Codex, Amazon Q Developer CLI, OpenCode, Claude Code 등)는 주로 Linux 및 macOS 시스템에 최적화되어 있습니다. Windows 사용자가 이러한 도구들을 경험하려면 일반적으로 WSL2 (Windows Subsystem for Linux 2)를 통해 실행해야 합니다. 그러나 WSL2는 일부 기능 지원이 완벽하지 않으며, 이미지 붙여넣기는 그 중 대표적인 불편 사항 중 하나입니다:

• 문제: WSL2 터미널이 Windows 클립보드 내의 이미지 데이터에 직접 접근할 수 없음
• 영향: 사용자가 네이티브 Linux/macOS에서처럼 스크린샷을 AI 도구에 직접 붙여넣어 분석할 수 없음
• 현황: 일부 AI CLI 도구는 "이미지를 파일로 저장 -> 파일 경로 전달" 방식을 통해 우회적으로 이미지 입력을 지원함

본 도구는 이 간극을 메우기 위해 제작되었습니다. 전역 단축키(기본값 Alt+V)를 통해 Windows 클립보드 이미지를 자동으로 읽어 로컬 temp/ 디렉토리에 저장하고, 해당 WSL 경로(/mnt/c/...)를 현재 입력창에 붙여넣어 AI 도구가 이미지 파일을 직접 소비할 수 있게 합니다.

현재 주 버전은 Rust로 구현되었습니다 (v4.0). GitHub Release v4.0 또는 최신(latest) 릴리스의 사전 컴파일된 버전을 직접 다운로드하는 것을 권장합니다.

• 🚀 즉각적인 경로 출력: 단축키 트리거 후 /mnt/... 경로를 우선적으로 붙여넣어 대기 시간을 단축
• ⚡ 이미지 비동기 저장: 경로를 먼저 사용 가능하게 하고 이미지 파일은 백그라운드에서 작성하여 메인 프로세스의 차단을 방지
• 🌐 입력기 보호 (안전 모드): 붙여넣기 전 영문 입력기로 전환하고, 종료 후 자동으로 복구
• 🧹 자동 정리 메커니즘: 만료된 PNG를 주기적으로 정리하고, 종료 시 임시 이미지를 삭제
• 🖱️ 트레이 관리: 단축키 변경, 실행 모드 전환, 임시 이미지 디렉토리 열기, 종료 및 임시 이미지 정리 지원
• 🛡️ 이미지 읽기 경계 보호: DIB 헤더 및 메모리 크기에 대한 안전 검증을 수행하여 비정상적인 데이터로 인한 충돌 방지
• 🪟 Windows 통합: 다양한 크기의 아이콘이 내장되어 있으며, DPI-aware manifest를 포함하여 고해상도(High DPI) 환경에서 더 안정적으로 표시됨
• 📁 Explorer 경로 변환: 파일 탐색기에서 파일을 복사한 후 Alt+V를 누르면 변환된 /mnt/... 경로가 붙여넣어짐

이 이미지를 예로 들면, Codex, Claude Code, OpenCode에 붙여넣었을 때 모두 정상적으로 작동합니다 (다른 Agent 도구에서도 직접 시도해 볼 수 있습니다). 붙여넣을 때 자동으로 [Image #n] 형식을 인식하며, 이 형식으로 변환할 수 없는 경우에는 입력창에 경로 형태로 표시됩니다.

codex
claude
openCode

• Windows 10/11, WSL2 활성화 상태
• PowerShell 5.1 이상
• Rust 툴체인 (Rust 버전을 직접 컴파일해야 하는 경우에만 필요)
• AutoHotkey v2 (기존 AHK 프로세스를 유지하거나 직접 AHK 실행 파일을 작성하는 경우에만 필요)

WSL-Image-Clipboard-Helper/
├── README.md
├── docs/ # 문서 기록
...

• 가장 간단한 방법 (권장): GitHub Release에서 컴파일된 버전을 다운로드하세요:

• 다운로드한 wsl_clipboard.exe를 고정된 디렉토리에 넣으세요. Releases 압축 파일 내 디렉토리 구조:
  WSL-Image-Clipboard-Helper/ ├── wsl_clipboard.exe # 직접 사용을 권장하는 사전 컴파일된 실행 파일 (Rust 버전) ├── temp/ # 실행 시 임시 이미지 디렉토리 ├── wsl_clipboard.toml # 실행 시 자동 생성되며 관련 설정을 저장함, 삭제하지 마세요

• wsl_clipboard.exe를 더블 클릭하여 실행합니다.

• 편집 가능한 모든 입력창에서 단축키(기본 Alt+V)를 누릅니다:

  • 이미지가 있는 경우: temp/에 저장하고 /mnt/... 경로를 붙여넣음
  • 이미지가 없는 경우: 자동으로 일반 붙여넣기 (Ctrl+V)로 전환

• 파일 탐색기(Explorer)에서 파일을 먼저 복사한 후 Alt+V를 누릅니다: 변환된 WSL 경로(예: /mnt/c/...)를 붙여넣음

  • 이미지가 있는 경우: 저장됨

• 트레이 메뉴를 통해 단축키와 실행 모드를 전환합니다.

• 종료 시 트레이 메뉴에서 종료 및 임시 이미지 정리(Exit and clean temporary images)를 선택하면 temp/ 아래의 임시 PNG 파일이 삭제됩니다.

직접 컴파일이 필요한 경우, 아래의 소스 코드 방식을 사용하세요:

• 저장소를 클론하고 디렉토리로 이동합니다:
  git clone https://github.com/cpulxb/WSL-Image-Clipboard-Helper.git cd WSL-Image-Clipboard-Helper

• 아래의 “Rust 버전 컴파일 (추천)” 단계를 따라 컴파일을 완료하세요.

• 컴파일 결과물을 실행합니다.
  wsl_clipboard.exe

• 기본 단축키는 Alt+V이며, 트레이 메뉴에서 Ctrl+Alt+V 또는 Alt+Enter로 변경할 수 있습니다.

• 실행 설정은 wsl_clipboard.toml (실행 파일과 동일한 디렉토리)에 저장됩니다.

• 트레이 메뉴의 종료 및 임시 이미지 정리 (Exit and Clean Temporary Images)를 선택하면 temp/ 디렉토리 아래의 임시 PNG 파일이 삭제됩니다.

• 입력기 (IME)로 인해 붙여넣기 오류가 발생하는 경우, 호환 모드 (입력기 보호) (Compatible Mode (IME Protection))로 전환하세요.

• 트레이 아이콘이 표시되지 않으면 작업 표시줄의 숨겨진 아이콘 영역을 확인하세요.

저장소 루트 디렉토리에서 실행:

cd rust
cargo build --release --target x86_64-pc-windows-msvc

컴파일 결과물:

rust/target/x86_64-pc-windows-msvc/release/wsl_clipboard.exe

디버그 빌드:

cd rust
cargo build --target x86_64-pc-windows-msvc

빌드 결과물 정리:

cd rust
cargo clean

v3.0 AHK 브랜치를 유지 관리하는 경우, Ahk2Exe를 사용하여 다시 컴파일할 수 있습니다:

• AutoHotkey v2 설치:
  https://www.autohotkey.com/download/ahk-v2.exe

• C:\Program Files\AutoHotkey\Compiler\Ahk2Exe.exe를 엽니다.

• Source에서 scripts/wsl_clipboard.ahk를 선택합니다.

• Destination에서 출력 경로(예: scripts/wsl_clipboard.exe)를 선택합니다.

• Base File은 AutoHotkey64.exe 사용을 권장합니다.

• 주요 프로세스를 Rust로 마이그레이션하여 유지보수성 향상

• DIB 픽셀 오프셋 해석 문제를 수정하여 이미지 호환성 개선

• 클립보드 메모리 경계 검증을 추가하여 경계 외 읽기 (Out-of-bounds read) 위험 방지

• 단축키 전환 시 롤백 메커니즘을 추가하여 전환 실패 시 단축키를 사용할 수 없는 상황 방지

• 예외 분기에서 클립보드 해제를 보완하여 리소스 점유 위험 감소

• 다중 크기 애플리케이션 아이콘 내장 및 DPI-aware 매니페스트 추가

• Explorer에서 파일을 복사한 후 Alt+V를 사용하여 /mnt/... 경로로 변환 및 붙여넣기 지원

• 여전히 AHK 기반임

• 단축키 경험 및 설정 가능성에 중점적으로 최적화

• 트레이 상호작용을 더욱 개선

• 경로 저장을 비동기 방식으로 우선 처리하여 체감 지연 시간 대폭 감소

• 입력기 보호 및 자동 정리 메커니즘 도입

• 기본적인 클립보드 이미지 동기화 기능

• SHA256 중복 제거 및 캐시 관리

많은 AI CLI 에이전트 (Codex, Amazon Q Developer CLI, OpenCode, Claude Code 등)는 Linux/macOS 워크플로우에 최적화되어 있습니다. Windows 사용자는 보통 WSL2에 의존하지만, 클립보드 이미지 처리에는 여전히 실질적인 격차가 존재합니다:

• 문제점: WSL2 터미널은 Windows 클립보드에서 이미지 바이트를 직접 가져올 수 없음
• 영향: 스크린샷을 에이전트로 전달하는 흐름이 네이티브 Linux/macOS보다 덜 직관적임
• 우회 방법: 이미지를 파일로 저장한 뒤 해당 파일 경로를 도구에 전달해야 함

이 프로젝트는 전역 단축키 (기본값 Alt+V)를 통해 해당 우회 방법을 자동화합니다. 클립보드 이미지 데이터를 캡처하여 PNG 파일로 저장한 뒤, 활성화된 입력 컨트롤에 WSL 경로 (/mnt/...)를 붙여넣습니다.

현재 메인라인 릴리스는 Rust 기반 (v4.0)입니다. 권장되는 방법은 GitHub Release의 사전 빌드된 v4.0 또는 최신 릴리스를 다운로드하는 것입니다.

• 🚀 빠른 경로 우선 붙여넣기 (Fast path-first paste) 워크플로우
• ⚡ 비동기 이미지 영속성 (Async image persistence)
• 🌐 안전 모드에서의 IME 가드 (IME guard)
• 🖱️ 트레이 기반 단축키 및 모드 전환
• 🧹 임시 PNG 파일 자동 정리
• 🛡️ 메모리 제한 검사를 통한 더 안전한 클립보드 파싱
• 🪟 내장된 다양한 크기의 앱 아이콘 및 DPI 인식 (DPI-aware) 매니페스트
• 📁 탐색기 파일 경로 변환: 탐색기에서 파일을 복사한 후, Alt+V를 눌러 /mnt/... 경로를 붙여넣기

이 이미지를 예로 들면, Codex, Claude Code, OpenCode에서 붙여넣기가 올바르게 작동합니다 (다른 에이전트 도구에서도 시도해 볼 수 있습니다). 붙여넣기 시 많은 도구들이 이미지를 [Image #n]으로 렌더링하며, 해당 렌더링 경로를 사용할 수 없는 경우 입력값은 텍스트 상자에 파일 경로를 표시하는 방식으로 대체(fallback)됩니다.

codex

claude

openCode

• WSL2가 설치된 Windows 10/11
• PowerShell 5.1 이상
• Rust 툴체인 (Rust 버전을 빌드하는 경우)
• AutoHotkey v2 (v3.0 기반의 AHK 버전을 유지하는 경우에만 필요)

WSL-Image-Clipboard-Helper/
├── README.md
├── docs/
...

• 가장 쉬운 방법 (권장): GitHub Releases에서 사전 빌드된 패키지를 다운로드합니다.

• wsl_clipboard.exe를 고정된 폴더(temp/ 및 wsl_clipboard.toml이 있는 폴더가 이상적임)에 넣습니다.

• wsl_clipboard.exe를 실행합니다.

• 편집 가능한 모든 필드에서 단축키(기본값 Alt+V)를 누릅니다:

  • 클립보드에 이미지가 있는 경우: temp/에 저장하고 /mnt/... 경로를 붙여넣습니다.
  • 클립보드에 이미지가 없는 경우: 자동으로 일반 붙여넣기(Ctrl+V)로 전환됩니다.
  • 탐색기에서 하나 이상의 파일을 복사한 후, Alt+V를 눌러 /mnt/c/...와 같은 WSL 경로를 붙여넣습니다.

• 클립보드에 이미지가 있는 경우: temp/에 저장합니다.

• 트레이 메뉴를 사용하여 단축키/모드를 전환하고, 종료 시 Exit and clean temporary images를 선택합니다.

• 기본 단축키는 Alt+V이며, 트레이 메뉴를 통해 Ctrl+Alt+V 또는 Alt+Enter로 변경할 수 있습니다.

• 런타임 설정은 실행 파일 옆의 wsl_clipboard.toml에 저장됩니다.

• Exit and clean temporary images는 temp/ 아래의 임시 PNG 파일들을 삭제합니다.

• IME 상태로 인해 붙여넣기 문제가 발생하는 경우, Compatibility mode (IME guard)로 전환하십시오.

. - 트레이 아이콘이 보이지 않는다면, Windows 작업 표시줄의 숨겨진 아이콘 영역을 확인하십시오.

소스 코드로 직접 빌드(Building from source)하는 것을 선호하는 경우:

• 저장소(Repository) 복제:
  git clone https://github.com/cpulxb/WSL-Image-Clipboard-Helper.git cd WSL-Image-Clipboard-Helper

• 다음 섹션의 명령어를 사용하여 빌드하십시오.

• 빌드된 wsl_clipboard.exe를 실행하십시오.

.

cd rust
cargo build --release --target x86_64-pc-windows-msvc

바이너리(Binary) 출력 위치:

rust/target/x86_64-pc-windows-msvc/release/wsl_clipboard.exe

빌드 결과물(Artifacts) 삭제:

cd rust
cargo clean

v4.0

: 다중 크기 아이콘 임베딩, DPI 인식(DPI-aware) 매니페스트, 그리고 Explorer에서 WSL로의 경로 붙여넣기 기능이 포함된 Rust 메인라인 릴리스(Mainline release)

v3.0

: AHK(AutoHotkey) 기반의 단축키 중심 개정판

v2.0

: AHK 경로 우선 최적화

v1.0

: AHK 베이스라인 (Baseline)