Greetings from the island nation of Japan. I find myself wondering why, in a world where 59% of developers use Windows, so much of the Claude Code documentation reads like a love letter exclusively addressed to macOS users. Well, I suppose us Windows developers are rather accustomed to being the majority that everyone politely ignores (personally very grateful for this recurring life lesson). My favourite chapter of this saga involved spending a solid thirty minutes dissecting VS Code settings, convinced something was profoundly misconfigured, only to discover the entire ordeal was a matter of pressing Alt+V instead of Ctrl+V. The settings were fine. The documentation simply never mentioned it. This article is my humble attempt to organise every Windows-specific pitfall into one place, so you can skip the part where you question your own competence. Truly.
Table of Contents
- GUI vs Terminal: Which One Are You Running?
- The Ctrl+V Trap: Why Your Screenshots Won't Paste
- VS Code Terminal Image Display Settings
- npm Scripts and Unix Syntax
- Shell Juggling: Git Bash / PowerShell / WSL2
- Cheat Sheet
My Setup
- OS: Windows 11
- Editor: VS Code (when visual confirmation is needed)
- Terminal: Warp (when it's not)
- Claude Code: v2.1.71 / Opus 4.6 / Agent Teams
GUI vs Terminal: Which One Are You Running?
Before diving in, a bit of context. When running Claude Code in VS Code, there are two modes:
| Feature | GUI (WebView) | Terminal (CLI) |
|---|---|---|
| Appearance | VS Code side panel / panel |
> prompt in the integrated terminal |
| Base tech | WebView (browser equivalent) | CLI application |
| Image paste | Ctrl + V works normally | Alt + V (more on this below) |
| Toggle setting | claudeCode.useTerminal: false |
claudeCode.useTerminal: true |
Not knowing this distinction can lead you down a rabbit hole: thinking you're stuck with the terminal version, wondering why images won't paste, and spending half an hour reviewing settings that were perfectly fine all along. That last one is from personal experience.
You can switch between them by toggling claudeCode.useTerminal in VS Code settings.
The Ctrl+V Trap: Why Your Screenshots Won't Paste
Here's the main episode.
One day, I tried pasting a screenshot into terminal-mode Claude Code. Win + Shift + S to capture, Ctrl + V to paste.
Nothing happened.
Text wouldn't paste either. Right-click paste didn't work. Dragging and dropping opened the image file in a separate tab. Not exactly helpful.
The Settings Investigation
First suspect: VS Code terminal settings. Being on Windows, the usual "something environment-related is breaking things" instinct kicked in.
{
"terminal.integrated.enableImages": true
}
Checked. Enabled.
Next, GPU Acceleration, mentioned in the setting description:
{
"terminal.integrated.gpuAcceleration": "auto"
}
Fine.
Then the Windows-specific ConPTY setting:
{
"terminal.integrated.windowsUseConptyDll": true
}
Enabled. The bundled ConPTY DLL (v1.23) was in place.
Everything was correct. Still couldn't paste.
I even went as far as checking the ConPTY DLL version, wondering "it says v2+ is required, but where exactly is v2 in this versioning scheme?"
The Answer
Switching my search language to English, the answer appeared almost immediately.
In terminal-mode Claude Code, you paste images with Alt + V, not Ctrl + V.
On Windows terminals, Ctrl + V is reserved for text paste, so Claude Code assigns image paste to Alt + V.
Tried it. Worked instantly.
Thirty minutes of settings investigation, and it was just a different shortcut key. There was virtually no information about this in Japanese, so here it is.
I also looked into whether Alt + V could be remapped to Ctrl + V, but this is a hardcoded keybinding in the Claude Code CLI. There's no user-configurable option for it. You just have to get used to it. There are open GitHub issues requesting this change, so perhaps the official team will address it eventually.
Quick reference: Image paste in terminal-mode Claude Code
[BUG] Image paste with Ctrl+V not working on Windows (drag-and-drop works)
#9124
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
Title:
Description:
Image pasting via Ctrl+V is no longer working in Claude Code on Windows, though it used to work previously. Drag-and-drop still functions correctly.
Steps to reproduce:
- Copy an image to clipboard (e.g., from a screenshot tool or by copying an image file)
- Open Claude Code in VSCode terminal
- Try to paste the image using Ctrl+V
Expected behavior: The image should be pasted into the conversation, as documented in the https://docs.claude.com/en/docs/claude-code/common-workflows.
Actual behavior: The image does not paste. No error message is shown.
Workaround: Drag-and-drop of images still works correctly.
Environment:
- OS: Windows (MINGW64_NT-10.0-26100 3.5.4-395fda67.x86_64)
- Platform: win32
- Claude Code: [2.0.10
Additional context: This functionality worked previously and appears to be a regression.
The image should be pasted into the conversation, as documented in the https://docs.claude.com/en/docs/claude-code/common-workflows.
The image does not paste. No error message is shown.
- Copy an image to clipboard (e.g., from a screenshot tool or by copying an image file)
- Open Claude Code in VSCode terminal
- Try to paste the image using Ctrl+V
None
Yes, this worked in a previous version
No response
2.0.10
Other
Windows
VS Code integrated terminal
No response
[VS Code] Cannot paste screenshot images with Ctrl+V
#22377
In VS Code's integrated terminal, it's impossible to paste a screenshot image using Ctrl+V. The paste shortcut doesn't work for images copied to the clipboard (e.g., from Windows Snipping Tool or PrintScreen).
- Open Claude Code in VS Code integrated terminal
- Take a screenshot (Win+Shift+S or PrintScreen) - image is now in clipboard
- Try to paste with Ctrl+V in the Claude Code prompt
- Nothing happens / text paste occurs instead of image
Ctrl+V should paste the clipboard image, similar to how it works in:
- Claude.ai web interface
- Other terminal applications that support image paste
- The standalone Claude Code terminal (if supported there)
Ctrl+V does not paste images. Only text paste works.
- Claude Code version: 2.1.x
- VS Code version: 1.96.x
- Platform: Windows 11 + WSL2
- Terminal: VS Code integrated terminal (bash/zsh)
Currently need to:
- Save screenshot to a file
- Use the file path or drag-and-drop
Medium - Significantly slows down workflows involving screenshots, especially for debugging UI issues or sharing visual context.
VS Code Terminal Image Display Settings
If you're using terminal mode, image display requires some VS Code configuration. Even if Alt+V works for pasting, images won't render properly without these settings.
Three settings are needed:
{
// Enable image display in the terminal (default: false)
"terminal.integrated.enableImages": true,
// Keep GPU acceleration enabled ("off" disables image support)
"terminal.integrated.gpuAcceleration": "auto",
// Use VS Code's bundled ConPTY DLL (Windows only)
"terminal.integrated.windowsUseConptyDll": true
}
After changing these, a full VS Code restart is required. Ctrl + Shift + P followed by Reload Window may not be sufficient. Close VS Code entirely and relaunch.
npm Scripts and Unix Syntax
Not Claude Code-specific, but you'll run into this constantly when developing alongside Claude Code.
Say your package.json has this:
{
"scripts": {
"dev": "NODE_OPTIONS='--require ./node-compat.cjs' next dev --turbopack"
}
}
The single-quote environment variable syntax (NODE_OPTIONS='...') is Unix. It won't work in Windows cmd or PowerShell.
# This will fail
npm run dev
Workarounds
1. Run directly via Git Bash
NODE_OPTIONS='--require ./node-compat.cjs' npx next dev --turbopack
Skip npm run dev and execute the command directly in Git Bash, where Unix syntax is supported.
2. Use cross-env
npm install --save-dev cross-env
{
"scripts": {
"dev": "cross-env NODE_OPTIONS='--require ./node-compat.cjs' next dev --turbopack"
}
}
cross-env handles environment variables across Windows, Mac, and Linux. If you're working in a team, it's worth adding.
When Claude Code runs npm run dev and it fails, it sometimes can't identify the cause and starts investigating unrelated issues. Knowing this is a Windows syntax problem lets you point it in the right direction immediately.
Shell Juggling: Git Bash / PowerShell / WSL2
When Claude Code executes commands in VS Code's integrated terminal, which shell is active matters more than you'd expect.
Git Bash, PowerShell, and WSL2 each behave differently, and the same command can produce different results depending on where it runs.
The Path Conversion Trap
Git Bash internally converts Windows paths to Unix paths. This breaks certain commands.
# robocopy in Git Bash: paths get converted and the command fails
robocopy C:\src C:\dst # Paths become /c/src /c/dst
For file operations, PowerShell commands are safer:
# PowerShell: reliable
Move-Item -Path "C:\src\file.txt" -Destination "C:\dst\"
Copy-Item -Path "C:\src\*" -Destination "C:\dst\" -Recurse
Symbolic Links
The Unix ln -s doesn't work as expected in Git Bash on Windows. Use NTFS junctions instead:
mklink /J "C:\link" "C:\target"
Teaching Claude Code
Writing shell guidelines in your CLAUDE.md helps Claude Code pick the right commands:
## Platform Notes
- Prefer PowerShell commands (Move-Item, Copy-Item) for file operations
- Avoid robocopy in Git Bash due to path conversion issues
- Use NTFS junctions (mklink /J) instead of ln -s
I have rules like these in my own CLAUDE.md. Most of them were set up early on, and I haven't had to add much since. Claude Code respects them reliably, which prevents the same mistakes from recurring. It still goes on the occasional unsupervised adventure, but that's becoming rarer.
Cheat Sheet
| Gotcha | Symptom | Fix |
|---|---|---|
| Image paste | Ctrl + V does nothing | Use Alt + V |
| Terminal image display | Images don't render | Enable enableImages, gpuAcceleration, windowsUseConptyDll
|
| npm scripts |
npm run dev fails |
Run directly in Git Bash or add cross-env
|
| Path conversion | Commands fail in Git Bash | Use PowerShell commands |
| Symbolic links |
ln -s doesn't work |
Use mklink /J (NTFS junction) |
| GUI vs Terminal | Confused by different behaviour | Toggle claudeCode.useTerminal
|
Windows requires a bit more setup upfront, but once everything is configured, it runs smoothly.
Top comments (0)