# Carrot Browser Bridge

Carrot is a hosted bridge between AI agents and a user's Chrome browser.
The hosted service is available 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.

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 https://browser.carrotlabs.ai/mcp and use claim_session.

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

Common commands via POST /cmd:
- readPage, find, getPageText, query
- click, hover, type, formInput, scroll, press
- navigate, goBack, goForward
- tabs, focused, getWindows
- screenshot
- readConsole, readNetwork

Self-hosting:
The bridge server is open source in this repository. Users can run their own
server.py locally or run it elsewhere, then set the extension Server URL to
their server instead of https://browser.carrotlabs.ai.