claude-ss

Frictionless screenshot workflow for Claude Code.

Press cmd+shift+2 anywhere on macOS. Drag to capture. Switch to your Claude Code terminal — every screenshot you took gets pasted in order, automatically. No file juggling, no clipboard overwrite, no screen jumping.

Status: v0.1 (macOS only). Linux / Windows on the roadmap.

Why

The default macOS screenshot → Claude Code flow is clunky:

• cmd+shift+4 → drag → screenshot dumps to Desktop
• Hunt for the file, drag it in. Or use the lesser-known ctrl+cmd+shift+4 for clipboard.
• Switch tab, cmd+v, wait, repeat.
• Want to attach 3 screenshots in one turn? Clipboard only holds the last one.

claude-ss collapses this to:

hotkey → drag → done. Multi-shot supported. Works across terminals (Terminal, iTerm2, cmux, Warp, etc.).

Install

git clone https://github.com/jidohyun/claude-ss ~/Desktop/claude-ss
cd ~/Desktop/claude-ss
npm install              # also builds the Swift IME helper + chmods the keyserver
npm link                 # makes `claude-ss` available globally
claude-ss setup          # walks you through the 3 macOS permissions
claude-ss start          # launch the background daemon

Link as a Claude Code plugin so the /ss slash commands work:

mkdir -p ~/.claude/plugins
ln -s ~/Desktop/claude-ss ~/.claude/plugins/claude-ss

Restart Claude Code. You should see /ss, /ss-all, /ss-clear in the slash menu.

Permissions

macOS requires three separate permissions. claude-ss setup probes and opens each pane:

| Permission | Why | |---|---| | Accessibility (손쉬운 사용) | Send cmd+v keystrokes to your terminal | | Screen Recording (화면 및 시스템 오디오 녹음) | Run screencapture for area capture | | Input Monitoring (입력 모니터링) | Detect the global cmd+shift+2 hotkey |

After granting any permission, you must restart the host app (the terminal you launched claude-ss from). macOS caches the denial at process-start time.

If something silently fails after granting, toggle the app OFF → ON in System Settings and restart it again. This is a common macOS TCC caching quirk — it's not a bug in claude-ss.

How it works

[Browser]  cmd+shift+2  →  drag  →  screenshot saved to ~/.claude/screenshots/, clipboard copied
[Browser]  cmd+shift+2  →  drag  →  2nd screenshot queued
[Browser]  cmd+shift+2  →  drag  →  3rd screenshot queued
[Click Claude Code terminal]  →  claude-ss detects focus  →  pastes 3 images in order

Two modes:

Auto last-active (default)

claude-ss tracks which terminal you most recently used with a claude process. When you press cmd+shift+2 from anywhere and later return to that terminal, the queue flushes automatically.

No setup needed. Just use it.

Pinned target (recommended for tmux / multi-session setups)

If you run several Claude Code sessions across multiple terminals, or use tmux / iTerm2 -CC mode, pin a specific window as the paste target:

# Focus the exact Claude Code window you want screenshots to go to
claude-ss target set

# Later, if you want to reset:
claude-ss target clear

Pinned mode records the iTerm2 session ID (when available) so it survives even complex tmux-control-master setups. The daemon pastes into that specific session when it becomes frontmost.

Usage

| Action | Effect | |---|---| | Press cmd+shift+2 | Area-capture → saved to ~/.claude/screenshots/ + copied to clipboard | | Switch to Claude Code terminal | Queue auto-pastes in order | | /ss in Claude Code | Attach the latest queued screenshot and clear it | | /ss-all | Attach every queued screenshot and clear the queue | | /ss-clear | Drop the queue without attaching anything |

CLI

claude-ss setup                    first-run permission wizard
claude-ss start / stop / restart   manage daemon
claude-ss status                   show state
claude-ss doctor                   re-check permissions, reopen missing panes
claude-ss target set|show|clear    pin / unpin paste target
claude-ss hotkey META+SHIFT+2      change hotkey (modifiers: META CTRL ALT SHIFT)
claude-ss queue                    list pending screenshots
claude-ss clear                    empty queue
claude-ss reset                    reset config to defaults

Config lives at ~/.claude-ss/config.json:

{
  "hotkey": { "modifiers": ["META", "SHIFT"], "key": "2" },
  "autoPasteMode": "on-focus",
  "copyToClipboard": true,
  "saveToFile": true,
  "pasteDelayMs": 150,
  "focusPollMs": 500,
  "interPasteDelayMs": 300
}

Troubleshooting

Hotkey does nothing Input Monitoring permission missing. claude-ss doctor → grant → claude-ss restart.

Auto-paste fires but nothing lands in the terminal Accessibility for the terminal app is likely cached as denied. Toggle OFF → ON in System Settings → Privacy & Security → Accessibility, then completely quit the terminal app and relaunch.

Korean / Japanese / Chinese IME is active claude-ss auto-switches to the ABC (English) input source before pasting and restores your IME afterward. If it fails, make sure the Swift ime-helper built during npm install — run ls bin/ime-helper to confirm. If missing, swiftc -framework Cocoa -framework Carbon -O src/ime-helper.swift -o bin/ime-helper.

Multi-session tmux / iTerm2 — paste goes to the wrong window Use claude-ss target set while focused on the exact Claude Code window you want.

cmux screen jumps or doesn't receive paste cmux (and most Electron terminal-likes) enforce strict key-event isolation. claude-ss only ever pastes when cmux is already frontmost (no forced activate). If paste still fails after cmux is focused, toggle cmux's Accessibility permission OFF → ON and fully quit/relaunch cmux.

Known limitations

• macOS only (v0.1). Linux (grim / scrot) and Windows on the roadmap.
• No true background paste. macOS / terminal emulators do not accept keystroke events while in the background. claude-ss works around this by queuing and pasting only when you explicitly focus the target terminal — no screen jumping, but no instant paste while you're in another app.
• cmux in tmux-CC mode: pin the specific Claude Code session with claude-ss target set.

Roadmap

• v0.2: menubar indicator, richer target matching (iTerm2 window+tab), annotation before save
• v0.3: Linux (grim / scrot + key-injection via wtype / ydotool)
• v0.4: Windows (PowerShell + SnippingTool + SendInput)

License

MIT