# Carrot Browser Bridge

Carrot Browser Bridge is an open-source bridge between AI agents and a user's
Chrome browser. You can run your own bridge server, or use the community-hosted
instance at https://browser.carrotlabs.ai.

What it does:
- Browser extensions connect to /ws over WebSocket.
- Agents call HTTP endpoints or the MCP endpoint at /mcp.
- Users authorize agents with short-lived pairing codes from the Carrot side panel.
- Sessions can be scoped to one tab, one window, or the whole browser.

Agent docs:
- Quick start: https://browser.carrotlabs.ai/llms.txt
- Full HTTP API and command reference: https://browser.carrotlabs.ai/api.md
- OpenAPI schema for top-level HTTP routes: https://browser.carrotlabs.ai/openapi.json
- MCP endpoint: https://browser.carrotlabs.ai/mcp

How an agent should use it:
1. Ask the user to install/open the Carrot Chrome extension and generate a pairing code.
2. Claim the code with POST /sessions/claim and your agent name:
   {"code":"ABC123","agent_name":"your-agent-name"}
3. Use the returned session_token as Authorization: Bearer SESSION_TOKEN.
4. Prefer POST /cmd for browser actions. Example:
   {"type":"readPage"}
5. For page interactions, call readPage or find first and use returned ref IDs.
6. MCP clients can connect directly to any bridge instance's /mcp endpoint and use claim_session.

Useful endpoints:
- GET /status
- GET /api.md
- POST /sessions/claim
- GET /sessions
- POST /cmd
- GET /focused
- GET /tabs
- GET /windows
- GET /groups
- GET /bookmark_tree
- GET /screenshot?tabId=123
- POST /navigate
- POST /execute
- /mcp (MCP endpoint)

Common commands via POST /cmd:
- readPage, find, getPageText, dom, query
- click, hover, type, formInput, scroll, press
- navigate, goBack, goForward, execute
- tabs, focused, activateTab, createTab, closeTab, reloadTab
- duplicateTab, pinTab, muteTab, moveTab, discardTab
- getWindows, createWindow, updateWindow, closeWindow, resizeWindow
- groupTabs, ungroupTabs, updateGroup, queryGroups
- screenshot
- readConsole, readNetwork
- searchHistory, deleteHistory
- searchBookmarks, createBookmark, getBookmarkTree
- download, getDownloads, notify

For all command parameters and examples, read /api.md.

Running your own bridge:
This server is open source in this repository. Users can run server.py locally
or elsewhere, then set the extension Server URL to that bridge instance.