AI Browser CLI

An AI-powered browser automation CLI that accepts natural-language queries and executes web tasks autonomously — fully local, no cloud APIs required.

How it works

User Query (CLI)
      │
      ▼
Provider Selection  ←  ollama | anthropic | openai | azure | bedrock | vertexai | groq
      │
      ▼
LangChain ReAct Agent
      │
      ├── LLM Layer (chosen provider)
      │     ├── Ollama          (local, no API key)
      │     ├── Anthropic Claude
      │     ├── OpenAI
      │     ├── Azure OpenAI
      │     ├── AWS Bedrock
      │     ├── Google Vertex AI
      │     └── Groq
      │
      ├── Tools Layer
      │     ├── Primary  : @playwright/mcp  (MCP subprocess)
      │     └── Fallback : Direct Playwright (in-process)
      │
      └── Session Memory       ← optional context carry-over

Prerequisites

Installation

# 1. Install npm dependencies
npm install

# 2. Install the Chromium browser binary used by Playwright
npm run install:browsers

# 3. Copy and edit environment variables
cp .env.example .env

Optional: global install

npm link
# then call: ai-browser "…"

Configuration (.env)

Copy .env.example to .env and fill in the values for the provider(s) you want to use.

Common settings

Ollama (local)

Anthropic Claude

OpenAI

Azure OpenAI

AWS Bedrock

Google Vertex AI

Run gcloud auth application-default login before using Vertex AI.

Groq

Usage

node src/cli.js [options] <query>

Options:
  -P, --provider <provider>    LLM provider to use       (default: ollama)
                               ollama | anthropic | openai | azure | bedrock | vertexai | groq
  -m, --model <model>          Model / deployment name   (skips the picker)
  -H, --headless               Run browser headlessly
  -v, --verbose                Print tool calls and debug info
  -s, --screenshot             Auto-save screenshots
  --no-memory                  Disable session memory for this run
  --max-iterations <number>    Cap agent reasoning steps  (default: 50)
  --timeout <ms>               Agent timeout              (default: 300000)
  -V, --version                Show version
  -h, --help                   Show help

Built-in subcommands

# Check connection status for ALL configured providers
node src/cli.js status

# List models for a specific provider
node src/cli.js models                    # Ollama (default)
node src/cli.js models --provider anthropic
node src/cli.js models --provider groq

Examples

Using Ollama (local)

node src/cli.js --provider ollama "Search best JavaScript frameworks in 2025"
node src/cli.js --provider ollama --model mistral "Find iPhone 16 price on Amazon"

Using Anthropic Claude

node src/cli.js --provider anthropic "Go to news.ycombinator.com and list the top 5 stories"
node src/cli.js --provider anthropic --model claude-3-opus-20240229 "Extract the main headline from bbc.com"

Using OpenAI

node src/cli.js --provider openai "Fill the contact form on example.com with name 'Jane Doe'"
node src/cli.js --provider openai --model gpt-4-turbo --verbose "Go to MDN and summarise the Fetch API page"

Using Azure OpenAI

node src/cli.js --provider azure "Go to github.com/trending and take a screenshot"

Using AWS Bedrock

node src/cli.js --provider bedrock --model anthropic.claude-3-5-sonnet-20241022-v2:0 "Search for Node.js tutorials"

Using Google Vertex AI

node src/cli.js --provider vertexai "Go to google.com/maps and search for coffee near me"

Using Groq

node src/cli.js --provider groq --model llama3-70b-8192 "Summarise the front page of reuters.com"

Interactive mode (no --provider flag)

node src/cli.js
# → shown a provider picker, then a model picker, then a task prompt

Headless + screenshot

node src/cli.js --provider openai --headless --screenshot "Go to github.com/trending"

Project structure

ai-browser-cli/
│
├── src/
│   ├── cli.js                 ← Entry point  (Commander CLI + provider selection)
│   │
│   ├── agent/
│   │   ├── agent.js           ← LangGraph ReAct agent + streaming
│   │   ├── tools.js           ← MCP tools (primary) + direct Playwright (fallback)
│   │   └── prompts.js         ← System prompt + task-planning template
│   │
│   ├── llm/
│   │   ├── providers.js       ← Multi-provider LLM factory (all 7 providers)
│   │   └── ollama.js          ← Ollama-specific helpers (health-check, pull)
│   │
│   ├── browser/
│   │   └── playwright.js      ← BrowserController (chromium singleton)
│   │
│   ├── memory/
│   │   └── memory.js          ← SessionMemory + LongTermMemory
│   │
│   └── utils/
│       ├── logger.js          ← Coloured logger factory
│       └── retry.js           ← withRetry / withTimeout helpers
│
├── .env.example
├── .gitignore
├── package.json
└── README.md

Tool system

MCP tools (via @playwright/mcp)

When available, the agent runs @playwright/mcp as a subprocess and loads its tools through the MCP protocol. These include:

browser_navigate · browser_click · browser_fill · browser_snapshot · browser_screenshot · browser_press_key · browser_scroll · browser_wait_for

Direct Playwright tools (fallback)

If the MCP server cannot start, the agent falls back to Playwright running in-process:

Memory system

Session memory (default on)

• Stores the last 10 query/answer pairs in .memory/session.json
• Injected as context into the next run's system prompt
• Disable for a single run: --no-memory

Long-term memory (optional)

• Key/value JSON store in .memory/long-term.json
• Enable via ENABLE_LONG_TERM_MEMORY=true in .env

Troubleshooting

Ollama not connecting

ollama serve                          # start the server
curl http://localhost:11434/api/tags  # verify it responds

Model not installed (Ollama)

ollama pull llama3
node src/cli.js models --provider ollama   # confirm it appears

Cloud provider credentials missing

The CLI prints a setup hint with the exact variables to add. Copy them into your .env file and re-run. You can also verify all providers at once:

node src/cli.js status

Vertex AI authentication error

gcloud auth application-default login

AWS Bedrock access denied

Ensure the IAM policy attached to your credentials includes bedrock:InvokeModel for the target model ARN.

Playwright / browser not found

npm run install:browsers   # installs Chromium
npx playwright install     # installs all browsers

MCP server fails to start

The agent automatically falls back to direct Playwright. Use --verbose to confirm which mode is active.

Security notes

• Never pass real passwords as CLI arguments (they appear in shell history).
• Store credentials in .env (excluded from version control via .gitignore).
• The agent will not retry login more than twice to avoid account lockouts.
• No browser cookies or credentials are persisted between runs.

License

MIT