llms.txt

# TideSurf

> The connector between Chromium and LLM agents — no screenshots, no vision models, just the DOM compressed for machines.

TideSurf launches Chrome via CDP, walks the live DOM, and compresses it into a token-efficient markdown-like format (50–200 tokens per page vs 5,000–50,000+ for raw HTML). Interactive elements get stable IDs (L=link, B=button, I=input, S=select, F=form, T=table, D=dialog) so agents can act on them. Element state flags (disabled, expanded, collapsed, checked, required, readonly, obscured, inert) are serialized inline so agents know which elements are actionable. Ships with 18 tool definitions and an MCP adapter.

## Install

```bash
bun add @tidesurf/core
```

## Quick Start

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

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

const state = await browser.getState();
console.log(state.content);

const page = browser.getPage();
await page.click("B1");
await page.type("I1", "hello world");
await page.search("pricing"); // returns nearest interactive IDs when available

await browser.close();
```

Read-only mode keeps: `get_state`, `extract`, `list_tabs`, `switch_tab`, `search`, `screenshot`.

`clipboard_read`, `evaluate`, `upload`, and custom `downloadDir` access are disabled or constrained in read-only/safe mode. File I/O is confined to the current working directory and the OS temp directory unless `fileAccessRoots` is set explicitly.

## MCP

```json
{
  "mcpServers": {
    "tidesurf": {
      "command": "bunx",
      "args": ["tidesurf", "mcp"]
    }
  }
}
```

## Links

- Docs: https://tidesurf.org/docs
- GitHub: https://github.com/TideSurf/core
- npm: https://www.npmjs.com/package/@tidesurf/core
- Website llms.txt: https://tidesurf.org/llms.txt