agent-browser-kit

Project-level custom commands for agent-browser.

abk is a transparent wrapper: every agent-browser command works unchanged, and any executable you drop into .abk/commands/ becomes a first-class CLI command. Multi-step browser workflows (log in, seed data, record a walkthrough) collapse into a single invocation that returns one compact JSON line — exactly what AI coding agents need.

agent (Claude Code / Codex)
  │
  ▼
abk ──┬── .abk/commands/<name>.ts ?  →  run your workflow, print one JSON line
      └── anything else             →  exec agent-browser (byte-for-byte passthrough)

Why

AI agents drive browsers step by step. Each step is a model turn, and with MCP-based tooling each turn also carries a page snapshot. An 8-step login flow costs the agent 8 turns of reasoning plus 8 results — every time, on every task.

With agent-browser-kit that flow is written once as a project command:

$ abk login http://localhost:4173 [email protected] secret
{"ok":true,"signedInAs":"[email protected]","url":"http://localhost:4173/notes"}

One turn. ~80 tokens. Deterministic. The intermediate steps run inside the command process and never reach the agent's context.

Install

# the engine (skip if already installed)
brew install agent-browser        # or: npm i -g agent-browser
agent-browser install             # downloads Chrome for Testing if needed

# the kit
npm i -g agent-browser-kit

Quick start

abk is agent-browser everywhere it matters:

abk open https://example.com
abk snapshot -i
abk click @e2
abk close

Add a project command — create .abk/commands/login.ts anywhere in your repo:

import { defineCommand, ab } from "agent-browser-kit"

export default defineCommand({
  description: "Sign in and land on the notes page",
  args: ["base", "email", "password"],
  run({ base, email, password }) {
    ab("open", `${base}/login`)
    ab("find", "label", "Email", "fill", email)
    ab("find", "label", "Password", "fill", password)
    ab("find", "role", "button", "click", "--name", "Sign in")
    ab("wait", "--text", "Signed in as")
    return { signedInAs: email, url: ab("get", "url") }
  },
})

No registration, no build step — the file is the command:

$ abk commands
login <base> <email> <password>   Sign in and land on the notes page

$ abk login http://localhost:4173 [email protected] secret
{"ok":true,"signedInAs":"[email protected]","url":"http://localhost:4173/notes"}

Writing commands

• TypeScript or JavaScript (.ts, .mts, .js, .mjs, .cjs): export defineCommand({ description, args, run }). TypeScript runs directly via jiti — no build step.
• Any executable (.sh, or anything with the executable bit): runs as-is with the positional args. A leading # description: ... comment line is picked up for help listings.
• args are positional and required; suffix ? for optional (["email", "note?"]).
• run's return value becomes the command's entire stdout: {"ok":true, ...result}. Keep it small — it is what the agent reads.
• Thrown errors become {"ok":false,"command":...,"error":"<single line>"} with exit code 1.

Inside run:

| Helper | Does | |--------|------| | ab("open", url) | run one engine command, return trimmed stdout (throws on failure) | | abJson("get", "url") | same, with --json appended and parsed |

Sessions

--session <name> anywhere on the abk command line is lifted into AGENT_BROWSER_SESSION for the whole command, so every nested ab() call hits the same isolated browser:

abk --session checkout login http://localhost:3000 [email protected] secret
abk --session checkout add-to-cart "blue widget"
abk --session checkout close

Rules

• Command names cannot shadow engine commands (open, click, snapshot, ...) or kit commands (commands, help). Shadowing files are ignored with a warning — abk <engine-cmd> must always behave exactly like agent-browser <engine-cmd>.
• The nearest .abk/commands/ directory walking up from the current directory wins.

For AI agents

Discovery is built in:

abk --help            # agent-browser help + a "Project commands" section
abk commands --json   # machine-readable: names, args, descriptions

Add the snippet in docs/agents.md to your project's CLAUDE.md / AGENTS.md so agents prefer abk and know to check for project commands first.

Demo

Run it yourself:

git clone https://github.com/sriprasanna/agent-browser-kit
cd agent-browser-kit && npm install
npm run demo &                  # Acme Notes on http://localhost:4173
cd examples/demo-app
abk --session demo login http://localhost:4173 [email protected] demo
abk --session demo add-note "Ship the kit"
abk --session demo close

How it works

~300 lines, four files, one dependency (jiti):

• src/cli.js — finds the command word (lifting --session flags), dispatches: kit command → project command → engine passthrough
• src/discover.js — walks up to the nearest .abk/commands/, validates names, blocks shadowing
• src/runner.js — loads TS/JS commands in-process (jiti, with agent-browser-kit aliased so imports work without installing the package locally), maps args, prints the JSON envelope
• src/helper.js — ab() / abJson() subprocess helpers

The engine is never patched, wrapped, or reimplemented. It remains a runtime dependency you upgrade independently.

License

MIT