Website · Download · Quick Start · MCP Tools · Architecture · Contributing
--- **Oculo** is a full-Chromium desktop browser that speaks the [Model Context Protocol](https://modelcontextprotocol.io). 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:
| | Capability |
|---|---|
| **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 text 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 every MCP response |
| **Anti-injection** | Content boundary markers + regex-based prompt-injection detection |
| **19 stealth patches** | Navigator, WebGL, canvas, WebRTC, audio, font, battery, and screen fingerprint defenses |
| **Headless mode** | Run without a window β Docker support included |
| **Cross-platform** | macOS, Windows, Linux |
| **Python SDK** | `pip install oculo` β sync and async clients |
Each tool does one thing and returns the smallest useful answer. Token cost is the response size the agent pays for.
| Tool | What it does | Token cost |
|------|-------------|------------|
| `page` | Describe the current page β headings, forms, buttons, links. 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. 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 video (Veo 3.1); image-to-image editing | file path |
| `shell` | Execute shell commands non-interactively (ls, npm, git, python, β¦) | 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](https://webmcp.org) protocol.
### 1. Install
Grab the latest build from [Releases](https://github.com/xidik12/oculo/releases), or run from source:
```bash
git clone https://github.com/xidik12/oculo.git
cd oculo
npm install
npm run dev
```
### 2. Register with your MCP client
**Claude Code**
```bash
claude mcp add oculo -- node ~/oculo/bin/oculo-mcp.mjs
```
**Cursor / Windsurf** β add to your MCP config (`.cursor/mcp.json` or equivalent):
```json
{
"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:
```bash
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
```bash
pip install oculo
```
```python
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
| 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 (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:
| 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 from source
```bash
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.
Built by Salakhitdinov Khidayotullo · getoculo.com