# 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](https://github.com/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](https://github.com/outfitter-dev/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](https://github.com/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
```bash
# Install dependencies
bun install
# Start the server (HTTP + WebSocket on :9334)
bun run dev
# Start MCP server (optional)
bun run dev:mcp
```
### CLI
```bash
# 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:
```bash
nav install --plugin claude
```
Then use the `navigator` tool with action routing:
```json
{ "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`](.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