Skip to main content

Optima AI Browser

A browser built for AI assistants.
Clean pages for the agent, a quick tap for the human when it matters.

tests Glama score
macOS · Windows · Linux  |  MCP server + Claude skill  |  MIT


Why Optima?

Ordinary browsers are made for human eyes. When an AI assistant drives one, it wastes time and tokens on ads, pop-ups and cookie walls, loses its logins, and stalls without saying anything the moment a site asks for a human.

Optima fixes the agent side of browsing, and keeps a person in the loop for the parts that need one:

Ordinary browser + AI Optima
What the agent sees Raw HTML or screenshots Clean text with numbered elements: [12 button] Sign in
Cookie banners The agent clicks around them Declined automatically ("reject" / "only necessary")
Logins Lost between sessions Persistent profile: log in once
CAPTCHA / "checking your browser" Agent gets stuck Detected → you get a notification → you solve it → the agent continues
Passwords & cards Risky Always typed by you; the agent is refused these fields
Buying, posting, deleting Happens silently Agent must ask you in chat first
What happened? Unknown Daily audit log

Optima does not solve or bypass CAPTCHAs or bot protection, by design. Those checks are how sites decide who gets in. Optima makes the hand-off to you take seconds instead.

How it works

 AI assistant ──MCP──▶ Optima server (Python) ──▶ engine ──▶ the web
   (Claude…)            reading, rules,             macOS: native app on system WebKit
                        hand-off, log               Windows/Linux: Edge/Chrome via Playwright
                              │
                              └──▶ you: notification + "Your turn" banner + Done button
  • macOS: a tiny native app (Swift + the WebKit that ships with macOS) that you compile on your own Mac during install. Nothing is downloaded, which helps on managed Macs where installing third-party apps is restricted.
  • Windows: uses Microsoft Edge (already on every Windows PC) or Chrome through Playwright.
  • Linux: uses Google Chrome if installed, otherwise downloads Playwright's Chromium once.

Install

You need Python 3.9+. On macOS you also need the Swift compiler (Xcode or the Command Line Tools: xcode-select --install).

With pip (all systems)

pip install optima-ai-browser
optima setup

optima setup opens the first-run window (on macOS it compiles the native engine the first time). On Windows and Linux, if Playwright has no browser yet: python -m playwright install chromium.

Or run the MCP server without installing anything permanently: uvx optima-ai-browser mcp.

From source: macOS

git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
cd optima-ai-browser
sh install.sh

On macOS the installer also adds Optima AI Browser to ~/Applications. Double-click it to browse yourself, for example to log in to your sites: your assistant shares the same logins.

From source: Linux

git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
cd optima-ai-browser
sh install.sh

If Chromium complains about missing libraries: sudo ~/.optima/venv/bin/python -m playwright install-deps chromium.

From source: Windows (PowerShell)

git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
cd optima-ai-browser
powershell -ExecutionPolicy Bypass -File install.ps1

The installer copies Optima into ~/.optima, so you can move or delete the cloned folder. To update, git pull and run the installer again.

First run

The installer opens the Optima window:

  1. Choose your language. English, Italiano, Español, Français, Deutsch or Português. Banners and notifications use it; the agent always gets English.
  2. Connect your assistants. Optima detects Claude Code, the Claude Desktop app and Google Antigravity, installs its skill and registers its MCP server in each one you pick.
  3. Log in to your favourite sites in that same window, so your assistant finds you signed in.

Prefer the terminal? sh install.sh --cli (or install.ps1 --cli).

Then restart your assistant and try: "Use Optima to find the opening hours of the nearest library."

Where Optima connects

Assistant Skill MCP server
Claude Code ~/.claude/skills/optima/ user scope (claude mcp add-json)
Claude Desktop upload ~/.optima/optima-skill.zip in Settings → Capabilities → Skills claude_desktop_config.json
Google Antigravity ~/.gemini/config/skills/optima/ ~/.gemini/config/mcp_config.json

Connecting other MCP clients

Any MCP client can use Optima. If you installed it with pip:

{ "command": "optima", "args": ["mcp"] }

From source, use the launcher (no environment variables needed):

{
  "command": "/path/to/python",
  "args": ["~/.optima/app/src/optima_launcher.py", "mcp"]
}

On macOS /path/to/python is your python3; on Windows and Linux it is the one in ~/.optima/venv. Copy src/optima/skill/ into your assistant's skills folder if it supports Agent Skills.

Tools for the agent

Tool What it does
browser_open(url) Open a page, return it as clean text
browser_read(max_chars?) Read the current page again
browser_click(id, confirmed?) Click an element by its number
browser_type(id, text, submit?, confirmed?) Type into a field (never passwords or cards)
browser_select(id, value) Pick an option in a drop-down
browser_scroll(direction) down, up, top, bottom
browser_navigate(action) back, forward, reload
browser_screenshot() PNG of the page, when visuals matter
browser_ask_human(reason) Hand control to you and wait for Done
browser_wait(seconds) Wait for slow pages
browser_recent_actions(limit?) Today's audit log

The bundled skill (src/optima/skill/SKILL.md) only applies where Optima is turned on: if the browser_* tools are not available in a chat (for example you disabled the optima MCP server there), the assistant ignores the skill and uses its usual browser without mentioning Optima. Where Optima is on, it teaches the assistant when to use Optima (APIs and connectors first), how to act by element id, when to call you, and to always confirm purchases, messages and deletions with you.

Configuration

~/.optima/config.json (created on first run):

Key Default Meaning
language chosen on first run en, it, es, fr, de, pt
engine auto webkit (macOS), playwright
playwright_channel auto chrome, msedge, chromium
headless false Hide the window (Playwright only; hand-offs need a window)
identify_as_agent true Adds Optima/<version> (AI agent; +repo) to the user agent
dismiss_cookie_banners true Always the privacy-preserving choice
auto_handoff true Call you automatically when a human check appears
handoff_timeout_seconds 300 How long to wait for you
min_action_interval_ms 400 Gentle pace between actions
notify_desktop true System notification on hand-off
ntfy_topic "" Optional phone push via ntfy: set a private topic name and subscribe to it in the ntfy app
policies.confirm_before ["purchase","send","delete"] Actions the agent must confirm with you
policies.block [] Actions never allowed (same categories, plus submit)
policies.human_only_fields true Password and payment fields are yours only

Data lives in ~/.optima/: config.json, logs/ (one JSON-lines file per day) and, for Playwright, profile/. The macOS engine keeps cookies in the system WebKit store for the app.

Commands

python3 -m optima setup            # first-run window again (add --cli for terminal)
python3 -m optima open example.com # open Optima yourself, e.g. to log in
python3 -m optima doctor           # check the installation
python3 -m optima mcp              # the MCP server (started by assistants)

Run them with PYTHONPATH=~/.optima/app/src (or from the repo's src folder).

Principles

  • Humans decide. CAPTCHAs, logins, passwords, payments and one-time codes are always done by you.
  • Honest. Optima identifies itself as an AI agent and paces its requests.
  • Private. No telemetry. Cookie banners get "reject". Nothing leaves your machine except the pages you visit and, if you set one, your ntfy notification.
  • Accountable. Every action is logged locally.

Roadmap

  • Web Bot Auth signed requests, so sites that welcome verified agents can let Optima in without a check
  • Multiple tabs and downloads
  • Per-site rules (e.g. read-only on banking sites)
  • Packaged releases

Contributing

Issues and pull requests are welcome. Keep the principles above: features that help an agent evade CAPTCHAs, fingerprinting or bot detection won't be merged.

How it was made

Optima was designed by @ascaniolocorotondo and written largely with the help of Claude (Anthropic's AI assistant), then tested on macOS, Windows and Linux in CI.

License

MIT

Metadata

Release files for optima-ai-browser 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for optima-ai-browser 0.2.0
File Size Uploaded Provenance Actions
optima_ai_browser-0.2.0.tar.gz 717.2 kB With provenance Details for optima_ai_browser-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for optima-ai-browser 0.2.0
File Interpreter ABI Platform Actions
optima_ai_browser-0.2.0-py3-none-any.whl Python 3 none any Details for optima_ai_browser-0.2.0-py3-none-any.whl

Total release size: 1.4 MB

Release files / optima_ai_browser-0.2.0.tar.gz

Download URL optima_ai_browser-0.2.0.tar.gz
Size 717.2 kB
Tags Source
SHA-256 checksum
How to use checksums
6e9e1ce54aa5deeeace330bfbcd60564ad3463a3d89d4c2d3e5333821bf4da73
BLAKE2b-256 checksum
How to use checksums
0a2b2f876a8fd3dc175f2c4d5c12670c303ed1455e0ac4237d5be9b3a0d67815
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / optima_ai_browser-0.2.0-py3-none-any.whl

Download URL optima_ai_browser-0.2.0-py3-none-any.whl
Size 713.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
06a1f97a610353be003ff27350e72662b78b15e20428697ebca4a10c76bf01ab
BLAKE2b-256 checksum
How to use checksums
992c36362bfec9df73931fc1cf620a86306b08f85526d18fe92f97ed72dcf891
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for optima-ai-browser 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for optima_ai_browser-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page