plasmate: Instructions file for Claude Code

Plasmate

The browser engine for AI agents. HTML in, Semantic Object Model out.

Quick Start

# Build
cargo build --release

# Run
./target/release/plasmate fetch https://example.com

# MCP mode (for Claude Code, Cursor, etc.)
./target/release/plasmate mcp

Architecture

• src/main.rs - CLI entry point (Clap)
• src/network/ - HTTP fetch with H1/H2 fallback, custom headers
• src/som/ - Semantic Object Model compiler (HTML to structured JSON)
• src/cdp/ - Chrome DevTools Protocol server
• src/awp/ - Agent Web Protocol handler
• src/bench/ - Benchmarking runner
• src/js/ - V8 JavaScript execution engine
• website/ - plasmate.app homepage
• integrations/ - Framework adapters (Vercel AI, LangChain, browser-use)

Key Commands

• plasmate fetch <url> - Fetch URL, output SOM JSON
• plasmate fetch <url> --text - Extract readable text only
• plasmate fetch <url> -H "Authorization: Bearer ..." - Fetch with custom headers
• plasmate serve - Start CDP server
• plasmate mcp - Start MCP server (stdio)
• plasmate bench <url> - Run benchmarks

Testing

cargo test
cargo check

Version

Version is derived from Cargo.toml via env!("CARGO_PKG_VERSION"). Do not hardcode version strings.

Running State

2026-05-17T07:06:05Z - Plasmate Improvements Automation

• Git sync: required git fetch --prune origin was attempted first in the linked automation worktree and failed because shared worktree metadata FETCH_HEAD could not be opened (Operation not permitted). Fallback fetch from /Users/steve/Git/plasmate failed DNS for github.com, so work continued from the already-local HEAD/origin/master 11eda59.
• Market direction: current trend research still supports the local-first SOM wedge. Browserbase/Stagehand emphasizes act/extract/observe/agent, action caching, session replay, prompt observability, and local-to-cloud portability; Cloudflare Browser Rendering added CDP endpoints plus MCP client support; Firecrawl continues packaging scrape/search/extract and browser interaction through MCP surfaces. No hosted-browser pivot is recommended; the sticky move is making ordinary CDP clients resolve SOM-backed action targets with selectors and node attributes before raw DOM recovery.
• Code changes: CDP DOM.querySelector / DOM.querySelectorAll now support tag-qualified and bare attribute selectors for name, href, type, aria-label, aria-labelledby, aria-describedby, role, test ids, and boolean availability attrs. Text/label matching is now case-insensitive. CDP DOM nodes now expose replay attributes such as data-plasmate-id, data-som-role, HTML id, test id, ARIA label, href/name/type, and disabled/readonly/required flags when available.
• Docs changes: README, PRD, roadmap source docs, and generated website docs now document the CDP attribute-selector rationale and selector/node-attribute compatibility contract.
• Verification passed: touched-file rustfmt check, focused cargo test cdp::, node website/build.mjs with the primary-checkout website/node_modules symlink removed afterward, git diff --check, cargo build --quiet, cargo test --lib --quiet (281), and cargo clippy --quiet with existing warnings.
• Verification blocked: full cargo test --quiet still fails only in sandboxed tests/awp_integration_test.rs because local listener setup returns Operation not permitted.
• Commit/push state: alternate-index commit 31dc7c1 (chore: improve CDP attribute selector parity) was pushed to remote master and to origin/codex/plasmate-improvements-2026-05-17-cdp-attribute-selectors.