optima-ai-browser 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. optima_ai_browser-0.2.0/LICENSE +21 -0
  2. optima_ai_browser-0.2.0/PKG-INFO +264 -0
  3. optima_ai_browser-0.2.0/README.md +237 -0
  4. optima_ai_browser-0.2.0/pyproject.toml +46 -0
  5. optima_ai_browser-0.2.0/setup.cfg +4 -0
  6. optima_ai_browser-0.2.0/src/optima/__init__.py +2 -0
  7. optima_ai_browser-0.2.0/src/optima/__main__.py +82 -0
  8. optima_ai_browser-0.2.0/src/optima/assets/icon-256.png +0 -0
  9. optima_ai_browser-0.2.0/src/optima/brand.py +10 -0
  10. optima_ai_browser-0.2.0/src/optima/browser.py +287 -0
  11. optima_ai_browser-0.2.0/src/optima/config.py +99 -0
  12. optima_ai_browser-0.2.0/src/optima/engines.py +348 -0
  13. optima_ai_browser-0.2.0/src/optima/i18n.py +214 -0
  14. optima_ai_browser-0.2.0/src/optima/macos/AppIcon.icns +0 -0
  15. optima_ai_browser-0.2.0/src/optima/macos/Info.plist +31 -0
  16. optima_ai_browser-0.2.0/src/optima/macos/build.sh +26 -0
  17. optima_ai_browser-0.2.0/src/optima/macos/main.swift +493 -0
  18. optima_ai_browser-0.2.0/src/optima/mcp_server.py +157 -0
  19. optima_ai_browser-0.2.0/src/optima/notify.py +53 -0
  20. optima_ai_browser-0.2.0/src/optima/page_script.js +324 -0
  21. optima_ai_browser-0.2.0/src/optima/setup.py +257 -0
  22. optima_ai_browser-0.2.0/src/optima/skill/SKILL.md +69 -0
  23. optima_ai_browser-0.2.0/src/optima/welcome.html +151 -0
  24. optima_ai_browser-0.2.0/src/optima_ai_browser.egg-info/PKG-INFO +264 -0
  25. optima_ai_browser-0.2.0/src/optima_ai_browser.egg-info/SOURCES.txt +27 -0
  26. optima_ai_browser-0.2.0/src/optima_ai_browser.egg-info/dependency_links.txt +1 -0
  27. optima_ai_browser-0.2.0/src/optima_ai_browser.egg-info/entry_points.txt +3 -0
  28. optima_ai_browser-0.2.0/src/optima_ai_browser.egg-info/requires.txt +6 -0
  29. optima_ai_browser-0.2.0/src/optima_ai_browser.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Optima AI Browser contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,264 @@
1
+ Metadata-Version: 2.4
2
+ Name: optima-ai-browser
3
+ Version: 0.2.0
4
+ Summary: A browser built for AI assistants: clean page text for the agent, a human hand-off for CAPTCHAs, logins and payments. MCP server + Agent Skill.
5
+ Author: ascaniolocorotondo
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ascaniolocorotondo/optima-ai-browser
8
+ Project-URL: Issues, https://github.com/ascaniolocorotondo/optima-ai-browser/issues
9
+ Project-URL: Glama, https://glama.ai/mcp/servers/ascaniolocorotondo/optima-ai-browser
10
+ Keywords: mcp,mcp-server,model-context-protocol,ai-agents,browser,browser-automation,claude,agent-skills
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: MacOS X
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: Microsoft :: Windows
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: playwright>=1.45; sys_platform != "darwin"
24
+ Provides-Extra: playwright
25
+ Requires-Dist: playwright>=1.45; extra == "playwright"
26
+ Dynamic: license-file
27
+
28
+ <p align="center">
29
+ <img src="https://raw.githubusercontent.com/ascaniolocorotondo/optima-ai-browser/main/assets/logo.png" alt="Optima AI Browser" width="320">
30
+ </p>
31
+
32
+ <p align="center">
33
+ <b>A browser built for AI assistants.</b><br>
34
+ Clean pages for the agent, a quick tap for the human when it matters.
35
+ </p>
36
+
37
+ <p align="center">
38
+ <a href="https://github.com/ascaniolocorotondo/optima-ai-browser/actions/workflows/test.yml"><img src="https://github.com/ascaniolocorotondo/optima-ai-browser/actions/workflows/test.yml/badge.svg" alt="tests"></a>
39
+ <a href="https://glama.ai/mcp/servers/ascaniolocorotondo/optima-ai-browser"><img src="https://glama.ai/mcp/servers/ascaniolocorotondo/optima-ai-browser/badges/score.svg" alt="Glama score"></a><br>
40
+ macOS · Windows · Linux &nbsp;|&nbsp; MCP server + Claude skill &nbsp;|&nbsp; MIT
41
+ </p>
42
+
43
+ ---
44
+
45
+ ## Why Optima?
46
+
47
+ Ordinary browsers are made for human eyes. When an AI assistant drives one, it wastes time and
48
+ tokens on ads, pop-ups and cookie walls, loses its logins, and stalls without saying anything
49
+ the moment a site asks for a human.
50
+
51
+ Optima fixes the *agent* side of browsing, and keeps a person in the loop for the parts that
52
+ need one:
53
+
54
+ | | Ordinary browser + AI | Optima |
55
+ |---|---|---|
56
+ | What the agent sees | Raw HTML or screenshots | Clean text with numbered elements: `[12 button] Sign in` |
57
+ | Cookie banners | The agent clicks around them | Declined automatically ("reject" / "only necessary") |
58
+ | Logins | Lost between sessions | Persistent profile: log in once |
59
+ | CAPTCHA / "checking your browser" | Agent gets stuck | Detected → you get a notification → you solve it → the agent continues |
60
+ | Passwords & cards | Risky | Always typed by you; the agent is refused these fields |
61
+ | Buying, posting, deleting | Happens silently | Agent must ask you in chat first |
62
+ | What happened? | Unknown | Daily audit log |
63
+
64
+ > **Optima does not solve or bypass CAPTCHAs or bot protection, by design.** Those checks are
65
+ > how sites decide who gets in. Optima makes the hand-off to you take seconds instead.
66
+
67
+ ## How it works
68
+
69
+ ```
70
+ AI assistant ──MCP──▶ Optima server (Python) ──▶ engine ──▶ the web
71
+ (Claude…) reading, rules, macOS: native app on system WebKit
72
+ hand-off, log Windows/Linux: Edge/Chrome via Playwright
73
+ │
74
+ └──▶ you: notification + "Your turn" banner + Done button
75
+ ```
76
+
77
+ - **macOS:** a tiny native app (Swift + the WebKit that ships with macOS) that **you compile on
78
+ your own Mac** during install. Nothing is downloaded, which helps on managed Macs where
79
+ installing third-party apps is restricted.
80
+ - **Windows:** uses Microsoft Edge (already on every Windows PC) or Chrome through Playwright.
81
+ - **Linux:** uses Google Chrome if installed, otherwise downloads Playwright's Chromium once.
82
+
83
+ ## Install
84
+
85
+ You need **Python 3.9+**. On macOS you also need the Swift compiler (Xcode or the Command Line
86
+ Tools: `xcode-select --install`).
87
+
88
+ ### With pip (all systems)
89
+
90
+ ```bash
91
+ pip install optima-ai-browser
92
+ optima setup
93
+ ```
94
+
95
+ `optima setup` opens the first-run window (on macOS it compiles the native engine the first time).
96
+ On Windows and Linux, if Playwright has no browser yet: `python -m playwright install chromium`.
97
+
98
+ Or run the MCP server without installing anything permanently: `uvx optima-ai-browser mcp`.
99
+
100
+ ### From source: macOS
101
+
102
+ ```bash
103
+ git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
104
+ cd optima-ai-browser
105
+ sh install.sh
106
+ ```
107
+
108
+ On macOS the installer also adds **Optima AI Browser** to `~/Applications`. Double-click it to
109
+ browse yourself, for example to log in to your sites: your assistant shares the same logins.
110
+
111
+ ### From source: Linux
112
+
113
+ ```bash
114
+ git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
115
+ cd optima-ai-browser
116
+ sh install.sh
117
+ ```
118
+
119
+ If Chromium complains about missing libraries: `sudo ~/.optima/venv/bin/python -m playwright install-deps chromium`.
120
+
121
+ ### From source: Windows (PowerShell)
122
+
123
+ ```powershell
124
+ git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
125
+ cd optima-ai-browser
126
+ powershell -ExecutionPolicy Bypass -File install.ps1
127
+ ```
128
+
129
+ > The installer copies Optima into `~/.optima`, so you can move or delete the cloned folder.
130
+ > To update, `git pull` and run the installer again.
131
+
132
+ ## First run
133
+
134
+ The installer opens the Optima window:
135
+
136
+ 1. **Choose your language.** English, Italiano, Español, Français, Deutsch or Português.
137
+ Banners and notifications use it; the agent always gets English.
138
+ 2. **Connect your assistants.** Optima detects **Claude Code**, the **Claude Desktop** app and
139
+ **Google Antigravity**, installs its skill and registers its MCP server in each one you pick.
140
+ 3. **Log in to your favourite sites** in that same window, so your assistant finds you signed in.
141
+
142
+ Prefer the terminal? `sh install.sh --cli` (or `install.ps1 --cli`).
143
+
144
+ Then restart your assistant and try: *"Use Optima to find the opening hours of the nearest
145
+ library."*
146
+
147
+ ### Where Optima connects
148
+
149
+ | Assistant | Skill | MCP server |
150
+ |---|---|---|
151
+ | Claude Code | `~/.claude/skills/optima/` | user scope (`claude mcp add-json`) |
152
+ | Claude Desktop | upload `~/.optima/optima-skill.zip` in Settings → Capabilities → Skills | `claude_desktop_config.json` |
153
+ | Google Antigravity | `~/.gemini/config/skills/optima/` | `~/.gemini/config/mcp_config.json` |
154
+
155
+ ### Connecting other MCP clients
156
+
157
+ Any MCP client can use Optima. If you installed it with pip:
158
+
159
+ ```json
160
+ { "command": "optima", "args": ["mcp"] }
161
+ ```
162
+
163
+ From source, use the launcher (no environment variables needed):
164
+
165
+ ```json
166
+ {
167
+ "command": "/path/to/python",
168
+ "args": ["~/.optima/app/src/optima_launcher.py", "mcp"]
169
+ }
170
+ ```
171
+
172
+ On macOS `/path/to/python` is your `python3`; on Windows and Linux it is the one in
173
+ `~/.optima/venv`. Copy `src/optima/skill/` into your assistant's skills folder if it supports
174
+ [Agent Skills](https://agentskills.io).
175
+
176
+ ## Tools for the agent
177
+
178
+ | Tool | What it does |
179
+ |---|---|
180
+ | `browser_open(url)` | Open a page, return it as clean text |
181
+ | `browser_read(max_chars?)` | Read the current page again |
182
+ | `browser_click(id, confirmed?)` | Click an element by its number |
183
+ | `browser_type(id, text, submit?, confirmed?)` | Type into a field (never passwords or cards) |
184
+ | `browser_select(id, value)` | Pick an option in a drop-down |
185
+ | `browser_scroll(direction)` | `down`, `up`, `top`, `bottom` |
186
+ | `browser_navigate(action)` | `back`, `forward`, `reload` |
187
+ | `browser_screenshot()` | PNG of the page, when visuals matter |
188
+ | `browser_ask_human(reason)` | Hand control to you and wait for **Done** |
189
+ | `browser_wait(seconds)` | Wait for slow pages |
190
+ | `browser_recent_actions(limit?)` | Today's audit log |
191
+
192
+ The bundled **skill** (`src/optima/skill/SKILL.md`) only applies where Optima is turned on: if the
193
+ `browser_*` tools are not available in a chat (for example you disabled the `optima` MCP server
194
+ there), the assistant ignores the skill and uses its usual browser without mentioning Optima.
195
+ Where Optima is on, it teaches the assistant when to use Optima (APIs and
196
+ connectors first), how to act by element id, when to call you, and to always confirm purchases,
197
+ messages and deletions with you.
198
+
199
+ ## Configuration
200
+
201
+ `~/.optima/config.json` (created on first run):
202
+
203
+ | Key | Default | Meaning |
204
+ |---|---|---|
205
+ | `language` | chosen on first run | `en`, `it`, `es`, `fr`, `de`, `pt` |
206
+ | `engine` | `auto` | `webkit` (macOS), `playwright` |
207
+ | `playwright_channel` | `auto` | `chrome`, `msedge`, `chromium` |
208
+ | `headless` | `false` | Hide the window (Playwright only; hand-offs need a window) |
209
+ | `identify_as_agent` | `true` | Adds `Optima/<version> (AI agent; +repo)` to the user agent |
210
+ | `dismiss_cookie_banners` | `true` | Always the privacy-preserving choice |
211
+ | `auto_handoff` | `true` | Call you automatically when a human check appears |
212
+ | `handoff_timeout_seconds` | `300` | How long to wait for you |
213
+ | `min_action_interval_ms` | `400` | Gentle pace between actions |
214
+ | `notify_desktop` | `true` | System notification on hand-off |
215
+ | `ntfy_topic` | `""` | Optional phone push via [ntfy](https://ntfy.sh): set a private topic name and subscribe to it in the ntfy app |
216
+ | `policies.confirm_before` | `["purchase","send","delete"]` | Actions the agent must confirm with you |
217
+ | `policies.block` | `[]` | Actions never allowed (same categories, plus `submit`) |
218
+ | `policies.human_only_fields` | `true` | Password and payment fields are yours only |
219
+
220
+ Data lives in `~/.optima/`: `config.json`, `logs/` (one JSON-lines file per day) and, for
221
+ Playwright, `profile/`. The macOS engine keeps cookies in the system WebKit store for the app.
222
+
223
+ ## Commands
224
+
225
+ ```bash
226
+ python3 -m optima setup # first-run window again (add --cli for terminal)
227
+ python3 -m optima open example.com # open Optima yourself, e.g. to log in
228
+ python3 -m optima doctor # check the installation
229
+ python3 -m optima mcp # the MCP server (started by assistants)
230
+ ```
231
+
232
+ Run them with `PYTHONPATH=~/.optima/app/src` (or from the repo's `src` folder).
233
+
234
+ ## Principles
235
+
236
+ - **Humans decide.** CAPTCHAs, logins, passwords, payments and one-time codes are always done by you.
237
+ - **Honest.** Optima identifies itself as an AI agent and paces its requests.
238
+ - **Private.** No telemetry. Cookie banners get "reject". Nothing leaves your machine except the
239
+ pages you visit and, if you set one, your ntfy notification.
240
+ - **Accountable.** Every action is logged locally.
241
+
242
+ ## Roadmap
243
+
244
+ - [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) signed requests, so sites that welcome verified agents can let Optima in without a check
245
+ - Multiple tabs and downloads
246
+ - Per-site rules (e.g. read-only on banking sites)
247
+ - Packaged releases
248
+
249
+ ## Contributing
250
+
251
+ Issues and pull requests are welcome. Keep the principles above: features that help an agent
252
+ evade CAPTCHAs, fingerprinting or bot detection won't be merged.
253
+
254
+ ## How it was made
255
+
256
+ Optima was designed by [@ascaniolocorotondo](https://github.com/ascaniolocorotondo) and written
257
+ largely with the help of [Claude](https://claude.com) (Anthropic's AI assistant), then tested on
258
+ macOS, Windows and Linux in CI.
259
+
260
+ ## License
261
+
262
+ [MIT](LICENSE)
263
+
264
+ <!-- mcp-name: io.github.ascaniolocorotondo/optima-ai-browser -->
@@ -0,0 +1,237 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/ascaniolocorotondo/optima-ai-browser/main/assets/logo.png" alt="Optima AI Browser" width="320">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <b>A browser built for AI assistants.</b><br>
7
+ Clean pages for the agent, a quick tap for the human when it matters.
8
+ </p>
9
+
10
+ <p align="center">
11
+ <a href="https://github.com/ascaniolocorotondo/optima-ai-browser/actions/workflows/test.yml"><img src="https://github.com/ascaniolocorotondo/optima-ai-browser/actions/workflows/test.yml/badge.svg" alt="tests"></a>
12
+ <a href="https://glama.ai/mcp/servers/ascaniolocorotondo/optima-ai-browser"><img src="https://glama.ai/mcp/servers/ascaniolocorotondo/optima-ai-browser/badges/score.svg" alt="Glama score"></a><br>
13
+ macOS · Windows · Linux &nbsp;|&nbsp; MCP server + Claude skill &nbsp;|&nbsp; MIT
14
+ </p>
15
+
16
+ ---
17
+
18
+ ## Why Optima?
19
+
20
+ Ordinary browsers are made for human eyes. When an AI assistant drives one, it wastes time and
21
+ tokens on ads, pop-ups and cookie walls, loses its logins, and stalls without saying anything
22
+ the moment a site asks for a human.
23
+
24
+ Optima fixes the *agent* side of browsing, and keeps a person in the loop for the parts that
25
+ need one:
26
+
27
+ | | Ordinary browser + AI | Optima |
28
+ |---|---|---|
29
+ | What the agent sees | Raw HTML or screenshots | Clean text with numbered elements: `[12 button] Sign in` |
30
+ | Cookie banners | The agent clicks around them | Declined automatically ("reject" / "only necessary") |
31
+ | Logins | Lost between sessions | Persistent profile: log in once |
32
+ | CAPTCHA / "checking your browser" | Agent gets stuck | Detected → you get a notification → you solve it → the agent continues |
33
+ | Passwords & cards | Risky | Always typed by you; the agent is refused these fields |
34
+ | Buying, posting, deleting | Happens silently | Agent must ask you in chat first |
35
+ | What happened? | Unknown | Daily audit log |
36
+
37
+ > **Optima does not solve or bypass CAPTCHAs or bot protection, by design.** Those checks are
38
+ > how sites decide who gets in. Optima makes the hand-off to you take seconds instead.
39
+
40
+ ## How it works
41
+
42
+ ```
43
+ AI assistant ──MCP──▶ Optima server (Python) ──▶ engine ──▶ the web
44
+ (Claude…) reading, rules, macOS: native app on system WebKit
45
+ hand-off, log Windows/Linux: Edge/Chrome via Playwright
46
+ │
47
+ └──▶ you: notification + "Your turn" banner + Done button
48
+ ```
49
+
50
+ - **macOS:** a tiny native app (Swift + the WebKit that ships with macOS) that **you compile on
51
+ your own Mac** during install. Nothing is downloaded, which helps on managed Macs where
52
+ installing third-party apps is restricted.
53
+ - **Windows:** uses Microsoft Edge (already on every Windows PC) or Chrome through Playwright.
54
+ - **Linux:** uses Google Chrome if installed, otherwise downloads Playwright's Chromium once.
55
+
56
+ ## Install
57
+
58
+ You need **Python 3.9+**. On macOS you also need the Swift compiler (Xcode or the Command Line
59
+ Tools: `xcode-select --install`).
60
+
61
+ ### With pip (all systems)
62
+
63
+ ```bash
64
+ pip install optima-ai-browser
65
+ optima setup
66
+ ```
67
+
68
+ `optima setup` opens the first-run window (on macOS it compiles the native engine the first time).
69
+ On Windows and Linux, if Playwright has no browser yet: `python -m playwright install chromium`.
70
+
71
+ Or run the MCP server without installing anything permanently: `uvx optima-ai-browser mcp`.
72
+
73
+ ### From source: macOS
74
+
75
+ ```bash
76
+ git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
77
+ cd optima-ai-browser
78
+ sh install.sh
79
+ ```
80
+
81
+ On macOS the installer also adds **Optima AI Browser** to `~/Applications`. Double-click it to
82
+ browse yourself, for example to log in to your sites: your assistant shares the same logins.
83
+
84
+ ### From source: Linux
85
+
86
+ ```bash
87
+ git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
88
+ cd optima-ai-browser
89
+ sh install.sh
90
+ ```
91
+
92
+ If Chromium complains about missing libraries: `sudo ~/.optima/venv/bin/python -m playwright install-deps chromium`.
93
+
94
+ ### From source: Windows (PowerShell)
95
+
96
+ ```powershell
97
+ git clone https://github.com/ascaniolocorotondo/optima-ai-browser.git
98
+ cd optima-ai-browser
99
+ powershell -ExecutionPolicy Bypass -File install.ps1
100
+ ```
101
+
102
+ > The installer copies Optima into `~/.optima`, so you can move or delete the cloned folder.
103
+ > To update, `git pull` and run the installer again.
104
+
105
+ ## First run
106
+
107
+ The installer opens the Optima window:
108
+
109
+ 1. **Choose your language.** English, Italiano, Español, Français, Deutsch or Português.
110
+ Banners and notifications use it; the agent always gets English.
111
+ 2. **Connect your assistants.** Optima detects **Claude Code**, the **Claude Desktop** app and
112
+ **Google Antigravity**, installs its skill and registers its MCP server in each one you pick.
113
+ 3. **Log in to your favourite sites** in that same window, so your assistant finds you signed in.
114
+
115
+ Prefer the terminal? `sh install.sh --cli` (or `install.ps1 --cli`).
116
+
117
+ Then restart your assistant and try: *"Use Optima to find the opening hours of the nearest
118
+ library."*
119
+
120
+ ### Where Optima connects
121
+
122
+ | Assistant | Skill | MCP server |
123
+ |---|---|---|
124
+ | Claude Code | `~/.claude/skills/optima/` | user scope (`claude mcp add-json`) |
125
+ | Claude Desktop | upload `~/.optima/optima-skill.zip` in Settings → Capabilities → Skills | `claude_desktop_config.json` |
126
+ | Google Antigravity | `~/.gemini/config/skills/optima/` | `~/.gemini/config/mcp_config.json` |
127
+
128
+ ### Connecting other MCP clients
129
+
130
+ Any MCP client can use Optima. If you installed it with pip:
131
+
132
+ ```json
133
+ { "command": "optima", "args": ["mcp"] }
134
+ ```
135
+
136
+ From source, use the launcher (no environment variables needed):
137
+
138
+ ```json
139
+ {
140
+ "command": "/path/to/python",
141
+ "args": ["~/.optima/app/src/optima_launcher.py", "mcp"]
142
+ }
143
+ ```
144
+
145
+ On macOS `/path/to/python` is your `python3`; on Windows and Linux it is the one in
146
+ `~/.optima/venv`. Copy `src/optima/skill/` into your assistant's skills folder if it supports
147
+ [Agent Skills](https://agentskills.io).
148
+
149
+ ## Tools for the agent
150
+
151
+ | Tool | What it does |
152
+ |---|---|
153
+ | `browser_open(url)` | Open a page, return it as clean text |
154
+ | `browser_read(max_chars?)` | Read the current page again |
155
+ | `browser_click(id, confirmed?)` | Click an element by its number |
156
+ | `browser_type(id, text, submit?, confirmed?)` | Type into a field (never passwords or cards) |
157
+ | `browser_select(id, value)` | Pick an option in a drop-down |
158
+ | `browser_scroll(direction)` | `down`, `up`, `top`, `bottom` |
159
+ | `browser_navigate(action)` | `back`, `forward`, `reload` |
160
+ | `browser_screenshot()` | PNG of the page, when visuals matter |
161
+ | `browser_ask_human(reason)` | Hand control to you and wait for **Done** |
162
+ | `browser_wait(seconds)` | Wait for slow pages |
163
+ | `browser_recent_actions(limit?)` | Today's audit log |
164
+
165
+ The bundled **skill** (`src/optima/skill/SKILL.md`) only applies where Optima is turned on: if the
166
+ `browser_*` tools are not available in a chat (for example you disabled the `optima` MCP server
167
+ there), the assistant ignores the skill and uses its usual browser without mentioning Optima.
168
+ Where Optima is on, it teaches the assistant when to use Optima (APIs and
169
+ connectors first), how to act by element id, when to call you, and to always confirm purchases,
170
+ messages and deletions with you.
171
+
172
+ ## Configuration
173
+
174
+ `~/.optima/config.json` (created on first run):
175
+
176
+ | Key | Default | Meaning |
177
+ |---|---|---|
178
+ | `language` | chosen on first run | `en`, `it`, `es`, `fr`, `de`, `pt` |
179
+ | `engine` | `auto` | `webkit` (macOS), `playwright` |
180
+ | `playwright_channel` | `auto` | `chrome`, `msedge`, `chromium` |
181
+ | `headless` | `false` | Hide the window (Playwright only; hand-offs need a window) |
182
+ | `identify_as_agent` | `true` | Adds `Optima/<version> (AI agent; +repo)` to the user agent |
183
+ | `dismiss_cookie_banners` | `true` | Always the privacy-preserving choice |
184
+ | `auto_handoff` | `true` | Call you automatically when a human check appears |
185
+ | `handoff_timeout_seconds` | `300` | How long to wait for you |
186
+ | `min_action_interval_ms` | `400` | Gentle pace between actions |
187
+ | `notify_desktop` | `true` | System notification on hand-off |
188
+ | `ntfy_topic` | `""` | Optional phone push via [ntfy](https://ntfy.sh): set a private topic name and subscribe to it in the ntfy app |
189
+ | `policies.confirm_before` | `["purchase","send","delete"]` | Actions the agent must confirm with you |
190
+ | `policies.block` | `[]` | Actions never allowed (same categories, plus `submit`) |
191
+ | `policies.human_only_fields` | `true` | Password and payment fields are yours only |
192
+
193
+ Data lives in `~/.optima/`: `config.json`, `logs/` (one JSON-lines file per day) and, for
194
+ Playwright, `profile/`. The macOS engine keeps cookies in the system WebKit store for the app.
195
+
196
+ ## Commands
197
+
198
+ ```bash
199
+ python3 -m optima setup # first-run window again (add --cli for terminal)
200
+ python3 -m optima open example.com # open Optima yourself, e.g. to log in
201
+ python3 -m optima doctor # check the installation
202
+ python3 -m optima mcp # the MCP server (started by assistants)
203
+ ```
204
+
205
+ Run them with `PYTHONPATH=~/.optima/app/src` (or from the repo's `src` folder).
206
+
207
+ ## Principles
208
+
209
+ - **Humans decide.** CAPTCHAs, logins, passwords, payments and one-time codes are always done by you.
210
+ - **Honest.** Optima identifies itself as an AI agent and paces its requests.
211
+ - **Private.** No telemetry. Cookie banners get "reject". Nothing leaves your machine except the
212
+ pages you visit and, if you set one, your ntfy notification.
213
+ - **Accountable.** Every action is logged locally.
214
+
215
+ ## Roadmap
216
+
217
+ - [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) signed requests, so sites that welcome verified agents can let Optima in without a check
218
+ - Multiple tabs and downloads
219
+ - Per-site rules (e.g. read-only on banking sites)
220
+ - Packaged releases
221
+
222
+ ## Contributing
223
+
224
+ Issues and pull requests are welcome. Keep the principles above: features that help an agent
225
+ evade CAPTCHAs, fingerprinting or bot detection won't be merged.
226
+
227
+ ## How it was made
228
+
229
+ Optima was designed by [@ascaniolocorotondo](https://github.com/ascaniolocorotondo) and written
230
+ largely with the help of [Claude](https://claude.com) (Anthropic's AI assistant), then tested on
231
+ macOS, Windows and Linux in CI.
232
+
233
+ ## License
234
+
235
+ [MIT](LICENSE)
236
+
237
+ <!-- mcp-name: io.github.ascaniolocorotondo/optima-ai-browser -->
@@ -0,0 +1,46 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "optima-ai-browser"
7
+ version = "0.2.0"
8
+ description = "A browser built for AI assistants: clean page text for the agent, a human hand-off for CAPTCHAs, logins and payments. MCP server + Agent Skill."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [{ name = "ascaniolocorotondo" }]
14
+ keywords = ["mcp", "mcp-server", "model-context-protocol", "ai-agents", "browser", "browser-automation", "claude", "agent-skills"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Environment :: MacOS X",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: MacOS",
20
+ "Operating System :: Microsoft :: Windows",
21
+ "Operating System :: POSIX :: Linux",
22
+ "Programming Language :: Python :: 3",
23
+ "Topic :: Internet :: WWW/HTTP :: Browsers",
24
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
25
+ ]
26
+ # macOS uses the native WebKit engine (standard library only); Windows and Linux use Playwright.
27
+ dependencies = ["playwright>=1.45; sys_platform != 'darwin'"]
28
+
29
+ [project.optional-dependencies]
30
+ playwright = ["playwright>=1.45"]
31
+
32
+ [project.scripts]
33
+ optima = "optima.__main__:main"
34
+ optima-ai-browser = "optima.__main__:main" # lets `uvx optima-ai-browser mcp` work
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/ascaniolocorotondo/optima-ai-browser"
38
+ Issues = "https://github.com/ascaniolocorotondo/optima-ai-browser/issues"
39
+ Glama = "https://glama.ai/mcp/servers/ascaniolocorotondo/optima-ai-browser"
40
+
41
+ [tool.setuptools]
42
+ package-dir = { "" = "src" }
43
+ packages = ["optima"]
44
+
45
+ [tool.setuptools.package-data]
46
+ optima = ["*.js", "*.html", "assets/*", "skill/*", "macos/*.swift", "macos/*.plist", "macos/*.sh", "macos/*.icns"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,2 @@
1
+ """Optima: a browser built for AI agents."""
2
+ __version__ = "0.2.0"
@@ -0,0 +1,82 @@
1
+ """Command line: python -m optima <command>
2
+
3
+ setup first run: language, skill, connect assistants (add --cli for terminal only)
4
+ mcp run the MCP server (what assistants start)
5
+ open URL open the browser yourself, e.g. to log in to your sites
6
+ doctor check the installation
7
+ build-engine compile the native macOS engine (macOS only)
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import sys
13
+ import time
14
+
15
+ from . import __version__, brand, config
16
+
17
+
18
+ def doctor() -> None:
19
+ cfg = config.load()
20
+ engine = config.resolve_engine(cfg)
21
+ print(f"{brand.FULL_NAME} {__version__}")
22
+ print(f" python: {sys.executable} ({sys.version.split()[0]})")
23
+ print(f" config: {config.CONFIG_FILE} ({'found' if config.CONFIG_FILE.exists() else 'missing: run setup'})")
24
+ print(f" language: {cfg.get('language') or '(not chosen yet)'}")
25
+ print(f" engine: {engine}")
26
+ if engine == "webkit":
27
+ app = config.webkit_app_path()
28
+ print(f" app: {app} ({'ok' if app.exists() else 'missing: run optima build-engine'})")
29
+ else:
30
+ try:
31
+ import playwright # noqa: F401
32
+ print(" playwright: ok")
33
+ except ImportError:
34
+ print(" playwright: missing (pip install playwright)")
35
+ from .setup import desktop_config_path, find_claude_cli
36
+ print(f" claude cli: {find_claude_cli() or 'not found'}")
37
+ p = desktop_config_path()
38
+ registered = False
39
+ if p.exists():
40
+ try:
41
+ registered = brand.SLUG in json.loads(p.read_text("utf-8")).get("mcpServers", {})
42
+ except ValueError:
43
+ pass
44
+ print(f" claude desktop: {'registered' if registered else 'not registered'}")
45
+
46
+
47
+ def open_url(url: str) -> None:
48
+ from .browser import Browser
49
+ b = Browser()
50
+ print(b.open(url).split("\n\n", 1)[0])
51
+ print("Close the window when you are done.")
52
+ try:
53
+ while b.engine and b.engine.alive():
54
+ time.sleep(1)
55
+ except KeyboardInterrupt:
56
+ pass
57
+ b.close()
58
+
59
+
60
+ def main() -> None:
61
+ args = sys.argv[1:]
62
+ cmd = args[0] if args else "help"
63
+ if cmd == "mcp":
64
+ from .mcp_server import main as run
65
+ run()
66
+ elif cmd == "setup":
67
+ from .setup import main as run_setup
68
+ run_setup(args[1:])
69
+ elif cmd == "open" and len(args) > 1:
70
+ open_url(args[1])
71
+ elif cmd == "doctor":
72
+ doctor()
73
+ elif cmd == "build-engine":
74
+ print(config.build_macos_engine())
75
+ elif cmd in ("-v", "--version", "version"):
76
+ print(__version__)
77
+ else:
78
+ print(__doc__)
79
+
80
+
81
+ if __name__ == "__main__":
82
+ main()
@@ -0,0 +1,10 @@
1
+ """Every user-visible name lives here. scripts/rename.py rewrites it for you."""
2
+ NAME = "Optima"
3
+ FULL_NAME = "Optima AI Browser"
4
+ SLUG = "optima"
5
+ REPO_URL = "https://github.com/ascaniolocorotondo/optima-ai-browser"
6
+
7
+
8
+ def ua_suffix(version: str) -> str:
9
+ # Honest identification: sites can see this is an AI agent.
10
+ return f"{NAME}/{version} (AI agent; +{REPO_URL})"