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 (0)