plasmate: Instructions file for Codex

AGENTS.md — Plasmate Codebase Guide

This file is for AI coding agents (Cursor, Devin, Claude Code, Copilot, etc.). It tells you what the codebase does, how it is structured, and how to make changes safely.

What Plasmate is

Plasmate is a headless browser engine that compiles web pages into a Semantic Object Model (SOM) — structured JSON optimised for LLM consumption — instead of returning raw HTML. Output size is page-, configuration-, corpus-, and serialization-dependent. Retained v0.5.1 public-web snapshots measured median serialized-byte ratios of 9.98x over 83 successful non-JavaScript inputs and 9.32x over 82 successful JavaScript inputs, each from 98 attempted URLs. Those historical observations are not universal token, cost, latency, or task success claims. No API key, no cloud.

It runs as a CLI, a persistent daemon, an MCP server, and a CDP server.

Build

~/.cargo/bin/cargo build              # debug
~/.cargo/bin/cargo build --release    # release

Requires Rust 1.88+ (including --all-features). No system dependencies beyond a C linker.

Test

~/.cargo/bin/cargo test               # all tests
~/.cargo/bin/cargo test som::         # SOM tests only
~/.cargo/bin/cargo test mcp::         # MCP tests only
RUST_LOG=debug ~/.cargo/bin/cargo test -- --nocapture  # with logging

Run the suite rather than citing a hard-coded test count; the count changes as the repository evolves. All tests must pass before a PR.

Key directories

src/
  main.rs          CLI entry point (fetch, compile, diff, mcp, serve, daemon, screenshot)
  mcp/
    mod.rs         MCP server, JSON-RPC router, session manager
    tools.rs       ALL MCP tool definitions + handlers (add new tools here)
    sessions.rs    Persistent browser session state
  som/
    mod.rs         SOM data structures and serialisation
    filter.rs      apply_selector() — shared between CLI and MCP
    compiler.rs    HTML → SOM compiler (the core algorithm)
  js/
    runtime.rs     V8-backed JS execution
    pipeline.rs    Full fetch+JS+compile pipeline
  network/
    fetch.rs       HTTP client (reqwest)
sdk/python/        Python SDK (MCP client)
sdk/node/          Node.js SDK (MCP client)
integrations/      LangChain, LlamaIndex, Browser Use, etc.
packages/          som-parser-python, som-parser-node