{
  "markdown": "<p align=\"center\">\n  <img src=\"./assets/readme/hero.svg\" width=\"100%\" alt=\"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.\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/xidik12/oculo/stargazers\"><img src=\"https://img.shields.io/github/stars/xidik12/oculo?style=flat\" alt=\"GitHub stars\"></a>\n  <a href=\"https://github.com/xidik12/oculo/releases\"><img src=\"https://img.shields.io/github/v/release/xidik12/oculo\" alt=\"Latest release\"></a>\n  <img src=\"https://img.shields.io/badge/Electron-34-47848F?logo=electron&logoColor=white\" alt=\"Electron 34\">\n  <img src=\"https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white\" alt=\"TypeScript 5.7\">\n  <img src=\"https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black\" alt=\"React 19\">\n  <img src=\"https://img.shields.io/badge/MCP-12%20tools-orange\" alt=\"12 MCP tools\">\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-green\" alt=\"MIT License\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://getoculo.com\">Website</a> &middot;\n  <a href=\"https://github.com/xidik12/oculo/releases\">Download</a> &middot;\n  <a href=\"#quick-start\">Quick Start</a> &middot;\n  <a href=\"#the-toolbelt\">MCP Tools</a> &middot;\n  <a href=\"#how-it-works\">Architecture</a> &middot;\n  <a href=\"CONTRIBUTING.md\">Contributing</a>\n</p>\n\n---\n\n**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**.\n\n> *Cursor : VSCode :: Oculo : Chrome*\n\n## See it in action\n\nYour agent describes intent; Oculo resolves it into a few tiny tool calls and hands back terse, redacted results — not megabytes of screenshots.\n\n```\nYou: \"Log into GitHub and star the oculo repo\"\n\nClaude Code calls:\n  1. act({action: \"navigate\", url: \"https://github.com/login\"})\n  2. act({action: \"login\", site: \"github.com\"})         # vault lookup, password never leaves the OS keychain\n  3. act({action: \"navigate\", url: \"https://github.com/xidik12/oculo\"})\n  4. act({action: \"click\", text: \"Star\"})\n\n→ 4 tool calls, <100 tokens of response\n```\n\n```\nYou: \"Fill out the contact form on example.com\"\n\nClaude Code calls:\n  1. act({action: \"navigate\", url: \"https://example.com/contact\"})\n  2. page()                                               # see the form structure\n  3. fill({fields: {\"Name\": \"...\", \"Email\": \"...\"}, submit: true})\n\n→ 3 tool calls\n```\n\n<img src=\"./assets/readme/section-why.svg\" width=\"100%\" alt=\"Section: Why Oculo — a native engine, not a wrapper\">\n\nOculo runs a real Chromium engine on your machine and adds an agent-first control layer on top. That combination is the point:\n\n| | Capability |\n|---|---|\n| **Native browser** | Full Chromium engine — not a wrapper, extension, or headless scraper |\n| **12 MCP tools** | page, act, fill, read, run, media, shell, tabs, research, preview, translate, lens |\n| **< 300 tokens / flow** | Compact text responses by default — cheaper than screenshot-based approaches |\n| **Self-healing automation** | Selector caching + DOM diffing — 44%+ faster on repeated workflows |\n| **Multi-provider AI** | Built-in chat with Claude, OpenAI, Gemini, Grok, OpenClaw, Ollama |\n| **4-level security** | auto / notify / confirm / blocked permission gate on every action |\n| **OS keychain vault** | Credentials encrypted via `electron.safeStorage` (macOS Keychain / Windows DPAPI) |\n| **PII redaction** | Credit cards, SSNs, JWTs, API keys, Bearer tokens stripped from every MCP response |\n| **Anti-injection** | Content boundary markers + regex-based prompt-injection detection |\n| **19 stealth patches** | Navigator, WebGL, canvas, WebRTC, audio, font, battery, and screen fingerprint defenses |\n| **Headless mode** | Run without a window — Docker support included |\n| **Cross-platform** | macOS, Windows, Linux |\n| **Python SDK** | `pip install oculo` — sync and async clients |\n\n<img src=\"./assets/readme/section-tools.svg\" width=\"100%\" alt=\"Section: The Toolbelt — one verb per call\">\n\nEach tool does one thing and returns the smallest useful answer. Token cost is the response size the agent pays for.\n\n| Tool | What it does | Token cost |\n|------|-------------|------------|\n| `page` | Describe the current page — headings, forms, buttons, links. Compact, a11y (ref-tagged), and markdown modes | ~30–80 |\n| `act` | Navigate, click, hover, scroll, type, press keys, login via vault, manage tabs, cookies, proxy, recording | ~1 line |\n| `fill` | Fill form fields by label/placeholder matching, optional submit. Text, select, checkbox, contenteditable | ~1 line |\n| `read` | Extract structured data — search results, tables, lists, articles | compact |\n| `run` | Multi-step pipeline with conditionals (`page`/`act`/`fill`/`read`/`wait`/`if`). Cached for replay | header + last |\n| `media` | Generate images (Nano Banana 2 / DALL·E 3) or video (Veo 3.1); image-to-image editing | file path |\n| `shell` | Execute shell commands non-interactively (ls, npm, git, python, …) | stdout + stderr |\n| `tabs` | List all open browser tabs with URLs and titles | compact |\n| `research` | Deep web research — opens multiple tabs, reads pages, synthesizes findings | synthesized |\n| `preview` | Pre-fetch a URL without navigating away from the current page | page description |\n| `translate` | Translate page content or specific text to any language | translated text |\n| `lens` | Visual analysis of the current page via screenshot + AI vision | description |\n\n**Bonus:** `webmcp_list` and `webmcp_call` discover and invoke page-declared tools via the [WebMCP](https://webmcp.org) protocol.\n\n<img src=\"./assets/readme/section-how.svg\" width=\"100%\" alt=\"Section: How It Works — stdio to HTTP to webview\">\n\n<p align=\"center\">\n  <img src=\"./assets/readme/architecture.svg\" width=\"100%\" alt=\"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.\">\n</p>\n\n**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.\n\n**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.\n\n<img src=\"./assets/readme/section-start.svg\" width=\"100%\" alt=\"Section: Quick Start — clone, run, register\">\n\n### 1. Install\n\nGrab the latest build from [Releases](https://github.com/xidik12/oculo/releases), or run from source:\n\n```bash\ngit clone https://github.com/xidik12/oculo.git\ncd oculo\nnpm install\nnpm run dev\n```\n\n### 2. Register with your MCP client\n\n**Claude Code**\n\n```bash\nclaude mcp add oculo -- node ~/oculo/bin/oculo-mcp.mjs\n```\n\n**Cursor / Windsurf** — add to your MCP config (`.cursor/mcp.json` or equivalent):\n\n```json\n{\n  \"mcpServers\": {\n    \"oculo\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/oculo/bin/oculo-mcp.mjs\"]\n    }\n  }\n}\n```\n\n### 3. (Optional) Headless & Docker\n\nRun without a visible window for CI/CD, scraping, or server-side automation:\n\n```bash\nnode bin/oculo-headless.mjs                          # convenience launcher\nnpx electron . --headless                            # or raw flags\nnpx electron . --headless --headless-auto-approve    # auto-approve CONFIRM actions\nOCULO_HEADLESS=1 npm run dev                          # or via env var\n\ndocker compose up                                    # containerized headless (Xvfb)\n```\n\n### 4. (Optional) Python SDK\n\n```bash\npip install oculo\n```\n\n```python\nfrom oculo import OculoClient\n\nclient = OculoClient()                 # auto-discovers port from ~/.oculo-port\nprint(client.page())                   # describe the page\nclient.act(\"navigate\", url=\"https://example.com\")\nclient.fill({\"Email\": \"hi@oculo.com\", \"Message\": \"Hello!\"}, submit=True)\nresults = client.read(\"search results\", format=\"json\")\n```\n\nAn async `AsyncOculoClient` with the same surface is also available.\n\n<img src=\"./assets/readme/section-security.svg\" width=\"100%\" alt=\"Section: Security Model — gate, vault, redact\">\n\nEvery action passes through a permission gate, and every response is redacted before it reaches the model.\n\n### Permission levels\n\n| Level | Actions | Behavior |\n|-------|---------|----------|\n| **Auto** | navigate, page, read, scroll, screenshot, back, forward, reload, hover, listTabs, switchTab, preview, translate, lens | Executes silently |\n| **Notify** | click, type, fill, select, press, submit, newTab, closeTab | Executes + OS notification |\n| **Confirm** | payment, delete_account, change_password, send_email, download, oauth, shell, evaluate, setProxy, startRecording | Native dialog approval required |\n| **Blocked** | read_vault, export_cookies, export_tokens, disable_security | Always rejected |\n\n### Credential vault\n\n- Encrypted with `electron.safeStorage` → OS Keychain (macOS) / DPAPI (Windows).\n- Passwords are **never** returned via IPC or MCP — only domain + username are exposed.\n- `act({action: \"login\", site: \"github.com\"})` retrieves and fills credentials without the model ever seeing them.\n\n### Redaction & anti-injection\n\n- Every MCP response passes through a redactor that strips credit-card numbers, SSNs, JWTs, API keys, private keys, and Bearer tokens.\n- Page content handed to the model is wrapped in boundary markers, and regex-based detection blocks prompt-injection attempts embedded in that content.\n\n### Stealth (19 patches)\n\nNavigator (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.\n\n### Self-healing automation\n\nAfter 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:\n\n- **> 80% similarity** — replay from cache, no LLM call.\n- **50–80%** — fall back to alternative selectors.\n- **< 50%** — re-engage the AI for a fresh resolution.\n\nThat's where the 44%+ speed-up on repeated workflows comes from.\n\n## Built-in AI chat\n\nOculo also ships a side-panel chat that talks to multiple providers directly:\n\n| Provider | Auth | Models |\n|----------|------|--------|\n| **Claude** | API key or CLI subscription | Opus, Sonnet, Haiku |\n| **OpenAI** | API key or Codex CLI | GPT-4o, GPT-4o mini, o1, o3 |\n| **Gemini** | API key | 2.0 Flash, 1.5 Pro, 1.5 Flash |\n| **Grok** | API key | Grok 2, Grok 2 Mini |\n| **Ollama** | Local (no key) | Any pulled model |\n| **OpenClaw** | API key | OpenClaw models |\n\n## Building from source\n\n```bash\nnpm run build          # production build\nnpm run dist:mac       # macOS DMG + ZIP\nnpm run dist:win       # Windows NSIS + portable\nnpm run dist:linux     # Linux AppImage + deb\n\nnpm run typecheck      # TypeScript\nnpm run lint           # ESLint\nnpm run test           # Vitest\n```\n\n**Prerequisites:** Node.js 20+, npm (not pnpm/yarn — native modules require npm), macOS / Windows / Linux.\n\n<details>\n<summary><strong>Project structure</strong></summary>\n\n```\nsrc/\n  main/                    Electron main process\n    ai/agent.ts            Multi-provider AI controller\n    captcha/               CAPTCHA detection + solvers\n    data/                  Bookmarks, downloads, history, session recording\n    engine/                Page describer, extractor, form-detector, pipeline, resolver,\n                           selector-cache, dom-differ, tab-manager\n    mcp/server.ts          HTTP MCP server (ports 19516–19520, auth token)\n    mcp/tools/             act, fill, page, read, run tool handlers\n    network/proxy.ts       HTTP/SOCKS proxy manager\n    security/              Vault, permissions, redactor, audit, anti-injection\n  preload/index.ts         contextBridge API\n  renderer/\n    App.tsx                Root browser UI component\n    components/            TabBar, AddressBar, ChatPanel, WebViewContainer,\n                           bookmarks, downloads, find, history, layout, common\n  shared/                  Types, constants, IPC channels, AI provider definitions\nbin/\n  oculo-mcp.mjs            stdio-to-HTTP MCP bridge (for Claude Code / Cursor)\n  oculo-headless.mjs       Headless mode launcher\nsdk/python/                Python SDK (pip install oculo)\nDockerfile                 Container deployment\ndocker-compose.yml         Docker Compose for headless mode\n```\n\n</details>\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture details, and how to add a new MCP tool.\n\n## Donate\n\nIf Oculo saves you time, you can support development — **BTC:** `12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B`\n\n## License\n\n[MIT](LICENSE) © 2026 Salakhitdinov Khidayotullo\n\n---\n\n<p align=\"center\">\n  Built by <a href=\"https://github.com/xidik12\">Salakhitdinov Khidayotullo</a> &middot; <a href=\"https://getoculo.com\">getoculo.com</a>\n</p>\n",
  "bytes": 13914,
  "sha": "1e9fec685fb32e10fcbe8c97b686639b46f54eb2f93f77a6a99e3d802f57feb8",
  "repo_slug": "xidik12/oculo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xidik12_oculo_363aefbf/readme"
}