Cursor : VSCode :: Oculo : Chrome
Open-source AI browser that gives Claude Code, Cursor, Windsurf, and any MCP client the ability to see and interact with any website. 12 tools, under 300 tokens per flow.
Why Oculo?
| Feature | |
|---|---|
| Native browser | Full Chromium engine -- not a wrapper, extension, or headless scraper |
| 12 MCP tools | page, act, fill, read, run, media, shell, tabs, research, preview, translate, lens |
| < 300 tokens/flow | Compact responses by default -- cheaper than screenshot-based approaches |
| Self-healing automation | Selector caching + DOM diffing -- 44%+ faster on repeated workflows |
| Multi-provider AI | Built-in chat with Claude, OpenAI, Gemini, Grok, OpenClaw, Ollama |
| 4-level security | auto / notify / confirm / blocked permission gate on every action |
| OS keychain vault | Credentials encrypted via electron.safeStorage (macOS Keychain / Windows DPAPI) |
| PII redaction | Credit cards, SSNs, JWTs, API keys, Bearer tokens stripped from all MCP responses |
| Anti-injection | Content boundary markers + regex-based injection detection |
| 19 stealth patches | Navigator, WebGL, canvas, WebRTC, audio, font, battery, screen fingerprint defenses |
| Headless mode | Run without UI -- Docker support included |
| Cross-platform | macOS, Windows, Linux |
| Python SDK | pip install oculo -- sync and async clients |
Quick Start
Download
Grab the latest release from Releases, or build from source:
git clone https://github.com/xidik12/oculo.git
cd oculo
npm install
npm run dev
Register with Claude Code
claude mcp add oculo -- node ~/oculo/bin/oculo-mcp.mjs
Register with Cursor / Windsurf
Add to your MCP config (.cursor/mcp.json or equivalent):
{
"mcpServers": {
"oculo": {
"command": "node",
"args": ["/path/to/oculo/bin/oculo-mcp.mjs"]
}
}
}
Tools are always discoverable (static definitions in the bridge), but Oculo must be running for tool calls to succeed.
12 MCP Tools
| Tool | What it does | Token cost |
|---|---|---|
page | Describe current page -- headings, forms, buttons, links. Supports compact, a11y (ref-tagged), and markdown modes | ~30-80 |
act | Navigate, click, hover, scroll, type, press keys, login via vault, manage tabs, cookies, proxy, recording | ~1 line |
fill | Fill form fields by label/placeholder matching, optional submit. Handles text, select, checkbox, contenteditable | ~1 line |
read | Extract structured data -- search results, tables, lists, articles | compact |
run | Multi-step pipeline with conditionals (page/act/fill/read/wait/if). Cached for replay | header + last |
media | Generate images (Nano Banana 2 / DALL-E 3) or videos (Veo 3.1). Image-to-image editing | file path |
shell | Execute shell commands non-interactively (ls, npm, git, python, etc.) | stdout+stderr |
tabs | List all open browser tabs with URLs and titles | compact |
research | Deep web research -- opens multiple tabs, reads pages, synthesizes findings | synthesized |
preview | Pre-fetch a URL without navigating away from the current page | page description |
translate | Translate page content or specific text to any language | translated text |
lens | Visual analysis of the current page via screenshot + AI vision | description |
Bonus: webmcp_list and webmcp_call discover and invoke page-declared tools via the WebMCP protocol.
Example Flows
You: "Log into GitHub and star the oculo repo"
Claude Code calls:
1. act({action: "navigate", url: "https://github.com/login"})
2. act({action: "login", site: "github.com"}) # vault lookup
3. act({action: "navigate", url: "https://github.com/xidik12/oculo"})
4. act({action: "click", text: "Star"})
Total: 4 tool calls, <100 tokens response
You: "Fill out the contact form on example.com"
Claude Code calls:
1. act({action: "navigate", url: "https://example.com/contact"})
2. page() # see the form
3. fill({fields: {"Name": "...", "Email": "..."}, submit: true})
Total: 3 tool calls
Headless Mode
Run Oculo without a visible window for CI/CD, scraping, or server-side automation:
# Via convenience script
node bin/oculo-headless.mjs
# Or with flags
npx electron . --headless
npx electron . --headless --headless-auto-approve # auto-approve CONFIRM actions
# Environment variable
OCULO_HEADLESS=1 npm run dev
Docker
docker compose up
The included Dockerfile and docker-compose.yml run Oculo headless in a container with Xvfb.
Python SDK
from oculo import OculoClient
# Auto-discovers port from ~/.oculo-port
client = OculoClient()
# Describe the page
print(client.page())
# Navigate
client.act("navigate", url="https://example.com")
# Fill a form
client.fill({"Email": "hi@oculo.com", "Message": "Hello!"}, submit=True)
# Extract data
results = client.read("search results", format="json")
Async version available:
from oculo import AsyncOculoClient
async_client = AsyncOculoClient()
await async_client.act("navigate", url="https://example.com")
Install from the SDK directory:
pip install oculo
Architecture
Claude Code / Cursor / Windsurf
|
| stdio (MCP protocol)
v
bin/oculo-mcp.mjs <-- stdio-to-HTTP bridge
|
| HTTP POST :19516/mcp (auth token)
v
McpServerManager <-- Electron main process
|
| IPC
v
Renderer (React 19) <-- Chromium process
|
| webview.executeJavaScript()
v
<webview> tags <-- Actual web pages
Why HTTP instead of stdio? Electron's <webview> is only accessible from the renderer process. The main process (where stdio lives) can't touch page content. The HTTP bridge solves this via main-to-renderer IPC.
Port discovery: Oculo writes port:authtoken to ~/.oculo-port on startup. The bridge reads this file automatically.
Security
Permission Levels
| Level | Actions | Behavior |
|---|---|---|
| Auto | navigate, page, read, scroll, screenshot, back, forward, reload, hover, listTabs, switchTab, preview, translate, lens | Executes silently |
| Notify | click, type, fill, select, press, submit, newTab, closeTab | Executes + OS notification |
| Confirm | payment, delete_account, change_password, send_email, download, oauth, shell, evaluate, setProxy, startRecording | Native dialog approval required |
| Blocked | read_vault, export_cookies, export_tokens, disable_security | Always rejected |
Credential Vault
- Encrypted with
electron.safeStorage(OS Keychain on macOS, DPAPI on Windows) - Passwords never returned via IPC or MCP -- only domain + username exposed
act({action: "login", site: "github.com"})retrieves and fills credentials automatically
PII Redaction
All MCP responses pass through a redactor before reaching the AI client. Stripped patterns: credit card numbers, SSNs, JWTs, API keys, private keys, Bearer tokens.
Anti-Injection
MCP content is wrapped in boundary markers. Regex-based detection blocks prompt injection attempts embedded in page content.
Stealth (19 patches)
Navigator (webdriver, languages, plugins, mimeTypes, connection, hardwareConcurrency, deviceMemory), window (chrome API, dimensions), WebGL (vendor/renderer spoofing), canvas (fingerprint randomization), WebRTC (IP leak prevention), AudioContext, font enumeration blocking, Battery API, screen resolution randomization.
Self-Healing Automation
After successful act or fill calls, element selectors are cached with stability scores:
| Selector type | Score |
|---|---|
id | 10 |
data-testid | 10 |
aria-label | 9 |
role + name | 8 |
text | 7 |
css | 5 |
On subsequent runs, DOM diffing determines the strategy:
- > 80% similarity -- replay from cache (no LLM call needed)
- 50-80% -- fallback to alternative selectors
- < 50% -- re-engage AI for fresh resolution
AI Providers
Built-in chat panel supports multiple providers:
| Provider | Auth | Models |
|---|---|---|
| Claude | API Key or CLI subscription | Opus, Sonnet, Haiku |
| OpenAI | API Key or Codex CLI | GPT-4o, GPT-4o mini, o1, o3 |
| Gemini | API Key | 2.0 Flash, 1.5 Pro, 1.5 Flash |
| Grok | API Key | Grok 2, Grok 2 Mini |
| Ollama | Local (no key) | Any pulled model |
| OpenClaw | API Key | OpenClaw models |
Building
# Production build
npm run build
# Platform distributables
npm run dist:mac # macOS DMG + ZIP
npm run dist:win # Windows NSIS + portable
npm run dist:linux # Linux AppImage + deb
# Other commands
npm run typecheck # TypeScript checking
npm run lint # ESLint
npm run test # Vitest
npm run clean # Remove build artifacts
Prerequisites
- Node.js 20+
- npm (not pnpm/yarn -- native modules require npm)
- macOS, Windows, or Linux
Project Structure
src/
main/ Electron main process
ai/agent.ts Multi-provider AI controller
captcha/ CAPTCHA detection + solvers
data/ Bookmarks, downloads, history, session recording
engine/ Page describer, extractor, form-detector, pipeline, resolver,
selector-cache, dom-differ, tab-manager
mcp/server.ts HTTP MCP server (port 19516-19520, auth token)
mcp/tools/ act, fill, page, read, run tool handlers
network/proxy.ts HTTP/SOCKS proxy manager
security/ Vault, permissions, redactor, audit, anti-injection
preload/index.ts contextBridge API
renderer/
App.tsx Root browser UI component
components/ TabBar, AddressBar, ChatPanel, WebViewContainer,
bookmarks, downloads, find, history, layout, common
shared/ Types, constants, IPC channels, AI provider definitions
bin/
oculo-mcp.mjs stdio-to-HTTP MCP bridge (for Claude Code / Cursor)
oculo-headless.mjs Headless mode launcher
sdk/python/ Python SDK (pip install oculo)
Dockerfile Container deployment
docker-compose.yml Docker Compose for headless mode
Contributing
See CONTRIBUTING.md for development setup, architecture details, and how to add new MCP tools.
Donate
If Oculo saves you time, consider supporting development:
BTC: 12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B
License
Built by Salakhitdinov Khidayotullo | getoculo.com