aim-browser

Headed Chromium CDP engine + thin agent skill suite for A.I.M.
Version 1.3.1 · MIT · BrianV1981/aim-browser
Suite name: aim-browser skill suite (see docs/SKILL_SUITE.md)

Built by one person — not a SaaS

I am a solo developer. No corporate budget, no VC runway, no product team. I build and share so more of us can own our stacks instead of renting every layer until the terms change.

Slogans I actually mean:

If that resonates, a coffee helps more than you might think:

Why this exists as open source (the short version):

• Paywall fatigue is real. Build a stack, get comfortable, then watch the good parts get metered, locked, or re-skinned as a new plan.
• I have felt that rug-pull. I am not alone. Plenty of us have woken up to news that a daily pipeline was changed, gated, or effectively taken away—not because we failed, but because someone else’s product roadmap moved. When a workflow you relied on stops being yours, you rebuild. That is why I care about portable tools and skills that live on your machine, not one vendor’s property.
• Micro-transactions add up. “Just $X/seat/month” times every CLI, host, model, and dashboard is how independence dies by a thousand cuts.
• Hope, not hype. Share the wrenches. Keep the soul of the stack local. Optional coffee is not a paywall—it is how a solo builder keeps shipping without turning every repo into a trap.

MIT means you can fork, self-host, and walk away with the code. Coffee is optional gratitude, never required access.

Agent: read this first

This README is the operator manual for agents. Humans can skim it; you (the agent) must follow it when browsing, searching, or extracting from the live web via this package.

Taxonomy

aim-browser          = TOOL (engine + daemon)
  └── *.skill/       = SKILLS (how agents should call the tool)

• Engine = importable CDP API for production scripts
• Skill = short playbook + CLI an agent loads for one job

Which skill do I use? (decision tree)

Need Google AI Mode answer (conversational)? ──► aim-google-ai      npm run google-ai
Need classic blue links / web-only SERP?     ──► aim-google-web     npm run google-web
Need news headlines?                         ──► aim-google-news    npm run google-news
Need main text from a known URL?             ──► aim-page-fetch     npm run page-fetch
Need PNG proof of a URL?                     ──► aim-screenshot-url npm run screenshot-url
Need YouTube title/channel/meta?             ──► aim-youtube-meta   npm run youtube-meta
Need multi-turn AI Mode chat?                ──► aim-google-ai-chat npm run google-ai-chat
Need Maps place card?                        ──► aim-maps-place     npm run maps-place
Need allowlisted form fill?                  ──► aim-form-fill      npm run form-fill
Need Operator to log in, then continue?      ──► aim-login-hold     npm run login-hold
Need page text diff / change detect?         ──► aim-web-diff       npm run web-diff
Explore DOM / click / eval / PX hold?        ──► aim-browser skill  npm run skill
Build a long-running custom job?             ──► import engine from 'aim-browser'
Gmail / Drive / Calendar API?                ──► NOT this package → aim-google (Workspace CLI)

Skills matrix (suite status)

Status board (what ships vs planned): docs/SKILL_SUITE.md

Install skills into a vessel

From this package root, install creates host folders named by skill id (no .skill suffix), e.g. aim-google-ai/, not aim-google-ai.skill/.

cd /path/to/aim-browser
npm install

# Grok — user-global
npm run install-skills -- "${HOME}/.grok/skills" --mode symlink
# Grok — project-local
npm run install-skills -- /path/to/project/.grok/skills --mode symlink

# AGY / Antigravity — user-global
npm run install-skills -- "${HOME}/.gemini/antigravity-cli/skills" --mode symlink
# AGY — project-local
npm run install-skills -- /path/to/project/.gemini/skills --mode symlink

# OpenCode
npm run install-skills -- /path/to/project/.opencode/skills --mode symlink

Dual-vessel policy: docs/VESSEL_DUAL_COMPAT.md.

Engine root: run skill CLIs from this package root, or set AIM_BROWSER_ROOT to it so src/ resolves.

Standing Operator policies (every skill)

Agents must honor these unless the Operator overrides in-chat.

Seamless headed (real Chrome, zero window on :0): see docs/SEAMLESS_HEADED.md (DISPLAY=:99 / Xvfb).

Prerequisites (before any skill)

1. cwd = aim-browser repo root (or install that includes src/ + *.skill/).
2. Node.js 18+, npm install done.
3. Chromium/Chrome available (BROWSER_BIN if nonstandard).
4. Display for headed mode (Operator seat or Xvfb).

cd /path/to/aim-browser
npm install

Install skills into agent hosts

Always run CLIs from the aim-browser package root (or set AIM_BROWSER_ROOT) so relative imports to src/ resolve.

Design rules (packaging)

1. No machine-local absolute homes or operator usernames in skills/docs.
2. Install dest name = skill id (strip source .skill suffix).
3. Dual vessel: keep Grok and AGY install examples.
4. Prefer $HOME / ~ / /path/to/… in docs.

How to run — shipping skills

A. Google AI Mode (aim-google-ai) — preferred for “what does Google AI say?”

# Standard: start minimized → answer → screenshot optional → STOP daemon
npm run google-ai -- "your query here"

# With proof artifact for reports
npm run google-ai -- --screenshot /tmp/aim-google-ai.png --timeout-ms 120000 "your query"

# Custom CDP port (if 9222 busy)
npm run google-ai -- --port 9333 "your query"

# Leave browser up for a second query in the same session
npm run google-ai -- --keep-open "first query"
npm run google-ai -- --no-start --keep-open "follow-up"   # still default-stop unless keep-open
npm run daemon:stop   # when finished with keep-open chains

Agent parsing

1. Stderr = progress (Starting…, Stopping daemon…).
2. Stdout = markdown answer + sources.
3. After ---JSON--- = machine JSON: { query, title, url, answer, sources[], screenshot? }.
4. Exit 0 = success; non-zero = fatal (daemon still stopped if stop-after default).

Do not

• Invent an AI Mode answer without running this.
• Leave Chromium running after a one-shot (default already stops — don’t pass --keep-open casually).
• Confuse with aim-google (Gmail/Drive API).

Full flags: aim-google-ai.skill/SKILL.md.

B. General exploration (aim-browser skill) — DOM / click / eval

Flags run left → right and keep tab state.

# Health
npm run skill -- --check

# Start minimized daemon, open page, list interactables
npm run skill -- --start --open "https://example.com" --elements

# Content / screenshot
npm run skill -- --url "https://example.com" --content --screenshot /tmp/page.png

# Stop when you started with --keep-style long sessions
npm run skill -- --stop
# or
npm run daemon:stop

Common flag groups (see aim-browser.skill/SKILL.md for full list):

When to use this vs google-ai

C. Daemon only (shared lifecycle)

npm run daemon:start   # minimized headed Chromium, CDP loopback
npm run daemon:check
npm run daemon:stop

Skills call this for you when needed. Prefer skill entrypoints over manual daemon juggling unless debugging.

How to report results (aim-communicate / Operator)

When another agent or the Operator needs proof:

FROM: <your session>
REPLY_TO: <theirs if any>
SKILL: aim-google-ai | aim-browser | …
QUERY_OR_URL: …
EXIT: 0|n
SCREENSHOT: /tmp/….png   (if taken)
SUMMARY: <2–5 lines from answer, no fabrication>

Attach or path-reference the screenshot file. Prefer quoting JSON answer / sources over paraphrasing if contested.

Engine import (production scripts — not first choice for chat agents)

Use when you are writing a durable script, not answering a one-off Operator question.

import { AimBrowser, startDaemon, stopDaemon, checkDaemon } from 'aim-browser';

startDaemon(); // minimized by default
const browser = new AimBrowser();
try {
  await browser.connect();
  const tab = await browser.openTab('https://example.com');
  await browser.connect(tab.id);
  await browser.waitReady();
  await browser.minimizeWindow().catch(() => {});
  // … evaluate / screenshot / etc.
} finally {
  await browser.close().catch(() => {});
  stopDaemon(); // always clean up unless Operator wants a long-lived daemon
}

API surface: src/cdp-client.js / src/index.js.
Tests: npm test (mocked CDP — no Chrome required).

Configuration (env)

Architecture (short)

  Agent loads SKILL.md  ──►  npm run <skill> / node *.skill/scripts/run.js
                                    │
                                    ▼
                           startDaemon() if needed (minimized)
                                    │
                                    ▼
                           AimBrowser  ──CDP ws──►  headed Chromium
                                    │
                                    ▼
                           extract / screenshot / markdown+JSON
                                    │
                                    ▼
                           stopDaemon() by default (close session)

Pure Node CDP (ws only) — no Puppeteer/Playwright dependency.

Security (mandatory)

See SECURITY.md.

• CDP loopback only
• Profile dir may contain live logins — do not commit, copy, or log secrets
• --eval and skill actions run as the profile user
• form-fill / login-hold (planned) require allowlists and Operator awareness

Docs map (deeper reading)

What this package is not

Versioning

Current: 1.3.1.

Support

Solo-built. No corporate dollars. Optional coffee if this saved you a subscription or a rug-pull:

Buy Me a Coffee →

🧬 The A.I.M. Ecosystem

Modular A.I.M. (Actual Intelligent Memory) repositories. Flagship engine: aim-agy.

Active vessels (CLI hosts):

• aim-agy — Core engine / soul (Antigravity CLI). Flagship. Shared nested aim-agy_os/ ships here first.
• aim-grok — Grok CLI vessel (hybrid memory, GitOps, wiki, fleet orchestration tooling).
• aim-opencode — OpenCode CLI vessel.
• aim-codex — OpenAI Codex CLI vessel (greenfield nested soul + Codex overlays; primary main).

Tools & workspaces:

• aim-connect — Self-hosted remote workspace web UI.
• aim-tmux-dashboard — Terminal multi-session monitor.
• aim-browser — Headed Chromium CDP engine + browser skill suite.
• aim-google — Google Workspace CLI (Gmail, Drive, Calendar, …).
• aim-flight-recorder — Forensic Markdown session extractor.
• aim-boardroom — Multi-agent orchestration room (OS multiplexing + artifacts).
• aim-skills — Skills index / multi-CLI install registry (agy, grok, opencode, codex).

DNA, comms & lore:

• aim-coagents — DNA bank for sovereign co-agent blueprints.
• aim-knowledge — Public Obsidian vault / deep-lore archive.
• aim-chalkboard — Optional cross-host async git mailbox (PoC; default same-host comms = aim-communicate skill).

Deprecated / not maintained:

• aim — Original Gemini CLI framework. Deprecated after loss of practical subscription access; Great Migration → aim-agy.
• aim-swarm — Legacy Python swarm factory → use aim-coagents + aim-agy spawn.
• aim-claude / Anthropic-line vessels — Done. Operator does not develop against Anthropic. Use aim-agy / aim-grok / aim-opencode / aim-codex.

Full map: see aim-skills docs/AIM_ECOSYSTEM_MAP.md or Operator artifact AIM_ECOSYSTEM_MAP.md.