The Idea
The fix seemed obvious: Ctrl+V should be context-aware. If I'm in a terminal and I have an image on my clipboard, I probably want the file path, not the image data. If I'm in a text editor, paste normally. If I'm in a browser, paste normally.
The key insight is that the behavior should be invisible. I didn't want a new command to memorize. I wanted Ctrl+V to just do the right thing depending on where I was.
How It Works
TCP has two layers.
The keyboard layer is an AutoHotkey v2 script that runs in the background as a tray process. It intercepts Ctrl+V at the OS level. When you press it, AHK checks which window is focused. If it's a terminal, it hands off to the Python core. If it's not, it does nothing and lets the normal paste go through.
The Python core handles the logic:
- Inspect the clipboard — is there image data?
- If yes: check the OS screenshot folder for a file that matches, using a recency window (default: 5 seconds). If the screenshot was captured in the last 5 seconds, it's almost certainly the one you want.
- If a match exists: type the full file path into the terminal.
- If no match exists: save the clipboard image to disk, then type the path.
- If no image in clipboard: fall back to normal paste behavior.
Alt+V is the override: it force-pastes the image path regardless of which window is focused. Useful when you're pasting into a GUI app that isn't a terminal but still needs a path.
Zero Config by Design
I made a deliberate choice to require no setup. TCP works the moment you install it.
Screenshot folder detection is automatic on every platform — Windows registry keys, macOS defaults, and XDG paths on Linux. No config file needed for the common case.
Terminal detection uses a built-in list of process names: WindowsTerminal.exe, powershell.exe, pwsh.exe, cmd.exe, Code.exe, warp.exe, alacritty.exe, mintty.exe. You can add more in %APPDATA%\tcp\config.toml if your terminal isn't covered.
The config file is optional TOML for users who want to customize anything:
save_dir = "" # Auto-detected from OS settings
filename_pattern = "tcp_%Y%m%d_%H%M%S.png"
recency_window = 5 # Seconds
format = "png"
path_style = "native" # native, forward, or backslash
extra_terminals = ["hyper.exe"]
Why AutoHotkey
Keyboard interception at the OS level on Windows comes down to a few options: raw Win32 hooks in C/C++, PowerShell with P/Invoke, or AHK. I chose AHK because it's mature, well-understood in the Windows power-user community, and the v2 API is clean. The shim is about 50 lines. It does one thing: intercept hotkeys and shell out to Python.
The Python core is where the logic lives. That also means it's cross-platform — the core already works on macOS and Linux. The missing piece for those platforms is just the hotkey interception layer (Swift/Hammerspoon for macOS, xdotool for Linux). That's on the roadmap.
What I Learned
The hardest part wasn't the clipboard logic or the file matching — it was getting the AHK keystroke injection right. When TCP types a file path into a terminal, it uses AHK's Send function. Early versions had a bug where modifier keys (Ctrl, Shift) from the intercepted hotkey would "leak" into the sent keystrokes, garbling the output. The fix was using {Raw} and {Blind} mode in AHK to ensure the send is clean.
The second tricky part was the clipboard-swap approach for Ctrl+V passthrough. When TCP determines the paste should be a normal text paste, it needs to let the keypress go through as-is. Getting that right without synthetic keystrokes or double-fires took a few iterations.
What's Next
- macOS support (the Swift hotkey shim is the main missing piece)
- Linux support (xdotool-based shim)
- Optional path quoting for paths with spaces
- Watcher mode — detect new screenshots in real time and pre-cache the path so the first Ctrl+V is instant even if the file write is slow
Try It
TCP is free. BSL 1.1 — free for all use.
One-click installer: TCPSetup.exe
PowerShell one-liner:
irm https://raw.githubusercontent.com/CodeWarrior4Life/TerminalCopyPaste/main/install.ps1 | iex
Repo: https://github.com/CodeWarrior4Life/TerminalCopyPaste
If you use Claude Code, Codex CLI, Aider, or any terminal-heavy workflow, give it a try.
If you found this useful, consider buying me a coffee to keep the ideas flowing. ☕ It's the kind of tool that becomes invisible after a day — which is exactly what I was going for.
Top comments (1)
Path hunting is only half the problem though. Once the screenshot actually reaches the model, a full page capture gets resized down to something like 1568px on the long edge, so anything past a single screen worth of content turns into a blur before the agent even reads it.
For Claude Code and Cursor specifically, SlimSnap.ai skips the image step and sends the capture as structured JSON through an MCP server. Codex isn't supported there yet, tool result size cap in Codex drops images with structured output, open issue upstream.