evoui-browser

Evoui Browser is an optional Agent Skill for agent-browser. Run a browser task normally once; on later, similar tasks, Evoui can reuse verified navigation and mechanical steps so the agent spends less time exploring and repeating work. The host agent still chooses targets, interprets results, and decides what to do next. The currently supported hosts are Codex, Claude Code, and Cursor.

[!WARNING] Evoui Browser is experimental. Start with non-critical tasks on non-sensitive websites.

See the difference

The first run explores the site step by step. On the next run, Evoui reuses the matching navigation and review routine while the agent still decides which invoices need attention. That avoids rediscovering the same invoice page and controls on every run.

Evoui does not promise that every task will be faster. It helps when a site and task contain repeatable work that can be verified. A first run may take the same amount of work—or more—because it also gathers evidence for possible reuse.

Quick start

Requirements: macOS or Linux, Python 3.10 or newer, and Node.js 24 or newer with npm. Evoui adds no third-party Python packages. Windows is not currently supported because Evoui uses POSIX fcntl.

Install the Skill and its pinned browser runtime:

npx skills add Salmonbird/evoui-browser --skill evoui-browser -g
npm install -g agent-browser@0.33.1
agent-browser install

On Linux, use agent-browser install --with-deps if browser libraries are missing. The skills CLI may ask which detected agents should receive the Skill; choose the Codex, Claude Code, or Cursor hosts you use, then start a new agent session. Some compatible agents share the CLI's global Skill directory, so Evoui may also appear in other detected agents; only the three hosts named above are supported.

[!NOTE] The third-party skills CLI collects anonymous usage telemetry for confirmed public skills. Set DISABLE_TELEMETRY=1 before the npx command to opt out.

Then give the agent a concrete website and goal:

Use $evoui-browser to open <website> and complete <task>.   # Codex
Use /evoui-browser to open <website> and complete <task>.   # Claude Code / Cursor

Prefer assisted setup? Send your agent this prompt:

Install Evoui Browser from https://github.com/Salmonbird/evoui-browser.
Use the README's Quick start, make it available to the supported host I am using,
keep agent-browser pinned to 0.33.1, and tell me when I can start a new session
and invoke the Skill.

How it helps

1. Run normally. The agent completes the task with agent-browser while Evoui records evidence from the managed calls.
2. Learn selectively. Evoui keeps only navigation or routines with a clear future use and enough evidence. A successful task does not have to produce knowledge.
3. Reuse when the page still matches. On a later task, Evoui verifies fresh page state and reuses only the applicable mechanical steps.

Safety boundaries

• Evoui replays mechanical browser work, not business judgment.
• A page mismatch, missing target, failed postcondition, or unknown outcome returns control to the agent.
• A click, submission, or other mutation that may already have taken effect is not blindly retried.
• Login, CAPTCHA, permission, and confirmation steps pause for you in the same visible browser window.
• One-off tasks and operations with a reliable API or dedicated connector should use the simpler direct path.

Local data and privacy

Evoui stores browser profiles, temporary Run evidence, and learned knowledge in ~/.evoui/ by default. Managed evidence may temporarily include command arguments, non-empty stdin, page text, form input, or site-returned data. Normal terminal cleanup deletes the content-bearing Run trace after the task and any selected learning work finish; an interruption or cleanup failure may leave data on disk.

Cleanup reduces retained data. It is not redaction, encryption, credential protection, or a privacy boundary. Debug tracing retains additional data without automatic rotation. See SECURITY.md for the full boundary, and never attach credentials, cookies, browser profiles, or task traces to a public issue.

By default, the selected Session and visible browser window remain open after a task for reuse, including their login state. Ask the agent to close the Session when you no longer want it running.

Update or remove

For a CLI-managed installation, update by running the install command again with the supported hosts you use. For example, to update Codex:

npx skills add Salmonbird/evoui-browser --skill evoui-browser -g -a codex

Use -a claude-code or -a cursor instead, or repeat -a for multiple supported hosts.

Existing clone-and-symlink installations continue to update directly:

git -C ~/src/evoui-browser pull --ff-only

After either update method, start a new agent session.

To remove the global CLI-managed installation from all hosts:

npx skills remove evoui-browser -g

Removing the Skill does not delete ~/.evoui/ or the separately installed agent-browser runtime. Inspect local state before deleting it.

If installation fails, first check agent-browser --version. Use agent-browser doctor only to diagnose a browser or daemon startup problem; it performs active checks and may clean stale daemon state.

Contributing

Small fixes, docs, tests, reproducible cases, and focused pull requests are welcome. The two local validation commands and the few changes worth discussing first are in CONTRIBUTING.md. To inspect or modify Evoui, clone the repository rather than relying only on the CLI-managed installation.

License and attribution

Evoui Browser is licensed under the Apache License 2.0. Third-party notices are in NOTICE. Modified documentation derived from agent-browser retains a separate upstream license copy.