Oculo

Website · Download · Quick Start · MCP Tools · Architecture · Contributing

---

Oculo is a full-Chromium desktop browser that speaks the Model Context Protocol. Point Claude Code, Cursor, Windsurf, or any MCP client at it and your agent can *see* and *drive* real web pages — read the DOM, click, fill forms, extract data, run multi-step pipelines — through 12 compact tools that answer in under 300 tokens per flow.

*Cursor : VSCode :: Oculo : Chrome*

See it in action

Your agent describes intent; Oculo resolves it into a few tiny tool calls and hands back terse, redacted results — not megabytes of screenshots.

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, password never leaves the OS keychain
3. act({action: "navigate", url: "https://github.com/xidik12/oculo"})
4. act({action: "click", text: "Star"})

→ 4 tool calls, <100 tokens of 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 structure
3. fill({fields: {"Name": "...", "Email": "..."}, submit: true})

→ 3 tool calls

Oculo runs a real Chromium engine on your machine and adds an agent-first control layer on top. That combination is the point:

Each tool does one thing and returns the smallest useful answer. Token cost is the response size the agent pays for.

Bonus: webmcp_list and webmcp_call discover and invoke page-declared tools via the WebMCP protocol.

Why HTTP instead of stdio? Electron's is only reachable from the renderer process. The main process — where stdio lives — can't touch page content. The HTTP bridge crosses that boundary via main-to-renderer IPC.

Port discovery. On startup Oculo writes port:authtoken to ~/.oculo-port. The bin/oculo-mcp.mjs bridge reads it automatically, so tool definitions stay discoverable even when the app is closed — only *execution* requires Oculo to be running.

1. Install

Grab the latest build from Releases, or run from source:

git clone https://github.com/xidik12/oculo.git

cd oculo npm install npm run dev

2. Register with your MCP client

Claude Code

claude mcp add oculo -- node ~/oculo/bin/oculo-mcp.mjs

Cursor / Windsurf — add to your MCP config (.cursor/mcp.json or equivalent):

{

"mcpServers": { "oculo": { "command": "node", "args": ["/path/to/oculo/bin/oculo-mcp.mjs"] } } }

3. (Optional) Headless & Docker

Run without a visible window for CI/CD, scraping, or server-side automation:

node bin/oculo-headless.mjs                          # convenience launcher

npx electron . --headless # or raw flags npx electron . --headless --headless-auto-approve # auto-approve CONFIRM actions OCULO_HEADLESS=1 npm run dev # or via env var

docker compose up # containerized headless (Xvfb)

4. (Optional) Python SDK

pip install oculo

from oculo import OculoClient

client = OculoClient() # auto-discovers port from ~/.oculo-port print(client.page()) # describe the page client.act("navigate", url="https://example.com") client.fill({"Email": "hi@oculo.com", "Message": "Hello!"}, submit=True) results = client.read("search results", format="json")

An async AsyncOculoClient with the same surface is also available.

Every action passes through a permission gate, and every response is redacted before it reaches the model.

Permission levels

Credential vault

• Encrypted with electron.safeStorage → OS Keychain (macOS) / DPAPI (Windows).
• Passwords are never returned via IPC or MCP — only domain + username are exposed.
• act({action: "login", site: "github.com"}) retrieves and fills credentials without the model ever seeing them.

Redaction & anti-injection

• Every MCP response passes through a redactor that strips credit-card numbers, SSNs, JWTs, API keys, private keys, and Bearer tokens.
• Page content handed to the model is wrapped in boundary markers, and regex-based detection blocks prompt-injection attempts embedded in that content.

Stealth (19 patches)

Navigator (webdriver, languages, plugins, mimeTypes, connection, hardwareConcurrency, deviceMemory), window (chrome API, dimensions), WebGL (vendor/renderer spoofing), canvas (per-call fingerprint randomization), WebRTC (IP-leak prevention), AudioContext, font enumeration blocking, Battery API, and screen-resolution randomization.

Self-healing automation

After a successful act/fill, selectors are cached with stability scores — id and data-testid = 10, aria-label = 9, role+name = 8, text = 7, css = 5. On the next run, DOM diffing picks the strategy:

• > 80% similarity — replay from cache, no LLM call.
• 50–80% — fall back to alternative selectors.
• < 50% — re-engage the AI for a fresh resolution.

That's where the 44%+ speed-up on repeated workflows comes from.

Built-in AI chat

Oculo also ships a side-panel chat that talks to multiple providers directly:

Building from source

npm run build          # production build

npm run dist:mac # macOS DMG + ZIP npm run dist:win # Windows NSIS + portable npm run dist:linux # Linux AppImage + deb

npm run typecheck # TypeScript npm run lint # ESLint npm run test # Vitest

Prerequisites: Node.js 20+, npm (not pnpm/yarn — native modules requ