Navigator

Browser automation for AI agents. Clean, simple, contributable.

Navigator exposes a single action-based MCP tool, supports selector-first interactions, and includes a marker system for durable UI annotations.

Built on agent-browser

Navigator extends vercel-labs/agent-browser, adding paired mode (work in your browser via Chrome extension), a marker system for UI annotations, session continuity, and other UX enhancements for AI agents.

We maintain a fork at @outfitter/agent-browser. As we develop enhancements that benefit the broader community, we contribute them back upstream.

Contribution process:

1. Implement and test changes in our fork
2. File a PR against vercel-labs/agent-browser

Features

• Single MCP tool — One navigator tool with action routing (not 26+ separate tools)
• CLI — nav open, nav click, nav snap, nav marker
• Paired mode — Agent works in your browser via Chrome extension
• Markers — Click to annotate, copy to agent with notes
• Sessions — Auto-continuation within 30min, step logging
• Element refs — e{index} format (e.g., e42) with symbol prefixes (@ link, $ button, # input)

Quick Start

# Install dependencies
bun install

# Start the server (HTTP + WebSocket on :9334)
bun run dev

# Start MCP server (optional)
bun run dev:mcp

CLI

# Navigate and interact
nav open https://example.com
nav snap                      # Snapshot with element refs
nav snap -i                   # Interactive elements only
nav click @e1                 # Click element by ref
nav type "#e2" "hello"        # Type into input

# Markers
nav marker set homepage        # Save current page as marker
nav marker list                # List all markers
nav marker read homepage       # Get marker content

# Sessions
nav session                   # Show current session
nav steps                     # List recent steps

MCP (Claude Code)

Install the navigator plugin:

nav install --plugin claude

Then use the navigator tool with action routing:

{ "action": "navigate", "url": "https://example.com" }
{ "action": "snap", "interactive": true }
{ "action": "click", "ref": "e1" }

Storage

~/.local/share/navigator/{project-hash}/sessions/
├── {session-id}/
│   ├── meta.json           # Session metadata
│   ├── steps.jsonl         # Action log
│   └── markers/
│       └── {marker-id}.json

Documentation

See .agents/plans/v1/PLAN.md for architecture and implementation details.

Capabilities source of truth: Action exposure for CLI/MCP is defined in packages/core/src/capabilities/manifest.ts, and the CLI help + MCP tool description are generated from it.

License

MIT