rudycanshoot

rudycanshoot

An MCP server + CLI that lets AI assistants take and view screenshots. Works with Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, OpenCode, Continue, Cline, Aider, and GitHub Copilot.

Install

npm install -g rudycanshoot

Or run without installing:

npx -y rudycanshoot serve

Quick Start

1. Auto-configure your AI tools

# All tools at once
rudycanshoot install --all

# Or a specific tool
rudycanshoot install --tool claude-code
rudycanshoot install --tool cursor
rudycanshoot install --tool windsurf
rudycanshoot install --tool codex
rudycanshoot install --tool gemini
rudycanshoot install --tool opencode
rudycanshoot install --tool continue
rudycanshoot install --tool cline

2. Restart your AI tool

The MCP server will now appear in your AI assistant's tool list.

3. Use it

Ask your AI: "Take a screenshot and show me what's on screen."

---

MCP Tools

| Tool | Description | |------|-------------| | take_screenshot | Capture fullscreen, active window, or a region | | read_screenshot | Read a saved image so the AI can view it | | list_screenshots | List recent captures | | record_video | Record a temporary screen video; returns frames the AI can watch | | read_video | Extract frames from a saved video for visual review | | list_videos | List recent recordings | | cleanup_videos | Delete temporary (or all) recordings |

take_screenshot parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | mode | fullscreen\|window\|area | fullscreen | What to capture | | area | string | — | x,y,width,height — required when mode=area | | filename | string | auto | Output filename | | outputDir | string | ~/.rudycanshoot/captures/ | Where to save |

---

CLI

# Take a screenshot
rudycanshoot capture
rudycanshoot capture --mode window
rudycanshoot capture --mode area --area 0,0,1920,1080
rudycanshoot capture --output /tmp/snap.png

# List recent screenshots
rudycanshoot list

# Record a temporary screen video (AI can read frames via MCP)
rudycanshoot record --duration 5 --fps 4
rudycanshoot videos
rudycanshoot cleanup-videos

# Start MCP server (used by AI tools — usually run automatically)
rudycanshoot serve

# Configure AI tools
rudycanshoot install --all

---

Supported AI Tools

| Tool | Config location | What's installed | |------|----------------|-----------------| | Claude Code | ~/.claude/settings.json | MCP server entry + /screenshot command | | Cursor | ~/.cursor/mcp.json | MCP server entry | | Windsurf | ~/.codeium/windsurf/mcp_config.json | MCP server entry | | Codex CLI | ~/AGENTS.md | Tool documentation | | Gemini CLI | ~/.gemini/settings.json | MCP server entry | | OpenCode | ~/.config/opencode/opencode.json | MCP server + agent | | Continue | ~/.continue/config.json | MCP server entry | | Cline | ~/.clinerules/ | Rules file | | Aider | ~/.aider.conf.yml | Comment reference | | GitHub Copilot | ~/.github/copilot-instructions.md | Instructions |

---

Screenshot Backends

Linux

Unlike macOS/Windows, Linux has no single built-in screencapture binary. rudycanshoot uses silent backends only (no permission popups — xdg-desktop-portal is intentionally skipped).

Tried in order when available:

| Tool | Display | Notes | |------|---------|-------| | grim | Wayland | sudo apt install grim | | gnome-screenshot | Wayland | only non-interactive -f | | scrot / maim / import | X11 | optional packages | | xwd + ffmpeg | X11 | X11 built-in dump → PNG (no ImageMagick needed) | | ffmpeg x11grab | X11 | same encoder already used for video | | WSL → PowerShell | — | Windows host desktop when Linux tools are missing |

Video (Linux)

Same rule: silent only (no portal ScreenCast prompts).

| Backend | When | |---------|------| | ffmpeg x11grab | DISPLAY available (X11 / XWayland) | | wf-recorder | Wayland, if installed | | screenshot frames → MP4/GIF | fallback using the silent screenshot chain |

macOS/Windows video uses ffmpeg avfoundation / gdigrab.

macOS

Uses the built-in screencapture command — no extra install needed.

Windows

Uses PowerShell + System.Windows.Forms — no extra install needed.

---

Project Config Files (for contributors)

When you clone this repo, your AI tool will auto-discover:

| File | Tool | |------|------| | CLAUDE.md | Claude Code | | AGENTS.md | Codex CLI, OpenCode | | GEMINI.md | Gemini CLI | | .github/copilot-instructions.md | GitHub Copilot | | .cursor/mcp.json | Cursor | | .mcp.json | Claude Code (project-level) | | .windsurfrules | Windsurf | | .clinerules/ | Cline | | .claude/commands/screenshot.md | Claude Code /screenshot command | | .opencode/agents/screenshot.md | OpenCode agent |

---

License

MIT

---

Image Processing

| Function | Description | |----------|-------------| | annotateImage | Add text label to a screenshot | | diffScreenshots | Highlight/heatmap/side-by-side diff | | compareScreenshots | Pixel-level similarity metrics | | highlightRegions | Color overlays with labels | | redactRegions | Fill or blur sensitive areas | | addWatermark | Corner text watermark | | addBorder | Solid border with optional radius | | cropImage | Crop to a region | | resizeImage | Resize preserving aspect ratio | | stitchImages | Horizontal or vertical concat | | makeGrid | N×M grid composite | | makeGif | Animated GIF from PNG frames | | ocrImage | Extract text via Tesseract |

Pipeline API

import { Pipeline } from "rudycanshoot";

const path = await Pipeline.capture({ mode: "fullscreen" })
  .annotate("CT-6101 Boson capture", { position: "bottom" })
  .redact([{ x: 0, y: 0, w: 1920, h: 30 }], { style: "blur" })
  .watermark("CONFIDENTIAL", { corner: "br" })
  .save("/tmp/final.png");