io.github.xidik12/oculo

Oculo — an open-source AI browser that gives Claude Code, Cursor, Windsurf, and any MCP client eyes on the live web. A sample agent flow turns the request 'Log into GitHub and star the oculo repo' into four act tool calls that log in via the credential vault and click Star, using under 100 tokens.

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.

Architecture pipeline: an MCP client (Claude Code, Cursor, Windsurf) speaks stdio to the oculo-mcp bridge, which forwards over authenticated HTTP on port 19516 to the Electron main process, which sends IPC to the React renderer, which runs executeJavaScript inside the webview holding the live web page. Tools stay discoverable when idle; Oculo must be running to execute; port and token are published to ~/.oculo-port.

Why HTTP instead of stdio? Electron's <webview> 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 require npm), macOS / Windows / Linux.

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 (ports 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 a new MCP tool.

Donate

If Oculo saves you time, you can support development — BTC: 12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B

License

MIT © 2026 Salakhitdinov Khidayotullo

Built by Salakhitdinov Khidayotullo · getoculo.com