TideSurf is a TypeScript library that connects Chromium to LLM agents via the Chrome DevTools Protocol (CDP). It walks the live DOM, compresses it into a token-efficient structured representation (50-200 tokens per page), and exposes 18 tool definitions for LLM function calling. No screenshots, no vision models -- just DOM compression that keeps token costs 10-100x lower than screenshot-based approaches.

Installation

npm install @tidesurf/core
# or
bun add @tidesurf/core

Requires Chrome/Chromium installed locally (auto-detected, or set CHROME_PATH).

Quick Start

import { TideSurf } from "@tidesurf/core";

// Launch Chrome and navigate
const browser = await TideSurf.launch();
await browser.navigate("https://example.com");

// Get compressed page state (50-200 tokens)
const state = await browser.getState();
console.log(state.content);

// Interact with elements using their IDs (L=link, B=button, I=input, S=select)
const page = browser.getPage();
await page.click("L1");
await page.type("I1", "search query", true);

await browser.close();

CLI Usage

TideSurf ships with a CLI for quick inspection and MCP server mode.

# Inspect a page — prints compressed DOM to stdout
npx @tidesurf/core inspect https://example.com

# Start the MCP server for Claude Code integration
npx @tidesurf/core mcp

MCP Integration

Add TideSurf as an MCP server in your Claude Code configuration (.mcp.json):

{
  "mcpServers": {
    "tidesurf": {
      "command": "npx",
      "args": ["-y", "@tidesurf/core", "mcp"]
    }
  }
}

Once configured, all 18 TideSurf tools become available as MCP tools that your AI assistant can invoke directly.

Read-Only Mode

const browser = await TideSurf.connect({ readOnly: true });
// Agent can observe, search, and screenshot — but cannot click, type, or navigate

Documentation

• Getting started -- installation, first steps, and output modes
• Page format -- understand the compressed DOM output and element IDs
• Token budget -- control output size with maxTokens
• Agent patterns -- real-world agent loop examples
• Security -- read-only mode, input validation, and CDP security
• API reference -- full method signatures and tool definitions