How To Use Screenshots With Claude Code on macOS

Most developers using Claude Code hit the same wall: you need to show it a screenshot, but pasting images into a terminal CLI is not as simple as dragging a file into a chat window. The popular DIY fix involves installing Hammerspoon, writing Lua scripts, and configuring accessibility permissions. But there is a much faster path.

In this guide, we compare the scripted Hammerspoon approach to a one-click solution with SnapCode, and show you how to get screenshots into Claude Code prompts in under a minute.

Key Takeaways

Question	Answer
How do I paste screenshots into Claude Code?	Claude Code accepts image file paths in prompts. You need a tool that captures a screenshot and puts the file path on your clipboard so you can paste it directly into the terminal.
What is the Hammerspoon method?	A DIY approach where you install Hammerspoon (a macOS automation framework), write ~50 lines of Lua, and configure hotkeys to capture and auto-paste screenshots. It works but requires technical setup and ongoing maintenance.
What is the easier alternative?	SnapCode does the same thing in a single install. One keystroke captures, saves, and copies the file path. No scripting required.
Does this work with other AI tools?	Yes. Any AI tool that accepts file paths or images, including Cursor, Windsurf, Gemini CLI, and Copilot, works with the same clipboard workflow.
How much does it cost?	Hammerspoon is free but costs you setup time. SnapCode is a one-time $10 purchase with zero configuration.

The Problem: Getting Screenshots Into A Terminal CLI

Claude Code runs in your terminal. Unlike the web version of Claude, you cannot drag and drop an image. You need to either:

Reference a file path in your prompt (e.g., look at /Users/me/Screenshots/bug.png)
Paste an image directly from your clipboard (supported in some terminal emulators like Ghostty and iTerm2)

Both approaches require that your screenshot ends up in a predictable location or on your clipboard in the right format. The default macOS screenshot shortcuts (Cmd+Shift+4) save files to the desktop with random timestamps, which means you are hunting through Finder every time.

The Hard Way: Hammerspoon + Lua Scripting

What is Hammerspoon?

Hammerspoon is a free, open-source macOS automation tool that uses Lua scripts. It is powerful but designed for developers who are comfortable writing and maintaining configuration files.

What the setup looks like

To get screenshots into Claude Code with Hammerspoon, you need to:

Install Hammerspoon via Homebrew (brew install --cask hammerspoon)
Grant it Accessibility permissions in System Settings
Write a Lua script in ~/.hammerspoon/init.lua that:
- Binds a custom hotkey (e.g., Cmd+Shift+6)
- Calls the macOS screencapture command
- Monitors which terminal window was last focused
- Auto-pastes the result into that window
Reload the Hammerspoon config every time you make changes
Debug edge cases like concurrent captures, window tracking, and clipboard timing

The downsides

~50 lines of Lua to maintain: If Hammerspoon updates or macOS changes accessibility APIs, your script may break.
Terminal-specific: Most implementations are hardcoded to one terminal emulator (usually Ghostty). Switch to iTerm2 or Warp and you need to rewrite the window-matching logic.
No file path on clipboard: The typical Hammerspoon approach puts the image data on the clipboard, not the file path. This works for direct paste but not for referencing screenshots later or using them across tools.
Accessibility permissions: Hammerspoon needs broad accessibility access, which some organizations restrict.
No organization: Screenshots are either discarded after paste or saved to a generic folder with no naming convention.

The Easy Way: SnapCode

SnapCode was built specifically for this workflow. It is a native macOS app that:

Captures with one keystroke: Press your shortcut, select the area, done.
Copies the file path to your clipboard: Paste it directly into Claude Code, Cursor, or any terminal.
Saves to a consistent folder: Every screenshot is organized and findable.
Works with every terminal: Terminal.app, iTerm2, Ghostty, Warp, Kitty, Alacritty, it does not matter.
Zero configuration: Install, set your shortcut, start capturing.

Example workflow with Claude Code

Press your SnapCode hotkey
Select the area of the screen you want to capture
The file path is now on your clipboard
In Claude Code, type your prompt and paste: Fix the layout bug shown in /Users/me/Screenshots/snap-2026-02-17-1.png
Claude Code sees the image and responds with a fix

Total time: under 5 seconds. No scripting, no debugging, no Lua.

Side-By-Side Comparison

Feature	Hammerspoon (DIY)	SnapCode
Setup time	15-30 minutes	Under 1 minute
Code required	~50 lines of Lua	None
Terminal support	One at a time (hardcoded)	All terminal emulators
File path on clipboard	Not by default	Yes, always
Screenshot organization	None	Auto-organized folder
Works with Claude, Cursor, Gemini	Claude Code only (paste-based)	Any tool that accepts file paths
Maintenance	You maintain the script	Automatic updates
Price	Free (+ your time)	$10 one-time

When Hammerspoon Makes Sense

To be fair, Hammerspoon is a great tool if:

You already use it for other macOS automations and want to add screenshot capture to your existing config
You enjoy tinkering with Lua and want full control over every aspect of the capture process
You specifically need clipboard-based image paste (not file paths) into a single terminal emulator

For everyone else, the time you spend writing and debugging a Lua script is better spent actually coding.

Setting Up SnapCode In 60 Seconds

Download SnapCode from snapcode.cc
Open the app and set your preferred capture hotkey
Take your first screenshot
Paste the file path into Claude Code and start prompting

That is the entire setup. No Homebrew, no Lua, no accessibility permission dialogs, no config files to maintain.

Beyond Claude Code: Universal Screenshot Workflow

The file-path-on-clipboard approach is more versatile than clipboard image paste because it works everywhere:

Claude Code: Paste the path directly in your prompt
Cursor / Windsurf: Reference screenshots in AI chat
Gemini CLI: Include image paths in multi-modal prompts
Git commits: Reference screenshots in commit messages or PR descriptions
Slack / Discord: Quickly find and share the right screenshot
Bug trackers: Attach organized, named screenshots instead of random desktop files

Conclusion

Getting screenshots into Claude Code should not require writing a Lua script. If you are a developer who values your time, SnapCode gives you the same result as the Hammerspoon approach, in a fraction of the setup time, with better organization and universal terminal support.

The best screenshot workflow is the one you do not have to think about. Install SnapCode, set a hotkey, and get back to building.

Download SnapCode