claude-ss

claude-ss

English · 한국어

Frictionless screenshot workflow for Claude Code.

npm: @jidohyun/claude-ss

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

Via npm (recommended)

npm install -g @jidohyun/claude-ss
claude-ss setup          # walks you through the 3 macOS permissions
claude-ss start          # launch the background daemon

Via git clone (for hacking)

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
claude-ss start

Enable slash commands in Claude Code

Option 1 — install as a plugin via Claude Code:

/plugin marketplace add jidohyun/claude-ss
/plugin install claude-ss@claude-ss

Option 2 — symlink into your plugins directory:

mkdir -p ~/.claude/plugins
ln -s "$(npm root -g)/@jidohyun/claude-ss" ~/.claude/plugins/claude-ss
# or, if installed via git clone: 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