Scout

[Scout]

Scout

Browser automation, one binary. The simpler alternative to Playwright — no Node, no Python, no runtime. Drive a real browser from Go, any shell, any AI agent (built-in MCP server), or a chat UI.

[Release] [License] [CI] [Go Reference] [Coverage] [Security (nox)]

A single statically-linked scout binary gives you a CLI, an 87-tool MCP server (so any MCP-aware agent — Claude Desktop, Cursor, Cline, custom — has a browser), a conversational chat UI, and a Go library with Gin-like middleware composition. Same engine, four access points.

brew install --cask klarlabs-studio/tap/scout-mcp

vs. Playwright

Quick Start

# CLI — visible browser, one-shot commandsscout observe https://example.com          # structured page snapshotscout markdown https://news.ycombinator.com # page as compact markdownscout screenshot https://github.com         # save screenshotscout extract https://example.com h1        # extract element textscout frameworks https://react.dev          # detect React, Vue, etc.
# MCP Server — give AI agents browser superpowersclaude mcp add scout -- scout mcp serve
# Browser UI — conversational browser automationscout ui serve --provider=ollama --model=mistralcd ui && npm install && npm run dev  # open http://localhost:3000

Install

# Homebrewbrew install --cask klarlabs-studio/tap/scout-mcp
# Direct binarycurl -fsSL https://raw.githubusercontent.com/klarlabs-studio/scout/main/install.sh | bash
# Gogo install go.klarlabs.de/scout/cmd/scout@latest
# As a librarygo get go.klarlabs.de/scout

MCP Server — 77 Tools

Run scout mcp serve and any MCP-aware agent has a browser. No second project to install, no Node runtime, no Python interpreter — the binary is the server. Configure in any MCP client:

claude mcp add scout -- scout mcp serve           # Claude Code

{"mcpServers": {"scout": {"command": "scout", "args": ["mcp", "serve"]}}}

Tool Categories

All tools have MCP annotations (ReadOnly, OpenWorld, ClosedWorld, Idempotent) for smart auto-approval. Read-only tools like observe, extract, and screenshot run without permission prompts.

Runtime Configuration

Switch between headless and visible browser without restarting, and opt into local-dev workflows (loopback, private IPs):

Agent: configure(headless: false)                        → browser window appearsAgent: navigate("https://...")                           → watch it workAgent: configure(headless: true)                         → back to headlessAgent: configure(allow_private_ips: true)                → unlock localhost / 192.168.* / 10.*Agent: navigate("http://127.0.0.1:4173/")                → drive your local dev server

The MCP server also reads SCOUT_ALLOW_PRIVATE_IPS=1 at startup as a one-shot toggle for trusted environments.

Screen Recording (video)

Record the active page as a video. Pure CDP — works in headless, no Playwright needed. Recording survives navigate, open_tab, and switch_tab calls in between, so a multi-page demo lands as one continuous clip:

Agent: start_screen_recording({ width: 1280, height: 800, fps: 15, format: "webm" })Agent: navigate("https://example.com")Agent: click("#cta")Agent: navigate("https://example.com/dashboard")   # recording continues across pagesAgent: stop_screen_recording()       → { path: "/tmp/scout-rec-XXX.webm", format: "webm", encoder: "ffmpeg",           frame_count: N, duration_ms: N }

If ffmpeg is on PATH, the result is encoded to WebM (libvpx-vp9) or MP4 (libx264). If not, scout returns the raw JPEG frames directory plus an ffmpeg concat list so you can encode offline. The result is always a file path, never base64 — never enters your LLM token budget.

Realistic FPS: ~10–15 on typical pages, capped at 30. Implementation polls Page.captureScreenshot (CDP Page.startScreencast events are silently dropped under --headless=new Chrome).

Browser UI

A conversational browser automation interface. Type natural language, watch the browser respond in real-time.

# Start the AG-UI server (Go backend)scout ui serve --provider=ollama --model=mistral    # local, no API keyscout ui serve --provider=claude                     # needs ANTHROPIC_API_KEYscout ui serve --provider=openai --model=gpt-4o     # needs OPENAI_API_KEYscout ui serve --provider=groq --base-url=https://api.groq.com/openai --model=llama-3.3-70b-versatile
# Start the Vue frontendcd ui && npm install && npm run dev                  # http://localhost:3000

The UI streams AG-UI protocol events over SSE:

• Chat panel with markdown rendering and quick-action pills
• Live browser viewport with screenshot streaming and URL bar
• Activity timeline showing tool calls in real-time
• Stop button to cancel mid-stream

The Go server handles the agentic loop: LLM decides which scout tools to call, executes them, streams browser state deltas back to the frontend. Supports any OpenAI-compatible endpoint via --base-url.

Agent Package (Go)

High-level Go API for callers that want to embed scout in a program. Structured output, auto-wait, goroutine-safe. Most users reach scout through the CLI or MCP server above — this section is for the Go-library path.

session, _ := agent.NewSession(agent.SessionConfig{Headless: true})defer session.Close()
// Navigate and observesession.Navigate("https://example.com")obs, _ := session.Observe()               // links, inputs, buttons, text + action costs
// DOM diff — only what changed (saves 50-80% tokens)session.Click("#submit")_, diff, _ := session.ObserveDiff()// diff.Classification: "modal_appeared"// diff.Summary: "Modal/dialog appeared: Login required"
// Semantic form filling — no CSS selectorssession.FillFormSemantic(map[string]string{    "Email": "user-example", "Password": "secret",})
// Visual grounding — click by number, not selectorresult, _ := session.AnnotatedScreenshot()  // numbered labels on elementssession.ClickLabel(7)                        // click element [7]
// Multi-tab coordinationsession.OpenTab("pricing", "https://example.com/pricing")session.SwitchTab("default")
// Framework detection (19 frameworks)frameworks, _ := session.DetectedFrameworks() // ["react", "nextjs"]state, _ := session.ComponentState("#app")    // read React/Vue state
// Network capture — read API responses directlysession.EnableNetworkCapture("/api/")captured := session.CapturedRequests("/api/users")
// Action replay — record once, replay without LLMsession.StartRecordingPlaybook("login-flow")// ... do stuff ...pb, _ := session.StopRecordingPlaybook()agent.SavePlaybook(pb, "login.json")// Later: session.ReplayPlaybook(pb)  // 100x cheaper
// Persistent profilessession.SaveProfile("session.json")   // cookies + localStoragesession.LoadProfile("session.json")
// Content distillation (5 levels)session.Markdown()          // ~2-8KB compact markdownsession.ReadableText()      // ~1-4KB main content onlysession.AccessibilityTree() // ~1-4KB semantic treesession.ObserveWithBudget(500) // fit in ~500 tokens

Core Library (Go)

Gin-like Engine/Context/Group/HandlerFunc with middleware composition. The lowest-level Go API — use it when you want full control of task lifecycle, named groups, and middleware chains:

engine := browse.Default(browse.WithHeadless(true))engine.MustLaunch()defer engine.Close()
engine.Use(middleware.Stealth())engine.Use(middleware.Retry(middleware.RetryConfig{MaxAttempts: 3}))engine.Use(middleware.Timeout(30 * time.Second))
admin := engine.Group("admin", middleware.BasicAuth("admin", "secret"))admin.Task("export", func(c *browse.Context) {    c.MustNavigate("https://app.example.com/admin")    table, _ := c.ExtractTable("#users")    c.Set("data", table)})
engine.RunGroup("admin")

Middleware

CLI

The CLI is a deliberate one-shot tier: each command launches a browser, navigates, runs one read/diagnostic action, prints the result, and exits. Stateful interactive flows (click→type→submit, multi-tab, live cookie/network manipulation) live in the MCP server (scout mcp serve) and chat UI (scout ui serve), which keep a session alive across actions.

CLI defaults to visible browser (--headless to hide):

scout navigate <url>                  # page info as JSONscout observe <url>                   # structured observationscout markdown <url>                  # compact markdownscout readable <url>                  # main readable content (boilerplate stripped)scout accessibility <url>             # semantic accessibility treescout screenshot <url> [--output f]   # save screenshotscout pdf <url> [--output f]          # save PDFscout extract <url> <selector>        # extract textscout table <url> <selector>          # extract a table as structured rowsscout auto-extract <url>              # auto-detect dominant data patternscout eval <url> <expression>         # run JavaScriptscout form discover <url>             # discover form fieldsscout frameworks <url>                # detect frameworksscout app-state <url>                 # global app/store state (JSON)scout aria <url>                      # ARIA violation report (JSON)scout vitals <url>                    # Core Web Vitals (JSON)scout console <url>                   # console errors + network 4xx/5xx (JSON)scout dialog <url>                    # detect visible modal/dialog (JSON)scout auth-wall <url>                 # detect login/auth wall (JSON)scout cookies <url>                   # list cookies (values redacted)scout watch <url> [--interval=5s]     # live-watch page changesscout pipe <command> [selector]       # batch process URLs from stdinscout record <url> [--output f]       # interactive recording → playbookscout mcp serve                       # start MCP serverscout ui serve [flags]                # start chat UIscout version                         # print version

Architecture

scout/├── browse.go, engine.go, context.go   # Gin-like API├── page.go, selection.go              # CDP page & element interaction├── recorder.go                        # Action playbook recording (Navigate/Click/Type → JSON)├── middleware/                        # stealth, resilience, auth, network├── agent/                             # AI agent API (50+ methods)│   ├── session.go                     # Session lifecycle, Navigate, Click, Type│   ├── observe.go, diff.go            # Observe, ObserveDiff, cost estimation│   ├── content.go                     # Markdown, ReadableText, AccessibilityTree│   ├── form.go                        # DiscoverForm, FillFormSemantic, MatchFormField│   ├── annotate.go                    # AnnotatedScreenshot, ClickLabel│   ├── network.go                     # EnableNetworkCapture, CapturedRequests│   ├── spa.go                         # DetectedFrameworks, ComponentState, GetAppState│   ├── tabs.go                        # OpenTab, SwitchTab, CloseTab, ListTabs│   ├── playbook.go                    # StartRecording, ReplayPlaybook, SavePlaybook│   ├── interact.go                    # Hover, DragDrop, SelectOption, ScrollTo│   ├── profile.go                     # CaptureProfile, ApplyProfile, SaveProfile│   ├── selector.go                    # Playwright :text() selector translation│   ├── budget.go                      # ObserveWithBudget, EstimateTokens│   ├── nlselect.go                    # SelectByPrompt, fuzzy NL element matching│   ├── batch.go                       # ExecuteBatch, sequential multi-action│   ├── vision.go                      # HybridObserve, FindByCoordinates│   ├── trace.go                       # StartTrace, StopTrace, action tracing│   ├── screencast.go                  # StartScreenRecording / StopScreenRecording — video via captureScreenshot polling + ffmpeg encode│   ├── iframe.go                      # SwitchToFrame, SwitchToMainFrame│   └── vitals.go                      # WebVitals (LCP/CLS/INP)├── internal/cdp/                      # WebSocket CDP client (context-aware)├── internal/launcher/                 # Chrome process management├── cmd/scout/                         # CLI + MCP server (87 tools)└── docs/                              # Landing page (GitHub Pages)

Security

Vulnerability scanning runs on every push and PR via nox. Findings are uploaded to GitHub code scanning, annotated inline on PRs, and gated against .nox/baseline.json so regressions block merges. The status badge in the header reflects the latest main-branch scan.

nox also drives dependency remediation in place of Dependabot — the Nox Remediate workflow runs weekly (Monday 06:00 UTC) and on demand, executing nox fix against fresh OSV.dev findings and opening a single PR with the verified upgrades.

# Local scannox scan -severity-threshold high .
# Local fixnox fix -input findings.json

License

MIT