Agents Surfing

Run browser tools from the shell. TideSurf keeps Chromium state between commands and turns the live DOM into compact text with current action handles.

brew install TideSurf/tap/tidesurf

Take a look

Keep the useful page. Drop the wrapper noise.

Actual TideSurf output: wrapper noise disappears. Navigation, form controls, visible copy, and action handles stay.

raw HTML before

<div class="header">
  <nav role="navigation">
    <ul class="nav-list">
      <a href="/">Home</a>
      <a href="/about">About</a>
    </ul>
  </nav>
</div>
<form action="/search">
  <div class="input-wrapper">
    <input placeholder="Search..." />
    <button>Search</button>
  </div>
</form>

5,348 separate fixture benchmark 1,218 e-commerce source HTML → TideSurf text

TideSurf text after

# Example Search
> example.com/search | 0/1200 800vh

NAV
  [L1](/) Home
  [L2](/about) About
FORM F1
  I1 ~Search... ="TideSurf"
  [B1] Search

Read it. Choose a handle. Use the live page.

The text reflects live browser state, not an export. Each handle routes through CDP to its Chromium session.

read
Compact page state avoids raw HTML for routine actions.
choose
The model picks a handle: B1, L2, or I1.
act
TideSurf validates the action and passes it to the live element through CDP.

agent action local CDP

await page.click("B1")

Chromium clicks the real Search button.

Small tool surface. Stateful browser runtime.

observe: Viewport state, extraction, search, tab control, and token budget.
act: Current IDs drive click, type, select, upload, and download. Scroll and page JavaScript stay explicit.
guard: Read-only mode, path limits, URL validation, retry policy, and typed errors.
connect: Run 20 CLI tools in named sessions, launch Chromium, attach to an endpoint, or use MCP.

Install it as your agent tool.

One package speaks both open packaging standards: TideSurf is an Agent Plugin with a bundled Agent Skill, and a host that loads yours.

plugin: The package root is an Agent Plugins directory: plugin.json, mcp.json, and skills/. Point VS Code, Cursor, Copilot, Codex, or Kiro at it.
skill: npx skills add TideSurf/core installs the bundled Agent Skill, or copy skills/tidesurf-browser into .agents/skills/.
mcp: Any MCP client runs tidesurf mcp over stdio. The adapter publishes installed skills in its server instructions.
host: TideSurf loads your plugins from .tidesurf/plugins and skills from .agents/skills. Agents reach them through list_skills and read_skill, and plugin MCP servers are proxied into the adapter.

Give the model a page it can use.

Read the docs Open npm