{
  "markdown": "# snap-browser\n\nA [Claude Plugin](https://claude.com/plugins) that captures focused screenshots of specific UI components from a running browser — with a red rectangle marking the exact element — and uses them for visual analysis and debugging.\n\n```\n/snap-browser:snap the submit button is in the wrong place\n/snap-browser:snap the certificate card under education looks broken\n/snap-browser:snap show me the skills section\n```\n\n---\n\n## How it works\n\n1. You describe a UI element in plain English\n2. Claude finds your running dev server (or reads the URL from your open browser)\n3. A headless browser navigates to the page invisibly\n4. The element is located using ARIA roles, labels, and text — then **smart container expansion** walks up the DOM to find the full component (not just a text label inside it)\n5. Two screenshots are produced:\n   - **Tight crop** — just the component, for close-up analysis\n   - **Context shot** — the full viewport with a red rectangle showing where it sits\n6. Claude analyzes what it sees and fixes the issue\n\n---\n\n## Requirements\n\n- **Node.js 18+** — check with `node --version`\n- **Chrome, Chromium, Brave, or Edge** installed on your machine (used for headless rendering — no download required)\n- **Claude Code CLI** — [install guide](https://docs.claude.com/en/docs/claude-code)\n\n---\n\n## Installation\n\nThis plugin is distributed as a [Claude Code marketplace](https://docs.claude.com/en/docs/claude-code/plugins). You install it using the official `/plugin` command — never by editing config files by hand.\n\nClaude Code supports three install scopes:\n\n| Scope | Where it writes | When to use |\n|---|---|---|\n| **user** *(default)* | `~/.claude/settings.json` | You, on your machine, across every project |\n| **project** | `<project>/.claude/settings.json` | Shared with your team via git commit |\n| **local** | `<project>/.claude/settings.local.json` | Just for you in one project, gitignored |\n\n### Step 1 — Add the GitHub repo as a marketplace (one-time, per machine)\n\nClaude Code can treat any public GitHub repo that contains a `.claude-plugin/marketplace.json` as a plugin marketplace. This repo does — so you can point Claude Code straight at GitHub, no cloning required.\n\nInside Claude Code, use **any** of these three forms:\n\n```\n# A. GitHub owner/repo shorthand (recommended)\n/plugin marketplace add sirayhancse/snap-browser\n\n# B. Full HTTPS URL to the repo\n/plugin marketplace add https://github.com/sirayhancse/snap-browser\n\n# C. Full git URL (works for private repos you have SSH access to)\n/plugin marketplace add git@github.com:sirayhancse/snap-browser.git\n```\n\nCLI equivalent (any of the above also works as a flag to `claude plugin marketplace add`):\n\n```bash\nclaude plugin marketplace add sirayhancse/snap-browser\n# or\nclaude plugin marketplace add https://github.com/sirayhancse/snap-browser\n```\n\nClaude Code fetches and caches the repo locally, reads `.claude-plugin/marketplace.json`, and registers `snap-browser` as an available marketplace. It does **not** enable the plugin yet — that happens in Step 2.\n\n> **Pinning a version.** To lock to a specific release or commit, append `@<ref>`:\n> `/plugin marketplace add sirayhancse/snap-browser@v1.0.0`\n> (works with tags, branches, or full commit SHAs)\n\n> **Updating later.** Run `/plugin marketplace update snap-browser` to pull the latest version.\n\n### Step 2 — Install the plugin\n\n#### Option A: User-level (recommended) — available in every project\n\n```\n/plugin install snap-browser@snap-browser\n```\n\nOr CLI:\n\n```bash\nclaude plugin install snap-browser@snap-browser\n```\n\n#### Option B: Project-level — shared with your team\n\nFrom inside the project root:\n\n```\n/plugin install snap-browser@snap-browser --scope project\n```\n\nOr CLI:\n\n```bash\nclaude plugin install snap-browser@snap-browser --scope project\n```\n\nThis writes to `.claude/settings.json` in your repo. Commit that file so teammates get the plugin when they pull.\n\n#### Option C: Local-only — just you, one project\n\n```\n/plugin install snap-browser@snap-browser --scope local\n```\n\nWrites to `.claude/settings.local.json` (already gitignored by Claude Code).\n\n> **Syntax note:** `snap-browser@snap-browser` is `<plugin-name>@<marketplace-name>`. Both happen to be `snap-browser` because this repo hosts a single-plugin marketplace of the same name.\n\n### Step 3 — Install the script's dependencies\n\nThe plugin ships a small Node.js capture script. Run this once after install:\n\n```bash\n# Claude Code will tell you the exact plugin path when you run /plugin list,\n# or you can ask Claude to run this for you:\ncd \"$(claude plugin path snap-browser)/skills/snap\" && npm install\n```\n\nOr simply invoke the skill once — Claude will prompt you to run `npm install` when the script first fails.\n\n### Step 4 — Verify\n\nIn Claude Code:\n\n```\n/plugin list\n```\n\nYou should see `snap-browser` listed as enabled. Try it:\n\n```\n/snap-browser:snap show me the header\n```\n\n### Browsing / interactive install\n\nYou can also run `/plugin` (no arguments) to open the interactive plugin browser. Press **Tab** to cycle between the **Discover**, **Installed**, **Marketplaces**, and **Errors** tabs.\n\n---\n\n## Manual install from GitHub (offline / hack-on-it)\n\nPrefer this if you want to clone the repo yourself — to read the source, modify it, or use it without Claude Code fetching from GitHub on its own.\n\n### Step 1 — Clone the repo\n\nPick any location on disk. A few common choices:\n\n```bash\n# Option A: user-level location (available across every project)\ngit clone https://github.com/sirayhancse/snap-browser.git ~/.claude/plugins/snap-browser\n\n# Option B: inside a specific project (so the plugin travels with the repo)\ncd /path/to/your-project\ngit clone https://github.com/sirayhancse/snap-browser.git .claude/plugins/snap-browser\n```\n\nThe path doesn't matter — Claude Code only needs an absolute path in the next step.\n\n### Step 2 — Install the script's dependencies\n\n```bash\ncd <clone-path>/skills/snap && npm install\n```\n\n### Step 3 — Register the clone as a local marketplace\n\n`/plugin marketplace add` accepts a **local directory** (not just a GitHub URL) as long as the directory contains `.claude-plugin/marketplace.json` — which this repo does.\n\nInside Claude Code:\n\n```\n/plugin marketplace add <absolute-path-to-clone>\n```\n\nExample:\n\n```\n/plugin marketplace add /Users/you/.claude/plugins/snap-browser\n```\n\nOr CLI:\n\n```bash\nclaude plugin marketplace add ~/.claude/plugins/snap-browser\n```\n\n### Step 4 — Install the plugin\n\nSame as the marketplace flow — pick a scope:\n\n```\n/plugin install snap-browser@snap-browser                  # user (default)\n/plugin install snap-browser@snap-browser --scope project  # shared with team\n/plugin install snap-browser@snap-browser --scope local    # just you, one project\n```\n\n### Step 5 — Verify\n\n```\n/plugin list\n```\n\nYou should see `snap-browser` listed. Try it:\n\n```\n/snap-browser:snap show me the header\n```\n\n### Updating a manually-cloned install\n\n```bash\ncd <clone-path>\ngit pull\ncd skills/snap && npm install   # only if dependencies changed\n```\n\nThen `/plugin reload` inside Claude Code. No need to re-register the marketplace.\n\n---\n\n## Usage\n\n### Slash command (inside Claude Code)\n\n```\n/snap-browser:snap <describe the element and/or the issue>\n```\n\nThe format is `/<plugin-name>:<skill-name>` — every plugin-provided skill is namespaced.\n\nExamples:\n\n```\n/snap-browser:snap the submit button is in the wrong place\n/snap-browser:snap the certificate card under education looks broken\n/snap-browser:snap show me the skills section\n/snap-browser:snap the name input field has bad styling\n/snap-browser:snap take a full screenshot of the dashboard\n/snap-browser:snap the navigation bar is overlapping the content\n```\n\nClaude will:\n- Find your running dev server or read the open browser URL automatically\n- Infer the page path from context (by checking your router config)\n- Capture the component with smart container expansion\n- Show you both the tight crop and the red-rectangle context shot\n- Diagnose the visual issue and suggest or apply a fix\n\n> **Tip:** Because the skill's `description` is rich, Claude will often auto-invoke it when you describe a UI problem in plain English — you don't always need to type the slash prefix.\n\n### Direct script usage (outside Claude Code)\n\nYou can also call the script directly from any terminal:\n\n```bash\n# Auto-detect URL from open browser or running dev server\nnode /path/to/snap-browser/skills/snap/scripts/snap.js \"submit button\"\n\n# Specific element on a specific page\nnode /path/to/snap-browser/skills/snap/scripts/snap.js \"submit button\" \"http://localhost:3000/checkout\"\n\n# Full page with the element highlighted (element may be below the fold)\nnode /path/to/snap-browser/skills/snap/scripts/snap.js --full-page \"submit button\" \"http://localhost:3000/checkout\"\n\n# Full page, no specific element\nnode /path/to/snap-browser/skills/snap/scripts/snap.js --full-page \"http://localhost:3000/dashboard\"\n```\n\n**Output JSON:**\n\n```jsonc\n// Element found — two images produced\n{\n  \"success\": true,\n  \"path\": \"/tmp/snap-crop-123.png\",         // tight component crop\n  \"contextPath\": \"/tmp/snap-context-123.png\", // viewport + red rectangle\n  \"mode\": \"element\",\n  \"expanded\": true,    // true = walked up from text node to parent component\n  \"strategy\": \"role(button)+name(\\\"submit\\\")\",\n  \"pageUrl\": \"http://localhost:3000/checkout\",\n  \"urlSource\": \"Google Chrome\",\n  \"boundingBox\": { \"x\": 120, \"y\": 340, \"width\": 200, \"height\": 44 }\n}\n\n// Element not found — viewport captured instead\n{\n  \"success\": true,\n  \"path\": \"/tmp/snap-viewport-123.png\",\n  \"mode\": \"viewport\",\n  \"message\": \"\\\"submit button\\\" not found via locators. ...\"\n}\n```\n\n---\n\n## Platform support\n\n| Feature | macOS | Linux | Windows |\n|---------|:-----:|:-----:|:-------:|\n| Headless capture | ✅ | ✅ | ✅ |\n| Auto-detect browser URL | ✅ Chrome, Brave, Edge, Arc, Safari | ❌ | ✅ Chrome, Edge, Firefox |\n| Auto-detect dev server | ✅ | ✅ | ✅ |\n| Smart container expansion | ✅ | ✅ | ✅ |\n| Red rectangle overlay | ✅ | ✅ | ✅ |\n\n**Linux note:** Browser URL auto-detection is unavailable. Always pass the URL explicitly, or rely on dev server detection.\n\n### Supported browsers for headless rendering\n\nThe script uses your system-installed Chrome/Chromium — no separate download. Supports: Google Chrome, Chromium, Brave, Microsoft Edge.\n\nIf none are installed, run:\n\n```bash\ncd \"$(claude plugin path snap-browser)/skills/snap\" && npx playwright install chromium\n```\n\n---\n\n## Project structure\n\n```\nsnap-browser/\n├── .claude-plugin/\n│   ├── plugin.json          ← Plugin manifest\n│   └── marketplace.json     ← Marketplace manifest (lets this repo be added via /plugin marketplace add)\n├── skills/\n│   └── snap/\n│       ├── SKILL.md          ← Skill definition & Claude workflow instructions\n│       ├── package.json      ← Dependencies (playwright-core only)\n│       └── scripts/\n│           └── snap.js       ← Headless screenshot script (Node.js)\n├── .gitignore\n├── LICENSE\n└── README.md\n```\n\n---\n\n## Troubleshooting\n\n**`/snap-browser:snap` is not recognized**\nRun `/plugin list` to confirm the plugin is installed and enabled. If not, re-run Step 2 of the installation. If it is listed but not firing, run `/plugin reload` (or restart Claude Code).\n\n**\"No page URL found\"**\nOpen your app in Chrome/Brave/Edge/Arc/Safari, or start your dev server, or pass the URL directly.\n\n**\"Could not launch headless browser\"**\nInstall Google Chrome or Chromium, or run `npx playwright install chromium` inside `skills/snap/`.\n\n**Element not found (mode: viewport)**\nThe element may be hidden, inside an accordion/tab, or below the fold. Re-run with `--full-page`, or make the description match the visible label text more exactly.\n\n**Wrong element captured**\nAdd more context: `\"submit button in the checkout form\"` instead of `\"submit button\"`.\n\n**Auth-gated pages**\nThe headless browser has no cookies. Pass the login page URL, or test on a page that doesn't need auth.\n\n**Linux: `env: 'which': No such file or directory`**\n\n```bash\nsudo apt install debianutils   # Debian/Ubuntu\nsudo dnf install which          # Fedora/RHEL\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 12165,
  "sha": "23a75dbec73c6e9a424003fe696c100d706a895110947bcf26bd1ed0c434f40c",
  "repo_slug": "sirayhancse/snap-browser",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sirayhancse_snap_browser_snap_browser_5a13e324/readme"
}