| name | peek |
| description | Use when you need to see what is on the user's screen — e.g. to verify a UI state, inspect a visual result, or confirm on-screen output — and cannot automate the action yourself. Do NOT use for tmux windows, panes, or panels — use tmux-monitor instead. |
Screenshot path
Format: /tmp/peek/<topic>/<seq>_<description>.png
- topic — short slug for the current task (e.g.
e2e, login-flow)
- seq — zero-padded 3-digit counter, auto-incremented within the topic directory
- description — snake_case summary of what is being captured
peek_topic="e2e"
peek_dir="/tmp/peek/${peek_topic}"
mkdir --parents "${peek_dir}"
peek_seq=$(printf "%03d" $(( $(ls "${peek_dir}"/*.png 2>/dev/null | wc --lines) + 1 )))
peek_path="${peek_dir}/${peek_seq}_<description>.png"
Workflow
1. Prepare
Announce the full path(s) to the user before taking any screenshot. Tell the user:
- What action to perform or what to have on screen
- The exact path(s) where screenshots will be saved
- To return to the terminal and confirm when ready
Wait for confirmation before proceeding — unless the user mentions "other screen" or "second monitor".
2. Detect monitors
After the user confirms (or mentions multiple monitors), run:
xrandr --query | grep ' connected'
Each geometry is WxH+X+Y. Convert to scrot's -a X,Y,W,H format when targeting a specific monitor.
3. Capture
Single monitor:
scrot "${peek_path}"
Multiple monitors — capture one screenshot per monitor:
scrot -a 0,0,1920,1080 "${peek_dir}/${peek_seq}_<description>_screen1.png"
scrot -a 1920,0,2560,1440 "${peek_dir}/${peek_seq}_<description>_screen2.png"
Use --delay 3 only when the user needs time to switch focus first.
--geometry is not supported on all scrot versions; always use -a X,Y,W,H.
4. Open and read
Open every screenshot in VS Code, then use the Read tool to inspect each image visually.
code "${peek_path}"
If multiple monitors were captured, tell the user which screens were found and guess which one they're likely looking at based on content.
5. Continue
Describe what you see and proceed with the task. For subsequent captures, skip monitor detection — reuse the same monitor and increment the sequence counter.
Installing scrot
sudo apt install --yes scrot
