obscura-plugin

Skill-driven plugin for Obscura headless browser — gives AI coding agents direct access to web scraping and browser automation via slash commands.

Two approaches in Obscura:

  • obscura-plugin (this plugin) — skill-driven with read-only commands (obscura_fetch, obscura_scrape, etc.), designed for autonomous agent pipelines

Install

Claude Code (zero-touch)

obscura-plugin ships a .claude-plugin/ manifest. Register the marketplace source once, then install:

claude plugin marketplace add epicsagas/plugins
claude plugin install obscura-plugin

The SessionStart hook downloads obscura and obscura-worker automatically on first load. No manual steps needed.

Codex CLI

codex plugin marketplace add epicsagas/plugins
codex plugin install obscura-plugin

Skills and agents are available immediately — no further steps needed.

Antigravity

agy plugin install https://github.com/epicsagas/obscura-plugin

obscura-plugin install automatically downloads the obscura and obscura-worker binaries from Obscura releases. Linux requires glibc 2.35+ (Ubuntu 22.04+).

macOS / Linux

# pre-built binary, no Rust required
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/obscura-plugin/releases/latest/download/obscura-plugin-installer.sh | sh

Windows

# pre-built binary, no Rust required
irm https://github.com/epicsagas/obscura-plugin/releases/latest/download/obscura-plugin-installer.ps1 | iex

Homebrew (macOS / Linux)

brew install epicsagas/tap/obscura-plugin

Via Rust toolchain

# pre-built binary via Rust toolchain (fast)
cargo binstall obscura-plugin

# build from source (requires Rust toolchain)
cargo install obscura-plugin

obscura-plugin --version to verify. Update with brew upgrade obscura-plugin or re-run the installer script.

Register with your AI tools

After installing the binary, run obscura-plugin install to connect it to your tools:

obscura-plugin install              # interactive — pick which tools
obscura-plugin install cursor       # Cursor
obscura-plugin install opencode     # OpenCode
obscura-plugin install cline        # Cline
obscura-plugin install all          # all at once

obscura-plugin uninstall cursor     # remove from a specific tool
obscura-plugin list                 # show supported tools and status

What gets installed

Tool Skills Method
Claude Code plugin auto-discovers .claude-plugin/ manifest
Codex CLI plugin auto-discovers .codex-plugin/ manifest
Antigravity plugin auto-discovers root plugin.json
Cursor ~/.cursor/rules/ obscura-plugin install
OpenCode ~/.opencode/skills/ obscura-plugin install
Cline ~/.cline/skills/ obscura-plugin install

Skills

Registered skills are available as slash commands inside your agent:

/obscura-fetch <url> [--dump html|text|links|markdown] [--eval <js>] [--selector <css>] [--stealth]
/obscura-scrape <url1> <url2> ... [--eval <js>] [--concurrency <N>] [--format json|text]
/obscura-pipeline <index-url>   # discover links → scrape in one pipeline
/obscura-crawl <seed-url>       # recursive crawl with depth control, pagination, sitemap discovery

Skill parameters

obscura-fetch

Parameter Type Description
url string URL to fetch (required)
dump string html · text · links · markdown (default: html)
eval string JavaScript expression to evaluate
wait_until string load · domcontentloaded · networkidle0 (default: load)
selector string CSS selector to wait for before returning
stealth boolean Enable anti-detection + tracker blocking¹
user_agent string Custom User-Agent string
quiet boolean Suppress banner (default: true)

obscura-scrape

Parameter Type Description
urls string[] URLs to scrape (required)
eval string JavaScript expression applied to each page
concurrency number Parallel workers (default: 10)
format string json · text (default: json)
proxy string HTTP/SOCKS5 proxy URL for all workers

obscura-pipeline

Parameter Type Description
url string Index page URL (required)
selector string CSS selector for link extraction
concurrency number Parallel workers for scraping
stealth boolean Anti-detection mode¹

¹ Stealth mode requires Obscura built with --features stealth. The default release binary includes stealth.

obscura-crawl

Parameter Type Description
url string Seed URL to start crawling from (required)
max_depth number Maximum crawl depth (default: 3)
same_domain boolean Only follow links on the same domain (default: true)
url_filter string Regex/glob pattern to filter URLs by path

The obscura-browser agent

A self-directed web data collection specialist. Invoke it for tasks like:

"Collect all product titles and prices from these 30 URLs" "Fetch the docs at example.com/api and summarize the endpoints" "Scrape the HN front page and return structured JSON" "Crawl example.com/blog up to depth 2 and extract all post titles"

The agent knows Obscura's limits — it stops and escalates to Playwright when login or interaction is required. Supports agentic crawling with depth control, pagination detection, sitemap discovery, and adaptive extraction.

Project structure

obscura-plugin/
  skills/                        # shared skills
    obscura-fetch/SKILL.md
    obscura-scrape/SKILL.md
    obscura-pipeline/SKILL.md
    obscura-crawl/SKILL.md
  agents/                        # shared agent (markdown)
    obscura-browser.md
  scripts/
    install.js                   # binary bootstrap (SessionStart hook)

  .claude-plugin/                # Claude Code plugin
    plugin.json, hooks.json, marketplace.json
  .codex-plugin/                 # Codex CLI plugin
    plugin.json, hooks.json
    agents/obscura-browser.toml  # Codex-specific TOML agent
  plugin.json                    # Antigravity (agy) plugin marker
  hooks.json                     # Antigravity hooks

  src/                           # Rust installer (cursor, opencode, cline)
  tests/
  Cargo.toml

Build from source

cargo build --release
./target/release/obscura-plugin --help

License

Apache 2.0