# 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");
```