Page Snapshots	Inline Scripting	Visual Annotations	AI Agent Prompts

What is spel?

spel is a command-line tool that controls a real browser. You type commands in your terminal, and spel opens pages, clicks buttons, fills forms, takes screenshots, reads page content, and more. Think of it as a remote control for Chrome/Firefox/WebKit that works from the shell.

Concrete example — scrape a page and get its content as Markdown:

spel open https://news.ycombinator.com
spel markdownify                          # page content as clean Markdown
spel screenshot front-page.png            # take a screenshot
spel close

Why not just use Puppeteer / Playwright directly?

• No Node.js, no node_modules, no 100 MB binary downloads. spel is a single self-contained binary (~71 MB). It uses Playwright Java under the hood, but you don't need to set up a Node project, manage npm dependencies, or deal with binary downloads on every npm install.
• Persistent browser session. spel runs a background daemon — your browser stays open between commands. This makes it fast for interactive use and for AI agents that need to issue many commands in sequence.
• Works as a CLI, not just a library. You don't need to write a script to automate a browser. Just type spel open, spel click, spel fill in your terminal (or let your AI agent do it).

Why not just use Claude Code's --chrome / browser MCP tools?

You can! If Claude Code's built-in browser works for you, keep using it. spel offers more when you need:

• Persistent sessions across multiple agent commands (the browser stays open)
• Accessibility snapshots — a structured, numbered view of the page that's better than raw HTML for AI agents
• E2E test generation — record a browser session and turn it into a test
• Allure reports — detailed test reports with traces, screenshots, and network inspection
• CI integration — run the same tests headlessly in CI with proper reporting
• Three browser engines — Chromium, Firefox, and WebKit

Who is this for?

Rationale

spel wraps Playwright Java with idiomatic Clojure: maps for options, anomaly maps for errors, with-* macros for lifecycle, and a native CLI binary for instant browser automation.

• Single binary, no ecosystem baggage: One download, no node_modules, no npm, no transitive dependency surprises. Install the binary, install browsers, done.
• Persistent daemon: First command auto-starts a background browser. Subsequent commands reuse it. No cold-start on every invocation — fast enough for interactive loops and AI agents.
• Accessibility snapshots: Pages are represented as structured, numbered documents (not raw HTML). AI agents can read them like text and reference elements by number — no brittle CSS selectors.
• Record, then generate: Capture any browser session to JSONL and auto-generate idiomatic Clojure tests or reusable scripts.
• Allure reports with network inspection: Full Allure reporting with Playwright traces, network visualization (method, status, headers, body), and visual diffs.
• API testing built in: Intercept, assert, and inspect HTTP traffic in the same tool as your browser tests.
• Three browser engines: Chromium, Firefox, and WebKit — full Playwright API coverage.
• Inline Clojure scripting: Run arbitrary Clojure expressions mid-session via eval-sci — not just shell commands, but real code.

Quick Start

Install

Clojure library:

;; deps.edn
{:deps {com.blockether/spel {:mvn/version "0.7.7"}}}

Native CLI (download from GitHub releases):

# macOS (Apple Silicon)
curl -LO https://github.com/Blockether/spel/releases/latest/download/spel-macos-arm64
chmod +x spel-macos-arm64 && mv spel-macos-arm64 ~/.local/bin/spel

# Linux (amd64)
curl -LO https://github.com/Blockether/spel/releases/latest/download/spel-linux-amd64
chmod +x spel-linux-amd64 && mv spel-linux-amd64 ~/.local/bin/spel

# Linux (arm64)
curl -LO https://github.com/Blockether/spel/releases/latest/download/spel-linux-arm64
chmod +x spel-linux-arm64 && mv spel-linux-arm64 ~/.local/bin/spel

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/Blockether/spel/releases/latest/download/spel-windows-amd64.exe -OutFile spel.exe
Move-Item spel.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\spel.exe"

Add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"  # add to ~/.bashrc or ~/.zshrc

macOS Gatekeeper (binaries are not Apple-signed):

xattr -d com.apple.quarantine ~/.local/bin/spel

Post-install:

spel install   # install browsers
spel version   # verify installation

Guided Installation (for LLM agents)

# Full scaffolding with all 8 agents (default)
spel init-agents

# All agents, no seed test or specs directory
spel init-agents --no-tests

# Scaffold only specific groups
spel init-agents --only=test          # test agents only
spel init-agents --only=automation    # browser automation agents only
spel init-agents --only=visual        # visual QA agents only
spel init-agents --only=bugfind      # adversarial bug-finding agents only
spel init-agents --only=orchestrator # orchestrator agent only
spel init-agents --only=discovery    # product discovery agents only

spel init-agents --loop=opencode   # OpenCode (default)
spel init-agents --loop=claude     # Claude Code

export SPEL_CA_BUNDLE=/path/to/corporate-ca.pem
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
spel install --with-deps

CLI Examples

The CLI is the primary way to use spel. The first command auto-starts a background browser daemon; subsequent commands reuse the same browser session.

Navigate and interact:

spel open https://example.org             # open a page
spel click "text=More information"        # click a link by text
spel fill "#search" "browser automation"  # fill an input field
spel press Enter                          # press a key
spel screenshot result.png                # take a screenshot
spel close                                # close the session

Read page content:

spel get title                            # page title
spel get text                             # all visible text
spel get html                             # full HTML
spel markdownify                          # page as clean Markdown
spel snapshot -i                          # accessibility snapshot with numbered refs

Multiple sessions in parallel:

spel --session shop open https://shop.example.com
spel --session docs open https://docs.example.com
spel --session shop screenshot shop.png
spel --session docs screenshot docs.png

Use your real Chrome profile (with extensions, saved passwords, etc.):

export SPEL_CHANNEL=chrome
export SPEL_PROFILE="$HOME/.config/google-chrome/Default"
spel open https://github.com    # opens with your logged-in session

Run spel --help for the full command list (~150 commands covering navigation, interaction, content extraction, network interception, cookies, tabs, frames, debugging, and more).

Clojure Library

spel is also a Clojure library for writing browser automation and tests programmatically:

(require '[com.blockether.spel.core :as core]
         '[com.blockether.spel.page :as page])

(core/with-testing-page [pg]
  (page/navigate pg "https://example.org")
  (page/title pg))
;; => "Example Domain"

Device emulation:

(core/with-testing-page {:device :iphone-14 :locale "fr-FR"} [pg]
  (page/navigate pg "https://example.org"))

Combined browser + API testing (shared Playwright trace):

(core/with-testing-page [pg]
  (page/navigate pg "https://example.org/login")
  (core/api-get (core/page-api pg) "/api/me"))

API Testing & Playwright-Style Tests

Write browser and API tests side-by-side: spel lets you write browser tests (open pages, click buttons, verify DOM) and API tests (call endpoints, check responses) using the same framework. You get full Playwright traces for both.

API testing on its own:

(core/with-testing-api {:base-url "https://api.example.org"} [ctx]
  (core/api-get ctx "/users"))

Combine browser + API for a single trace: You can link UI and API actions within the same test, ensuring one trace covers front-end and back-end steps:

(core/with-testing-page [pg]
  (page/navigate pg "https://example.org/login")
  (core/api-get (core/page-api pg) "/api/me"))

(core/with-testing-page [pg]
  (page/navigate pg "https://example.org/login")
  (core/with-page-api pg {:base-url "https://api.example.org"} [ctx]
    (core/api-get ctx "/me")))

Retry/polling logic built in: To handle flaky endpoints or wait for backend jobs:

(core/with-retry {}
  (core/api-get ctx "/flaky-endpoint"))

(core/with-retry {:max-attempts 10 :delay-ms 1000 :backoff :fixed
                  :retry-when (core/retry-guard #(= "ready" (:status %)))}
  (core/api-get ctx "/job/123"))

Important: Do not nest with-testing-page inside with-testing-api (or vice versa). Each creates its own Playwright instance, browser, and context, so you end up with separate traces. Use page-api or with-page-api when you want UI and API steps in one trace.

Allure reporting: Browser and API tests can feed the same Allure report with traces, screenshots, steps, and network inspection, so one run tells the whole story.

See the full API reference, browser options, Allure reporting, and API testing.

Ready-made Prompts for AI Coding Agents

What this does: spel init-agents generates pre-written prompt files that teach your AI coding agent (Claude Code, OpenCode, etc.) how to use spel. After running this command, your agent knows all spel commands, best practices, and can write E2E tests, automate browsers, or find bugs — without you having to explain spel's API yourself.

Think of it like this: instead of copy-pasting documentation into your AI agent's context, init-agents drops the right instruction files into your project so the agent picks them up automatically.

# Generate prompt files for Claude Code:
spel init-agents --loop=claude

# Generate prompt files for OpenCode (default):
spel init-agents

What gets created:

After setup, you can ask your AI agent things like:

• "Test the login page" — the agent opens the browser, navigates, interacts, and writes assertions
• "Find bugs on the checkout flow" — the agent explores the UI systematically, looking for issues
• "Scrape product data from this page" — the agent uses spel commands to extract content

spel init-agents                              # all 8 prompt sets (default)
spel init-agents --loop=claude                # Claude Code format
spel init-agents --only=test                  # only test-writing prompts
spel init-agents --only=automation            # only browser automation prompts
spel init-agents --only=visual                # only visual QA prompts
spel init-agents --only=bugfind              # only bug-finding prompts
spel init-agents --only=orchestrator          # only the orchestrator prompt
spel init-agents --only=test,visual           # combine groups
spel init-agents --only=discovery             # only product discovery prompts
spel init-agents --only=core                  # simplified 6-prompt core setup
spel init-agents --simplified                 # same as --only=core
spel init-agents --flavour=clojure-test       # clojure.test instead of Lazytest
spel init-agents --no-tests                   # skip seed test and specs directory

Video Recording

Record browser sessions as WebM files for debugging and CI artifacts.

(def ctx (core/new-context browser {:record-video-dir "videos"}))

See PDF, stitch, and video options.

Test Generation (Codegen)

Record browser sessions and transform them to idiomatic Clojure code.

spel codegen record -o recording.jsonl https://example.org
spel codegen recording.jsonl > my_test.clj

See codegen CLI reference for full actions and output formats.

Building from Source

# Install browsers (via Playwright Java CLI)
clojure -M -e "(com.microsoft.playwright.CLI/main (into-array String [\"install\" \"--with-deps\"]))"

# Build JAR
clojure -T:build jar

# Build native image (requires GraalVM)
clojure -T:build native-image

# Run tests
make test
make test-allure

# Start REPL
make repl

Changelog

See CHANGELOG.md.

License

Apache License 2.0 — see LICENSE.