# 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) so agents can act on them. 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