B_owser

Agentic browser automation and ui testing system — built with composable skills, subagent, command, and justfile layered architecture for repeatable, deployable browser use. Watch the breakdown video to see how Bowser works.

<p align="center"> <img src="images/bowser_11.jpg" width="800" /> </p>

The Four-Layer Stack

<p align="center"> <img src="images/four-layer-stack.gif" width="850" /> </p>

Every Bowser workflow is built from four composable layers — each one does one job and delegates down.

| Layer | Name | Role | Where it lives | | ----- | ------------ | ------------------------------------------------------------------- | ------------------- | | 4 | Just | Reusability — one command to run everything | justfile | | 3 | Command | Orchestration — discover stories, fan out agents, collect results | .claude/commands/ | | 2 | Subagent | Scale — parallel execution, isolated sessions, structured reporting | .claude/agents/ | | 1 | Skill | Capability — drive the browser via CLI or Chrome MCP | .claude/skills/ |

Skills give your agent raw capability. Subagents let you scale that capability into parallel, isolated workers. Commands orchestrate those workers into repeatable workflows. Justfile recipes make everything callable with a single terminal command — by you, your team, or other agents.

The key insight: you can enter at any layer. Test a skill directly, spawn a single agent, run a full orchestration command, or fire a one-liner from your justfile. Each layer is independently testable, and they compose upward.

What is this?

Problem

No consistent agentic tooling for running browser automation and UI testing across tools and applications — agents need both observable (your browser) and headless (background) modes, configurable per-run settings, and true validation workflows with full user-level tooling.

Solution

A composable, dual-purpose system — a skill drives the browser, a subagent wraps it for parallel execution, and a slash command orchestrates stories at scale. Test the skill standalone, spawn one agent for a single story, or fan out across dozens in parallel. The key here is being able to take a slightly opinionated approach and tweak it for a variety of browser automation and ui testing use cases.

Install

Claude Code

Bowser runs inside Claude Code. Install it with any of these methods:

# Native install (recommended — auto-updates)
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew install --cask claude-code

Then start Claude Code in this project:

cd bowser
claude

Playwright CLI

The Playwright Bowser skill requires playwright-cli — a token-efficient CLI for Playwright:

npm install -g @playwright/cli@latest

Verify the install:

playwright-cli --help

Just (optional)

The justfile provides one-command recipes for every layer. Install just:

brew install just

Quick Use

All commands are defined in the justfile. Run just to see what's available.

# ─── Layer 1: Skill (Capability) ─────────────────────────────
just test-playwright-skill                    # Playwright skill direct (headed)
just test-chrome-skill                        # Chrome skill direct (requires --chrome)

# ─── Layer 2: Subagent (Scale) ───────────────────────────────
just test-playwright-agent                    # Playwright subagent (isolated session)
just test-chrome-agent                        # Chrome subagent (requires --chrome)
just test-qa                                  # QA agent — structured story validation

# ─── Layer 3: Command (Orchestration) ────────────────────────
just hop amazon-add-to-cart "earbuds"         # Run a saved workflow via hop-automate
just ui-review                                # Parallel QA across all YAML stories

# ─── Layer 4: Just (Reusability) ─────────────────────────────
just automate-amazon                          # Amazon add-to-cart, multiple items
just summarize-blog                           # Summarize a blog's latest post

Every recipe is parameterized — run just --list for defaults, or override inline: just test-qa headed="false".

Architecture

Bowser is a four-layer system — each layer has one job and delegates down.

┌──────────────────────────────────────────────────────────────────┐
│  REUSABILITY                                                     │
│  just ui-review headed=true vision                               │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  ORCHESTRATE                          /ui-review command   │  │
│  │  Discover YAML stories, fan out agents, aggregate results  │  │
│  │                                                            │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │  │
│  │  │  Agent 1 │  │  Agent 2 │  │  Agent 3 │  ...            │  │
│  │  │  Story A │  │  Story B │  │  Story C │                 │  │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘                 │  │
│  │       │              │              │                      │  │
│  │  ┌────▼──────────────▼──────────────▼───────────────────┐  │  │
│  │  │  SCALE                          bowser-qa-agent      │  │  │
│  │  │  Parse story → execute steps → screenshot → report   │  │  │
│  │  │                                                      │  │  │
│  │  │  ┌────────────────────────────────────────────────┐  │  │  │
│  │  │  │  CAPABILITY               playwright-bowser    │  │  │  │
│  │  │  │  playwright-cli open, snapshot, click, fill,   │  │  │  │
│  │  │  │  screenshot, close                             │  │  │  │
│  │  │  └────────────────────────────────────────────────┘  │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Layer 4 — REUSABILITY   justfile recipe          One command to run everything
Layer 3 — ORCHESTRATE   /ui-review command       Discover stories, spawn team, collect results
Layer 2 — SCALE         bowser-qa-agent          Execute one story, step-by-step with screenshots
Layer 1 — CAPABILITY    playwright-bowser skill  Drive the browser via playwright-cli

graph TD
    subgraph "Layer 4 — Reusability"
        JF["justfile"]
    end

    subgraph "Layer 3 — Orchestration"
        CMD["/ui-review"]
    end

    subgraph "Layer 2 — Scale"
        A1["bowser-qa-agent"]
        A2["bowser-qa-agent"]
        A3["bowser-qa-agent"]
    end

    subgraph "Layer 1 — Capability"
        PW["playwright-bowser"]
    end

    JF --> CMD
    CMD --> A1 & A2 & A3
    A1 --> PW
    A2 --> PW
    A3 --> PW

Why this pattern?

• Each layer is testable in isolation. Run /playwright-bowser to test the skill, spawn a single bowser-qa-agent to test one story, or run /ui-review to test the full pipeline.
• Stories are just YAML. Drop a new .yaml file in ai_review/user_stories/ and it's automatically discovered on the next run.
• Agents are thin wrappers. Their only job: execute the skill, report results. ~20 lines of config.
• Parallel by default. The orchestrator spawns one agent per story — they run simultaneously in isolated browser sessions.
• Token-efficient. Agents navigate via accessibility tree, not vision. Screenshots save to disk for human review. Vision mode is opt-in.

Comparing the Two Approaches

Two browser automation skills built for fundamentally different jobs.

| | Claude-Bowser | Playwright-Bowser | | ----------------------- | ---------------------------------------------- | ---------------------------------------- | | Built for | Personal workflow automation | UI testing at scale | | Browser | Your real Chrome (observable) | Headless Chromium (isolated) | | Skill | /claude-bowser | /playwright-bowser | | Subagent | claude-bowser-agent | playwright-bowser-agent | | Parallel instances | No — single shared instance | Yes (named sessions) | | Auth / cookies | Uses your existing Chrome profile | Persistent per session (--persistent) | | Startup requirement | claude --chrome | Standard Claude Code | | Token efficiency | Lower (MCP tool schemas + accessibility trees) | Higher (CLI-based, minimal context) | | Vision mode | Yes | Yes (PLAYWRIGHT_MCP_CAPS=vision) | | Headed option | Always headed | Headless default, --headed available | | Best for | Personal automation, existing sessions | Scale, CI, testing, ground-up automation |

Claude Bowser — Personal Workflow Automation

Use when you need your identity — your logins, cookies, extensions, and browser state.

# Requires: claude --chrome
/claude-bowser check my order status on amazon.com

Good fit:

• Automating tasks on sites you're already logged into (Gmail, Jira, internal tools)
• One-off personal workflows (fill out a form, grab data from a dashboa