TideSurf - Surf the Tide

Compression 01

HTML in, text out

Same page. Fewer tokens. Stable IDs remain visible so the agent can act without pixels.

raw.html12 lines

<nav class="main-nav">
  <a id="docs" href="/docs">Docs</a>
  <a id="blog" href="/blog">Blog</a>
  <button class="primary">Start</button>
</nav>

tidesurf.txt~132 tokens

# example.com
URL: https://example.com/
---
L1 [LINK] Docs /docs
L2 [LINK] Blog /blog
B1 [BUTTON] Start /start

Prune wrappers, keep targets

Reduce cost before reasoning

50-200tokens per page

10-100xlower token cost

<25msparse time

0screenshots

Patterns 02

Built for agents

Three lines to browse. One tool call to act.

Chat request

Find the latest issue title and open it.

Agent tool loop

const state = await browser.getState()
state.content -> LLM
await browser.click("L3")

Browser page state

MAIN
  HEADING Issues
  [L1] Pull requests
  [L2] Actions
  [L3] Latest issue title
  [B1] New issue

Chat request

Tool call

Browser result

Features 03

What ships

Direct CDP tools, token budgets, tab lifecycle, extraction, and MCP wiring in one small TypeScript surface.

Navigate

Go anywhere on the web

navigate("https://...")

Interact

Click, type, select, scroll

click("B1"), type("I1")

Extract

Read precise page content

extract({ selector })

Budget

Keep output within token limits

getState({ maxTokens })

Tabs

Create, switch, close

newTab(), switchTab()

MCP

Expose tools to Codex agents

bunx tidesurf mcp

Security 04

Safe by default

Read-only modeRestrict agents to observation only. No clicks, no typing, no navigation.
Filesystem confinementUpload and download paths are locked to explicit roots.
Input validationURLs, selectors, expressions, and file paths are validated before execution.
Local CDP onlyChrome DevTools Protocol runs over local WebSocket.

Writes stay blocked

Local loop only

agent.config.ts

const browser = await TideSurf.launch({
  readOnly: true,
  allowedOrigins: ["example.com"],
  maxTokens: 500
})

Try it 05

Try it

Launch a browser, connect to an existing Chrome, or expose TideSurf through MCP.

$ npm install @tidesurf/core

index.ts

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

$ npm install @tidesurf/core

connect.ts

const browser = await TideSurf.connect()
await browser.switchTab(0)
const state = await browser.getState({
  maxTokens: 500
})

$ bunx tidesurf mcp

mcp.json

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

Install and launch

Switch examples

Surf deeper?

Read the docs