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 ```bash npm install -g rudycanshoot ``` Or run without installing: ```bash npx -y rudycanshoot serve ``` ## Quick Start ### 1. Auto-configure your AI tools ```bash # 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 | | `record_terminal` | Record a TERMINAL SESSION (a running command) as a GIF — no desktop, works headless | | `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 ```bash # 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 ```js 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"); ```