中文 | English

Clawome

Open-source AI browser agent. Tell it what you want — it browses the web and brings back results.

Quick Start • How It Works • Chat API • DOM Compression • Roadmap

What Can It Do?

clawome "Find the top 3 AI stories on Hacker News today"

  > Find the top 3 AI stories on Hacker News today

  I'll browse Hacker News and find the top AI stories for you.

  [task] Opening https://news.ycombinator.com ...
  [task] Scanning front page for AI-related stories ...
  [task] Extracting titles, scores, and links ...

  [result] Here are today's top 3 AI stories on Hacker News:
  1. "GPT-5 benchmark results leaked" — 842 points
  2. "Open-source vision model beats proprietary ones" — 631 points
  3. "Show HN: AI browser agent that actually works" — 529 points

No browser extensions. No complex setup. Just describe what you want in plain language.

Quick Start

Prerequisites: Python 3.10+

Install & Run

pip install clawome
clawome start

This walks you through LLM setup (pick a provider, enter API key), installs Chromium, and starts the server.

Server & Dashboard:  http://localhost:5001

Run Tasks from Terminal

clawome "Find AI graduate programs at Stanford"
clawome "Compare iPhone 16 Pro vs Samsung S25 Ultra specs"
clawome "What's the weather in Tokyo this weekend?"
clawome status          # Check progress
clawome stop            # Cancel

Or Use the Web Dashboard

Open http://localhost:5001 — chat with Beanie, the built-in AI assistant. It understands context, handles follow-ups, and delegates complex browsing tasks automatically.

Multi-turn conversation example:

You:    Find the top 3 AI papers on arxiv today
Beanie: Here are today's top 3 AI papers:
        1. "Scaling Laws for..." — 45 citations
        2. "Efficient Fine-tuning..." — 32 citations
        3. "Multi-modal Agents..." — 28 citations

You:    Tell me more about the first one
Beanie: "Scaling Laws for Neural Architecture Search"
        Authors: ... Abstract: ...

You:    What about the second author's other recent work?
Beanie: I'll look up their profile on Google Scholar...
        [browses Google Scholar, extracts papers]
        Here are their recent publications: ...

Each message builds on previous context — no need to repeat yourself.

git clone https://github.com/CodingLucasLi/Clawome.git
cd Clawome
cp .env.example .env       # Fill in your LLM API key
./start.sh                 # Start backend + frontend dev server

Dashboard:  http://localhost:5173
API:        http://localhost:5001

cd backend && python -m venv venv && source venv/bin/activate
pip install -r requirements.txt && playwright install chromium
python app.py               # http://localhost:5001

cd frontend && npm install && npm run dev   # http://localhost:5173

How It Works

Clawome uses a two-layer agent architecture:

You ──→ Beanie (Chat Agent) ──→ Runner (Task Engine) ──→ Browser
         │                        │
         │ Understands context    │ Plans subtasks
         │ Calls browser tools   │ Perceive → Plan → Act → Sense
         │ Manages sessions      │ Guard nodes (CAPTCHA, cookies, loops)
         │ Delegates complex     │ Anomaly detection & recovery
         │ tasks to Runner       │ Reports back to Beanie
         │                        │
         └── Watchdog ────────────┘ (monitors progress, intervenes if stuck)

Beanie handles simple questions and browser actions directly. For complex multi-step tasks, it delegates to the Runner — a LangGraph state machine that autonomously plans, browses, and extracts information.

Key Features

Chat API

Send a message, poll for the response. Beanie decides whether to answer directly or launch a browsing task.

# Send a message
curl -X POST http://localhost:5001/api/chat/send \
  -H "Content-Type: application/json" \
  -d '{"message": "Find AI graduate programs at NYU Tandon"}'

# Poll for response
curl http://localhost:5001/api/chat/status?since=0

# Stop processing
curl -X POST http://localhost:5001/api/chat/stop

# Start fresh
curl -X POST http://localhost:5001/api/chat/reset

Response format:

{
  "status": "processing",
  "session_id": "session_a1b2c3d4",
  "messages": [
    {"role": "user", "type": "text", "content": "Find AI programs..."},
    {"role": "agent", "type": "result", "content": "I found 5 programs..."}
  ]
}

Status values: processing (agent is working) → ready (waiting for input)

Tips for Better Results

• Give a URL when possible — "Go to https://example.com and find..." avoids guesswork
• Be specific — "top 5 news headlines" beats "what's on the page"
• Ask follow-ups — Beanie remembers context within a session

DOM Compression

Clawome's DOM compressor turns raw HTML into concise, LLM-friendly trees. Use it standalone for your own agents:

# Open a page
curl -X POST http://localhost:5001/api/browser/open \
  -d '{"url": "https://www.google.com"}'

# Read compressed DOM
curl http://localhost:5001/api/browser/dom

[1] form(role="search")
  [1.1] textarea(name="q", placeholder="Search")
  [1.2] button: Google Search
  [1.3] button: I'm Feeling Lucky
[2] a(href): About
[3] a(href): Gmail

Features:

• 100:1 compression on typical pages
• Preserves visible text, interactive elements, and semantic structure
• Hierarchical node IDs (1.2.3) for precise element targeting
• Site-specific optimizers (Google, Wikipedia, Stack Overflow, YouTube, etc.)
• Custom compressor scripts via Dashboard

Supported LLM Providers

Roadmap

• DOM compression with pluggable site-specific scripts
• Chat agent with session persistence and follow-ups
• Autonomous task engine with multi-step planning
• Guard nodes: CAPTCHA detection, cookie dismissal, loop prevention
• Watchdog monitoring with automatic intervention
• 12+ LLM provider support
• Bilingual Chinese/English dashboard
• MCP (Model Context Protocol) server integration
• Visual grounding — screenshot-based element location
• Multi-agent collaboration

Third-Party Libraries

License

Apache License 2.0 — see LICENSE for details.