Smugshot

A pointing tool for working with AI agents. It's "screenshot" crossed with "mugshot", taken by someone who already knows they're right.

Press a hotkey, drag over part of your screen, paste a path into a chat with an agent that can read your disk. The agent gets the whole screen with your part outlined, a sharp close-up, and a small text file that says what it is looking at. There is no editor and no annotation step. The drag is the whole gesture.

Mac (macOS 15 or later) is the full version. There is a first Windows version with the gesture only; see the end.

Download: https://smugshot.io, free. Or read the code here and build it yourself; see "Check it yourself" at the end.

Use it

1. Press Command + Shift + 1 (changeable in Settings). The screen freezes and dims slightly, like the Mac's own Command + Shift + 4, so a hover state or a tooltip you had showing stays visible while you drag.

2. Drag over the thing you want to show.

3. You hear a short sound (choose which in Settings). Paste into the chat. It looks like this:

   smugshot: /Users/you/.smugshots/2026-09-17-202006/shot.md
   

To cancel: Esc, a right-click, a click without dragging, or the hotkey again.

Paste it for me (off by default; the Paste into setting): after the drag, Smugshot brings an app to the front and presses ⌘V there, so the path lands where the cursor is. It never presses Enter; you still send it. Pick "The app I came from" (the app in front when you pressed the shortcut, usually your terminal) or a fixed app. While the screen is frozen, a line at the top says where it will paste, and pressing the shortcut's key on its own (1 for the default shortcut) switches pasting on or off for that one smugshot. It also works when the setting is off: press 1 and that one smugshot is pasted into the app you came from.

The menu bar menu has Copy last smugshot again for one more question about the same thing, Recent smugshots with the last five (a thumbnail and the app; hold Option to show one in Finder instead), and Quiet for calls and screen shares: no sound, no icon flash. What's new shows what changed in each version. Check for updates… shows the version you have and opens smugshot.io in your browser, where the newest version is named; Smugshot itself never goes online, so it does not check or update on its own.

The word in front of the path is there on purpose. A message that starts with / is read as a command by Claude Code and other chat tools.

What a smugshot is

~/.smugshots/2026-09-17-202006/
  shot.md     the path on your clipboard; explains itself to any agent
  full.png    whole screen, your part outlined, the rest dimmed
  crop.png    your part at full sharpness, with some margin

shot.md tells the agent, in this order of trust:

• Web element (Brave, Chrome, Edge, Arc, Vivaldi, Safari): the HTML of the page element you dragged over, a selector, data-testid, and on React dev sites the component names. This is what you would otherwise copy by hand with right-click, Inspect.
• What was there: the actual control under the drag (role, label, state, and for web pages the DOM id and classes), its parents up to the window, and what else sits inside the dragged area. It comes from the Mac's accessibility layer, the one screen readers use, so it works in any well-built app.
• Text read from the close-up: recognised on your Mac from the picture. It is there even in apps that publish nothing, like games and canvas apps.
• The app, the window title and, in a browser, the page address.

Two pictures because agents shrink big images before the model sees them (Claude Code to 2000 pixels on the long side). On a Retina screen that blurs small text, so the close-up is kept sharp and both pictures are capped at 2000 pixels.

Each smugshot deletes itself after a day unless you change that in Settings. The folder is readable only by you, skipped by Spotlight, excluded from Time Machine, and outside anything iCloud syncs.

Know this: a smugshot pictures the whole screen. Whatever else is visible (a password manager, tokens in a terminal, another chat) goes to the model provider along with the part you pointed at.

Install from source

You need Xcode's command line tools (Swift 6). Nothing else; the app has no dependencies.

./scripts/make-cert.sh        # once: a self-signed signing certificate (asks for your Mac password)
./scripts/build.sh --install  # builds, signs, copies to /Applications, starts it

Then give it its permissions. All three are asked for once and survive rebuilds:

Teach Claude Code to read a smugshot without being told how:

./scripts/install-claude-skill.sh   # installs the skill, and lets Claude Code read ~/.smugshots without asking

Why the certificate: without a stable signature, macOS sees every rebuild as a new app and forgets the permission. With it, rebuilds keep working.

Settings

Settings… in the menu bar menu (or ⌘,) opens a small window. Every change applies at once.

The same settings from the command line, with no restart needed:

defaults write com.pjalle.smugshot folder -string "$HOME/Desktop/shots"
defaults write com.pjalle.smugshot keepFor -string 5m           # 1m, 2m, 5m, 10m, 30m, 1h, 1d, 1w, forever
defaults write com.pjalle.smugshot prefix -string "look: "
defaults write com.pjalle.smugshot pasteInto -string previous    # or a bundle id such as com.mitchellh.ghostty; delete to switch off
defaults write com.pjalle.smugshot readText -bool false         # also nameControls, webElement
defaults write com.pjalle.smugshot quiet -bool true
defaults write com.pjalle.smugshot sound -string pop            # screen-capture, shutter, frog, pop, sent, tink
defaults write com.pjalle.smugshot hotkeyKeyCode -int 18        # 18 is the "1" key
defaults write com.pjalle.smugshot hotkeyModifiers -int 768     # 256 Command + 512 Shift (2048 Option, 4096 Control)
defaults delete com.pjalle.smugshot folder                      # back to the default

Working on it

• Sources/Smugshot/: HotKey (system hotkey), Capturer (the picture), Overlay (the drag layer), Renderer (full.png and crop.png), Accessibility (what was there), Paster (paste it for me: bring an app forward and press ⌘V, and the list of known apps), TextReader (text from the close-up), Browser (the web element), Store (the folder, cleanup, shot.md), Settings (the settings, the retention presets, the shortcut and key names), SettingsWindow, WhatsNewWindow (the changelog in the app; build.sh puts it there, without the lines that are not about the app), AppDelegate (the gesture and the menu), MenuBarIcon.
• agents/claude-skill/: the Claude Code skill. design/chosen/: the icon, drawn from geometry by python3 scripts/draw-icon.py (needs Pillow); swift scripts/make-icon.swift then rebuilds Resources/AppIcon.icns.
• Testing without hands on the mouse: defaults write com.pjalle.smugshot enableTestHook -bool true, restart, and see the comment above installTestHook in AppDelegate.swift. ./scripts/build.sh without SMUGSHOT_VERSION gives the app the newest version number in CHANGELOG.md.

Windows

windows/ holds a first Windows version written in Go, built from any machine with ./scripts/build-windows.sh. Press Ctrl + Shift + 1, drag, paste; it writes the same three files to %USERPROFILE%\.smugshots\ and sits in the system tray.

Its settings are a small file, %APPDATA%\Smugshot\settings.json, opened from Settings… in the tray menu: the folder, keepFor (the same values as on the Mac), the clipboard text, the hotkey (ctrl+shift+1, ctrl+alt+s, win+shift+f9; needs a restart), and sound and banner for the tink and the small "Copied" banner after a smugshot. Other changes apply to the next smugshot. The tray menu also has "Copy last smugshot again", the last five smugshots, the Sound and Banner switches, and "Check for updates…", which opens smugshot.io in your browser.

It has the gesture only: no "what was there", no text reading, no web element, no "paste into" yet. It was first run on a real Windows machine on 2026-09-18, and the gesture works. Since 2026-09-19 it also runs on a Windows laptop of ours, with 0.3.2, after Defender was told to allow it. When it starts, a banner at the bottom right says it is running and names the hotkey; starting it a second time only shows "already running".

Check it yourself

Smugshot sees your whole screen, so you should not have to take anyone's word for what it does with it. This is the code the downloads on smugshot.io are built from.

• It never goes online. There is no network code in the app. Look for yourself: grep -rnE "URLSession|URLRequest|NWConnection|CFNetwork" Sources/ and grep -rn '"net' windows/ both find nothing.
• No account, no telemetry, no updater. A smugshot is three files in a folder on your own disk (Sources/Smugshot/Store.swift, windows/store.go), and the folder deletes itself after the time you set.
• What it reads: the screen (Capturer.swift), the control under your drag through the accessibility layer (Accessibility.swift), text from the close-up, recognised on your Mac (TextReader.swift), and in a browser the page element you dragged over (Browser.swift). Each can be switched off in Settings.
• Point your agent at it. The code is small: about a dozen Swift files and half a dozen Go files, with no dependencies beyond what the system and the language ship with (Package.swift, windows/go.mod).
• Or build it yourself instead of downloading: "Install from source" above, or ./scripts/build-windows.sh for Windows (needs Go).
• The downloads are here too. Each release carries the same Mac and Windows files as smugshot.io, made from the tagged code.

Readable source does not prove that a download was built from it. If that matters to you, build your own copy.

Licence

The app is source-available under the Functional Source License (FSL-1.1-MIT): read it, build it, change it and use it, for anything except offering a competing product. Each version becomes plain MIT two years after its release.

The Claude Code skill in agents/claude-skill/ and the shape of shot.md are MIT from the start (agents/claude-skill/LICENSE), so other tools and agents are free to read and write smugshots.

Questions, bugs, ideas: open an issue, or [email protected].

Please open an issue rather than a pull request. This repo is written fresh from a private one at each release, so a change merged here would be lost at the next. A good fix described in an issue gets made there, with thanks.