Screenshot 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 OpenCode.
The plugin ships as an npm package. Install it globally so OpenCode can resolve it from your opencode.json:
npm install -g superbased-opencode-plugin superbasedThen add both the plugin and the MCP server to your opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["superbased-opencode-plugin"],
"mcp": {
"superbased": {
"type": "local",
"command": ["superbased", "mcp"],
"enabled": true
}
}
}A reference opencode.json ships in this package at the root if you want to copy from it.
- OpenCode ≥ the version that supports the TypeScript plugin SDK (
@opencode-ai/plugin) - SuperBased CLI installed globally on PATH:
npm install -g superbased - (Optional) SuperBased desktop app running on Windows or macOS — auto-detected via the PID file at
~/.superbased/. When the desktop app is running,superbased mcpacts as a stdio↔HTTP bridge so the desktop and OpenCode share state. - Node.js 20+
OpenCode plugins are TypeScript modules that hook into the OpenCode lifecycle. The 72 SuperBased tools live in the MCP server (superbased mcp), which OpenCode reaches via the mcp.superbased config above. This npm package is the lifecycle wrapper around that MCP server, adding three ergonomic value-adds:
- Pre-flight safety check — when a destructive SuperBased GUI action (
_click,_type,_drag,_form_fill,_sequence, etc.) is called withoutconfirm: true, the plugin warns proactively. The MCP server enforces this rejection anyway, but the client-side warning gives a faster and clearer UX. - Post-flight telemetry — expensive SuperBased calls (
_recording,_narrate,_scroll_capture,_describe_frames,_compress_text) get their durations logged when they exceed 5 seconds, so you notice the cost. - Audit-log surface — when permission is asked for a SuperBased tool the first time in a session, the plugin surfaces where the NDJSON audit log lives so you know where actions are recorded.
- Init probe — at plugin load time, verifies the
superbasedCLI is on PATH and prints the version. If not installed, surfaces an actionable error before the first MCP call fails opaquely.
You can use SuperBased with OpenCode without this plugin (just configure the MCP server). The plugin adds polish, not capability.
Skills are reference-only on OpenCode — the package ships them so you can read them, paste relevant ones into your context, or fork them into your own opencode prompt. They don't auto-load the way Claude Code skills do.
| Skill | Topic |
|---|---|
| screenshot | When to capture the screen and at what resolution |
| visual-qa | Record baseline → make changes → record again → diff → annotate workflow |
| monitor | Proactive screen watching during deploys, tests, or builds |
| compress | Convert large text to token-efficient images |
| redact | Auto-redact secrets / PII before sharing screenshots |
| dictation | Voice input, audio transcription, speech-to-text |
| annotate | Highlighting areas, marking regressions |
| walkthrough | Multi-frame product walkthrough (capture, narrate, export) |
| gui-automation | Reliability pyramid + sequence patterns + safety rails for the click/type/drag surface |
| captcha-solving | Image grid / drag puzzle / rotation puzzle / checkbox CAPTCHA patterns |
| humanization | Picking the right humanize profile per call |
Same situation as skills — reference markdown, not auto-loaded. Useful for prompting OpenCode like "use the SuperBased :form command pattern to fill this out" — paste the relevant commands/<name>.md into context.
agents/visual-qa/AGENT.md, agents/monitor/AGENT.md, agents/gui-automation/AGENT.md — same reference pattern. Useful when forking your own OpenCode subagent off the SuperBased orchestration patterns.
GUI automation actions (click, type, drag, hover) ship with a humanization layer to reduce the bot-detection signal: sin-shaped velocity envelope on cursor walks, gaussian click-target jitter, gamma-distributed pre-click settle dwell, 50–110 ms click hold variation, 45–95 ms key hold, wired typo simulation with QWERTY same-row neighbors, pre-click tremor on the target element, occasional 2–4× micro-pauses, per-process cross-session salt mixed into seeds, inter-action catch-up pause, and opt-in idle cursor drift.
Four profiles selectable per call: humanize: 'off' | 'light' | 'human' | 'paranoid'. Default light. Bump to human or paranoid for sites with active bot detection — see the humanization skill.
Plugin ships proactive guidance for the four CAPTCHA classes: image grids (vision identifies, batched click sequence), drag puzzles (one-motion drag with humanize: 'light'), rotation puzzles (calibrate-then-execute), and checkbox-only Turnstile. Plus the honest "what humanization can't defeat" list (server-side fingerprinting, audio CAPTCHAs, hCaptcha enterprise mode). See the captcha-solving skill.
The 72 tools come from the SuperBased MCP server, not this plugin. See the source-of-truth Claude Code plugin README for the full categorized list with collapsibles.
Categories: Capture & View (5), AI & OCR (8), Gallery (2), Privacy & Annotations (2), Dictation & Voice (2), Recording & Visual QA (7), Settings/Auth/System (6), and GUI Automation (40).
git clone https://github.com/marmutapp/superbased-opencode-plugin
cd superbased-opencode-plugin
npm install
npm run build # tsc → dist/Plugin entry: src/index.ts (default export is the OpenCode Plugin async function).
The runtime probe in src/mcp-bridge.ts spawns superbased --version to verify the CLI is reachable; fails open (logs a warning) so the plugin never blocks OpenCode startup.
- SuperBased — Desktop app + npm CLI
- npm: superbased — The CLI providing the MCP server
- npm: superbased-opencode-plugin — This package
- OpenCode docs — Plugin SDK reference
- Source-of-truth Claude Code plugin — Where shared content (skills/commands/agents) is mastered