@lazyingart/aginti-browser

v0.1.0

Published

23 days ago

AgInTi Browser is a local-first Chrome/CDP browser workbench for human-supervised AI browsing, powered by AgInTi Flow.

0High
0Medium
0Low

lachlanchen

aginti agintiflow browser browser-automation chrome cdp agent codex local-first web-automation

English · العربية · Español · Français · 日本語 · 한국어 · Tiếng Việt · 中文 (简体) · 中文（繁體） · Deutsch · Русский

AgInTi Browser is a practical browser automation tool built around real Chrome or Chromium, Chrome DevTools Protocol, and a Codex-compatible command wrapper. It gives the human a visible webapp, a clickable screenshot viewport, DOM observations, a CLI, tmux-friendly service management, and an autonomous surfing loop where every step is bounded and logged.

It is not a browser engine from scratch. It is a controlled browser workbench: real websites run inside real Chrome, while the local app observes screenshots and DOM state, asks an agent for one action, enforces safety rules, and executes that action through CDP.

AgInTi Browser acknowledges and is powered by AgInTi Flow, an agentic workflow system from LazyingArt LLC.

What It Does

Opens a local webapp for manual and agentic browsing control.
Launches or attaches to Chrome/Chromium through Chrome DevTools Protocol.
Shows a live screenshot-backed viewport that you can click, scroll, type into, reload, and navigate.
Combines screenshot state with DOM elements, links, cards, visible text, and page policy.
Provides codex exec powered one-step steering and a capped autonomous surf loop.
Provides a CLI/REPL so webapp and terminal can control the same browser service.
Runs in normal visible Chrome, a contained Xephyr window, or headless mode.
Supports guarded public-domain downloads and blocks shadow-library mirror/download/direct-file navigation.
Writes action logs and autonomous run logs under library/.

Quick Start

git clone https://github.com/lachlanchen/agentic-browser.git
cd agentic-browser
python3 -m pip install -r requirements.txt
./run-agentic-browser-vdesktop.sh start

Then open:

http://127.0.0.1:8794

The default virtual desktop mode is visible Xephyr. The controlled Chrome opens target websites inside one contained virtual-desktop window, while the webapp also shows the same selected tab through its screenshot and DOM panels.

npm Install

AgInTi Browser is packaged as @lazyingart/aginti-browser.

npm install -g @lazyingart/aginti-browser
python3 -m pip install websocket-client
aginti-browser service start

Then open:

http://127.0.0.1:8794

The npm package exposes both command names:

aginti-browser --help
agentic-browser --help

Publishing follows the same secret-handling pattern used by AAPS and AgInTi Flow. Put NPM_TOKEN or NODE_AUTH_TOKEN in .env, or point at an existing trusted env file:

npm install -g npm@^11.10.0
npm trust github @lazyingart/aginti-browser --repo lachlanchen/agentic-browser --file npm-publish.yml
gh workflow run npm-publish.yml --repo lachlanchen/agentic-browser

AGINTI_BROWSER_NPM_ENV=/home/lachlan/ProjectsLFS/Agent/AgInTiFlow/.env npm run publish:env:whoami
AGINTI_BROWSER_NPM_ENV=/home/lachlan/ProjectsLFS/Agent/AgInTiFlow/.env npm run publish:env

AGINTI_BROWSER_NPM_ENV=/home/lachlan/ProjectsLFS/AAPS/.env npm run publish:env:whoami

Trusted publishing is preferred for repeat releases because it avoids local OTPs and long-lived npm publish tokens. The local publish helper creates a temporary .npmrc, never prints the token, and removes the temporary file after npm exits. See docs/npm-publishing.md.

Main Commands

./agentic-browser status
./agentic-browser open --guarded https://example.com
./agentic-browser observe
./agentic-browser goal --start-url https://example.com --max-steps 4 "Extract the visible page title and stop."
./agentic-browser chat

Run the webapp directly:

./run-embedded-agentic-browser.sh

Run a standalone app-mode shell:

./run-agentic-browser-app.sh

Run the process-level agent without the GUI:

./run-true-agentic-browser.sh \
  --goal "Open the page, read the visible title, and stop." \
  --start-url "https://example.com" \
  --max-steps 4

Runtime Modes

| Mode | Use Case | Command | | --- | --- | --- | | Xephyr | Default. One contained nested desktop window, so you can see the controlled Chrome itself | ./run-agentic-browser-vdesktop.sh start | | Headless | No visible controlled browser window; best for background work | AGENTIC_VDESKTOP_MODE=headless ./run-agentic-browser-vdesktop.sh start | | Xvfb | Fully off-screen X desktop when Xvfb is installed | AGENTIC_VDESKTOP_MODE=xvfb ./run-agentic-browser-vdesktop.sh start | | Direct | Local webapp and normal controlled Chrome profile | ./run-embedded-agentic-browser.sh |

Architecture

Webapp / CLI
    |
    v
Local HTTP API
    |
    +-- CDP driver -> Chrome/Chromium tab
    |
    +-- Observation -> screenshot + DOM + policy
    |
    +-- Codex wrapper -> one bounded JSON action
    |
    +-- Safety guard -> allow / block / hold
    |
    v
Action log + autonomous run log

Core files:

embedded_agentic_browser/server.py: webapp/API service.
embedded_agentic_browser/open_chrome_driver.py: Chrome DevTools Protocol driver.
embedded_agentic_browser/agent.py: autonomous surf runtime.
embedded_agentic_browser/safety.py: navigation and download policy.
agentic_browser_cli.py: terminal client and REPL.
run-agentic-browser-vdesktop.sh: tmux + virtual display launcher.
docs/AGENTIC_BROWSER_GUIDE.md: detailed implementation notes.
docs/npm-publishing.md: npm install and LazyingArt publish workflow.
legacy/: older prototype GUI kept as a reference.

Safety Boundary

The browser can inspect normal pages, public-domain/open sources, and design tools such as Figma or BioRender under the local user’s own browser session. It does not bypass login, paywalls, access control, or site restrictions.

Guarded agent actions block shadow-library mirror/download/direct-file URLs and non-public direct binary downloads. Public-domain/open downloads can be allowed when the user explicitly asks for them.

Test

npm test
python3 -m unittest discover -s embedded_agentic_browser/tests
npm pack --dry-run

Current copied validation from the source workspace:

Webapp-driven Xephyr/windowed browsing worked through http://127.0.0.1:8794.
Webapp-driven headless browsing also worked when explicitly requested.
CLI/API smoke tests worked for status, open, observe, and autonomous goal.
Unit suite: 48 tests passing.

Project Lineage

This repo was extracted from a book/workflow automation workspace into a standalone AgInTi Browser project. Future AgInTi Browser development should happen here, not inside the Books repo.

AgInTi Browser is part of the LazyingArt LLC agentic tooling family and acknowledges AgInTi Flow as its workflow foundation: