browser_session

Files (3)

• SKILL.md
• runner.py
• setup.sh

SKILL.md (first lines)

# browser_session — multi-step browser automation

A `web` claw on steroids. While `web` is a one-shot Playwright
wrapper good for "fetch this page and read it", `browser_session`
hands the entire interaction loop to [browser-use](https://github.com/browser-use/browser-use)
— a framework that keeps a persistent browser, decorates the DOM
with numbered element IDs, and has its own LLM-driven planning loop
to execute multi-step tasks.

## When to use which

| Need | Tool | Why |
|---|---|---|
| Read one page's content | `web` | Cheap (~3s cold start), trivial |
| Run one JS expression | `web` | Same |
| Take one screenshot | `web` | Same |
| Click + type once | `web` | Same — `click=` + `type_text=` |
| Login + then do stuff | `browser_session` | Persistent session |
| 5+ page navigation | `browser_session` | No cold-start per step |
| Form + multi-page wizard | `browser_session` | Framework handles state |
| Anything where a CSS selector won't survive | `browser_session` | Element-index targeting |

## Why a super-skill

`browser_session` is the first member of LocalKin's **super-skill**
pattern: skills that wrap a battle-tested third-party OSS framework
(here, browser-use's 91K-star codebase) inside a thin SKILL.md
adapter. The kinclaw kernel doesn't care that there's an entire
LLM-driven planning agent inside; it just sees one tool call going
in, one result coming out.

This is "thin soul, fat skill" pushed to its useful extreme:

- We don't reinvent browser-use. We host it.
- Other LocalKin souls (researcher / marketer / curator) can also
  enable `browser_session` and get the same capability.
- If browser-use ships a new version, we re-run `setup.sh` — the
  SKILL.md interface stays the same.

## Setup details

`./setup.sh`:

1. Picks a Python ≥3.11 (homebrew, pyenv, or system) — browser-use
   doesn't support 3.10
2. Creates `./.venv/` (per-skill venv, isolated)
3. `pip install browser-use playwright`
4. `playwright install chromium` (~92 MB Chrome Headless Shell)
5. Verifies the imports work

The venv lives in `./.venv/`. **Add `.venv/` to .gitignore** so the
~500 MB of dependencies don't get committed.

## LLM selection

The framework drives a real LLM internally. Pick one with vision
support — browser-use feeds screenshots to the LLM for visual
reasoning. Recommended (in descending preference):

1. **`claude-sonnet-4.5`** via `ANTHROPIC_API_KEY` — current SOTA
   for browser-use's WebVoyager benchmark
2. **`gpt-4o`** via `OPENAI_API_KEY` — second-best, cheaper
3. **Local Ollama** with a vision model (e.g. `qwen2.5-vl:7b`) via
   `OLLAMA_BASE_URL=http://localhost:11434` — free but ~3-5x slower
   per step; good for long batch runs you don't want to pay for

Set `BROWSER_USE_MODEL=<name>` to override the default for the
selected provider.

## Returns

stdout: the agent's final answer (a string — could be markdown if
the task asked for structured output).

stderr: errors, warnings, the playwright/chromium boot noise.

Non-zero exit: agent failed or reported errors. The kernel will
surface this as a tool error to the calling soul.

## Costs

A typical 5-step task with Claude Sonnet:
- ~30-60 seconds wall-clock
- ~$0.05-0.15 in API tokens (browser-use sends DOM + screenshot at
  every step)

For dev/test use the local Ollama path; for production runs use
Anthropic.

From LocalKinAI/kinclaw, Apache-2.0.

More from LocalKinAI/kinclaw