{"id":50691970,"url":"https://github.com/marmutapp/superbased-claude-code-plugin","last_synced_at":"2026-06-09T03:44:58.733Z","repository":{"id":353954941,"uuid":"1208844994","full_name":"marmutapp/superbased-claude-code-plugin","owner":"marmutapp","description":"SuperBased plugin for Claude Code — screenshot capture, AI vision, OCR, screen recording, visual regression testing, token compression, voice dictation, and proactive monitoring via 28 MCP tools","archived":false,"fork":false,"pushed_at":"2026-04-26T11:38:51.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T13:22:44.613Z","etag":null,"topics":["ai-vision","claude-code","claude-code-plugin","dictation","mcp","ocr","screen-recording","screenshot","token-compression","visual-testing"],"latest_commit_sha":null,"homepage":"https://superbased.app","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marmutapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T20:18:45.000Z","updated_at":"2026-04-26T11:38:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marmutapp/superbased-claude-code-plugin","commit_stats":null,"previous_names":["marmutapp/superbased-claude-code-plugin"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/marmutapp/superbased-claude-code-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmutapp%2Fsuperbased-claude-code-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmutapp%2Fsuperbased-claude-code-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmutapp%2Fsuperbased-claude-code-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmutapp%2Fsuperbased-claude-code-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marmutapp","download_url":"https://codeload.github.com/marmutapp/superbased-claude-code-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmutapp%2Fsuperbased-claude-code-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34090751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-vision","claude-code","claude-code-plugin","dictation","mcp","ocr","screen-recording","screenshot","token-compression","visual-testing"],"created_at":"2026-06-09T03:44:58.029Z","updated_at":"2026-06-09T03:44:58.725Z","avatar_url":"https://github.com/marmutapp.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# SuperBased — Eyes AND Hands for Claude Code\n\nScreenshot capture, AI vision, OCR, screen recording, visual regression testing, token compression, voice dictation, proactive screen monitoring, **and full GUI automation with humanization v2** — all via 72 MCP tools, directly inside Claude Code.\n\n## Install\n\n### Option 1: From Marketplace\n\n```\n/plugin marketplace add marmutapp/superbased-claude-code-plugin\n/plugin install superbased@superbased-tools\n```\n\n### Option 2: Local Plugin\n\n```\nclaude --plugin-dir /path/to/superbased/plugin\n```\n\n### Option 3: MCP Server Only\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"superbased\": {\n    \"command\": \"superbased\",\n    \"args\": [\"mcp\"]\n  }\n}\n```\n\n## Prerequisites\n\n- **SuperBased desktop app** running (Windows or macOS), OR\n- **SuperBased CLI** installed globally: `npm install -g superbased`\n- Node.js 20+\n\n## Recommended: auto-approve SuperBased tools\n\nClaude Code prompts for approval on every MCP tool call by default. For GUI-automation flows (click / type / scroll / drag / sequence / ui_dump) each prompt also steals focus back to the Claude Code window — so 20 tool calls = 20 focus breaks. Add this to `.claude/settings.json` (project) or `~/.claude/settings.json` (global) to auto-approve all SuperBased tools:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"mcp__superbased\"]\n  }\n}\n```\n\nSafe: the SuperBased server still enforces its own gates (`guiAutomation.enabled` master toggle + per-action toggles + `confirm: true` + protected-apps blocklist + NDJSON audit log). Auto-approving in Claude Code only bypasses the redundant host-side prompt, not the underlying safety rail.\n\n## Slash Commands (26)\n\n| Command | Description |\n|---------|-------------|\n| `/superbased:capture` | Take a screenshot (fullscreen, window, or region) |\n| `/superbased:window` | List open windows or capture a specific window |\n| `/superbased:extract` | Capture + OCR to extract text from screen |\n| `/superbased:explain` | Capture + AI analysis of what's on screen |\n| `/superbased:ocr` | Extract text from screenshot or image file (local Tesseract) |\n| `/superbased:clipboard` | Read or write system clipboard (text or image) |\n| `/superbased:annotate` | Add rectangles, arrows, text labels, blur to captures |\n| `/superbased:redact` | Auto-redact secrets and PII from screenshots |\n| `/superbased:record` | Start, stop, or manage screen recording sessions |\n| `/superbased:monitor` | Start proactive AI screen monitoring |\n| `/superbased:sessions` | List recording sessions and view frames |\n| `/superbased:diff` | Compare two recording sessions for visual regressions |\n| `/superbased:baseline` | Manage visual regression testing baselines |\n| `/superbased:export` | Export sessions as zip, markdown, PDF, HTML, or GIF |\n| `/superbased:gallery` | Browse, search, and manage capture gallery |\n| `/superbased:compress` | Compress text into token-efficient images |\n| `/superbased:dictate` | Record from microphone and transcribe |\n| `/superbased:transcribe` | Transcribe audio file to text (raw Whisper) |\n| `/superbased:settings` | View or update app settings |\n| `/superbased:presets` | Manage AI instruction presets |\n| `/superbased:status` | Health, auth, and AI usage check |\n| `/superbased:auth` | Authentication management |\n| `/superbased:click` | Click an on-screen element by label or coordinates |\n| `/superbased:form` | Fill a form by label/value pairs (`superbased_form_fill`) |\n| `/superbased:record-gui` | Record a multi-step GUI workflow for replay |\n| `/superbased:captcha` | Open the CAPTCHA-solving guidance (rotation puzzles, drag puzzles, image grids) |\n\n## Skills (11)\n\nSkills are invoked automatically by Claude when relevant to the task.\n\n| Skill | When Claude Uses It |\n|-------|-------------------|\n| **screenshot** | Claude needs to see the screen to answer a question or verify a UI change |\n| **visual-qa** | Visual regression testing: record baseline, make changes, record again, diff |\n| **monitor** | Proactive screen watching during deploys, tests, or builds |\n| **compress** | Large text content (\u003e500 tokens) that would be cheaper as an image |\n| **redact** | Screenshots that may contain API keys, tokens, or PII before sharing |\n| **dictation** | User wants voice input, audio transcription, or speech-to-text |\n| **annotate** | Highlighting areas, marking regressions, creating annotated screenshots |\n| **walkthrough** | Multi-frame product walkthrough: capture, narrate, export |\n| **gui-automation** | \"Click that\", \"type into this\", \"fill the form\" — drives the desktop with click/type/hotkey/scroll/drag/form-fill/sequence |\n| **captcha-solving** | reCAPTCHA / Cloudflare Turnstile / drag puzzles / rotation puzzles / image grids |\n| **humanization** | Sites with bot detection — picks the right humanization profile (off/light/human/paranoid) |\n\n## Agents (3)\n\nDedicated agents for complex multi-step workflows.\n\n| Agent | Description |\n|-------|-------------|\n| **visual-qa** | Record baselines, capture after changes, diff, annotate regressions, export reports |\n| **monitor** | Watch screen for errors during deploys/tests, flag issues proactively, summarize findings |\n| **gui-automation** | Orchestrate multi-step GUI workflows with `superbased_sequence` + the click/type/drag/scroll/form-fill primitives, with the safety checklist baked in |\n\n## Hooks\n\n**Post-test auto-capture:** After any test command (`npm test`, `jest`, `vitest`, `pytest`, `cargo test`, `go test`), SuperBased automatically captures a screenshot at quarter resolution. This builds a visual history of test runs without manual intervention.\n\n## Humanization v2\n\nGUI automation actions (`click`, `type`, `drag`, `hover`) ship with a humanization layer to reduce the bot-detection signal:\n\n- **Cursor walks** use a sin-shaped velocity envelope (Bezier-style ease-in/ease-out) — not constant-velocity\n- **Click targets** get a Gaussian jitter so two clicks on the same element land on slightly different pixels\n- **Pre-click settle dwell** is gamma-distributed (rare long pauses, common short ones) — humans don't click the millisecond their cursor arrives\n- **Click hold** varies between 50–110 ms, **key hold** between 45–95 ms, with per-process cross-session salt mixed into the seed\n- **Typo simulation** wired via `typoProb` — with the QWERTY same-row neighbor distribution that real fat-finger errors follow\n- **Pre-click tremor** on the target element + occasional 2–4× micro-pauses that mimic distraction\n- **Inter-action catch-up pause** between sequence steps so back-to-back clicks don't have suspiciously identical inter-arrival times\n- **Opt-in idle cursor drift** via the `humanInputIdleDrift` setting\n\nFour profiles selectable per call: `humanize: 'off' | 'light' | 'human' | 'paranoid'`. Default is `light`. Bump to `human` or `paranoid` for sites with active bot detection — see the **humanization** skill.\n\n## CAPTCHA solving\n\nPlugin ships proactive guidance for the four CAPTCHA classes that come up in real automation work:\n\n- **reCAPTCHA / Cloudflare Turnstile** — checkbox + image-grid challenges. Vision identifies the matching tiles, then a single batched click sequence selects them.\n- **Drag puzzles** — slider-to-fit verification (e.g. \"drag the puzzle piece to the gap\"). Use `superbased_drag` with `humanize: 'light'` so the drop velocity reads as human; never `'off'`.\n- **Rotation puzzles** — calibrate-then-execute pattern (capture, identify the angular delta, then drag in one motion).\n- **Image grids** — vision to identify, batched click to select.\n\nPlus an honest list of \"what humanization can't defeat\" (server-side device fingerprinting, audio CAPTCHAs, hCaptcha enterprise mode). See the **captcha-solving** skill.\n\n## MCP Tools (72)\n\nThe plugin exposes all 72 SuperBased MCP tools. Click each section to expand.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCapture \u0026 View (5)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_screenshot` (preferred wrapper), `superbased_capture_image` (advanced), `superbased_capture`, `superbased_gallery_image`, `superbased_window_list`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAI \u0026 OCR (8)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_ai`, `superbased_ai_usage`, `superbased_ocr`, `superbased_transcribe`, `superbased_compress_text`, `superbased_project`, `superbased_workspace_sync`, `superbased_stt_status`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGallery (2)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_gallery`, `superbased_gallery_update`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePrivacy \u0026 Annotations (2)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_redact`, `superbased_annotate`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDictation \u0026 Voice (2)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_dictate`, `superbased_dictation_history`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRecording \u0026 Visual QA (7)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_recording`, `superbased_sessions`, `superbased_describe_frames`, `superbased_narrate`, `superbased_diff`, `superbased_baseline`, `superbased_export`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSettings, Auth \u0026 System (6)\u003c/b\u003e\u003c/summary\u003e\n\n`superbased_settings`, `superbased_presets`, `superbased_auth`, `superbased_license`, `superbased_health`, `superbased_clipboard`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGUI Automation (40)\u003c/b\u003e\u003c/summary\u003e\n\n**Read the screen:** `superbased_ui_dump` (preferred for \"read the page\"), `superbased_scroll_capture` (preferred for \"walk the whole page\"), `superbased_scroll_to` (preferred for \"find X on a long page\"), `superbased_accessibility_tree`, `superbased_locate`\n\n**Drive the desktop:** `superbased_sequence` (preferred for \u003e1 step), `superbased_click`, `superbased_type`, `superbased_hotkey`, `superbased_scroll`, `superbased_drag`, `superbased_drag_file` (scaffold), `superbased_hover`, `superbased_context_menu_select`, `superbased_form_fill`, `superbased_dialog_handle`, `superbased_open_url`, `superbased_find_in_page`, `superbased_tab_management`, `superbased_tray_click`, `superbased_virtual_desktop`\n\n**Window \u0026 display:** `superbased_window_state`, `superbased_resize_window`, `superbased_focus_window`, `superbased_window_bounds`, `superbased_find_title_bar_drag_region`, `superbased_display_list`, `superbased_launch_app`\n\n**Vision targeting:** `superbased_find_image`, `superbased_capture_template`, `superbased_pixel_color`\n\n**Accessibility \u0026 invoke:** `superbased_ax_invoke`\n\n**Timing:** `superbased_wait`, `superbased_wait_for`, `superbased_mouse_position`\n\n**Safety / dev tools:** `superbased_dry_run`, `superbased_replay`, `superbased_doctor_gui_automation`, `superbased_undo_last`, `superbased_tools`\n\n\u003c/details\u003e\n\n## Token Savings\n\nSuperBased optimizes token usage with resolution control:\n\n| Resolution | 1080p Tokens | Savings vs Full |\n|------------|-------------|-----------------|\n| `full` | ~2,765 | baseline |\n| `high` | ~1,382 | 2x |\n| `half` | ~691 | 4x |\n| `quarter` | ~173 | 16x |\n| `thumbnail` | ~43 | 64x |\n\nThe Token Compression Engine converts large text blocks into optimized images, saving tokens when `image_tokens \u003c text_tokens` (typically for content \u003e500 tokens).\n\n## Examples\n\n### See what's on screen\n```\n/superbased:capture\n```\n\n### Capture a specific window\n```\n/superbased:window Chrome\n```\n\n### Click a button by label\n```\n/superbased:click Submit\n```\n\n### Fill a login form\n```\n/superbased:form email=alice@example.com password=hunter2\n```\n\n### Solve a rotation CAPTCHA\n```\n/superbased:captcha\n(then describe the puzzle to Claude — it'll calibrate the angle, then drag in one motion)\n```\n\n### Monitor a deploy for errors\n```\n/superbased:monitor Flag any errors, failed health checks, or 500 status codes\n```\n\n### Visual regression test\n```\n/superbased:record login-flow-baseline\n(navigate the login UI)\n/superbased:record stop\n/superbased:baseline set login-flow \u003csession-id\u003e\n(make code changes)\n/superbased:record login-flow-after\n(navigate the same flow)\n/superbased:record stop\n/superbased:diff \u003cbaseline-id\u003e \u003cafter-id\u003e\n```\n\n### Redact and share a screenshot\n```\n/superbased:capture\n/superbased:redact \u003ccapture-id\u003e\n```\n\n## Links\n\n- [SuperBased](https://superbased.app) — Desktop app download\n- [npm package](https://www.npmjs.com/package/superbased) — Headless CLI\n- [MCP Integration Guide](https://github.com/marmutapp/superbased-claude-code-plugin) — Plugin repo \u0026 setup guide\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmutapp%2Fsuperbased-claude-code-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarmutapp%2Fsuperbased-claude-code-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmutapp%2Fsuperbased-claude-code-plugin/lists"}