Behavioral browser specs for coding agents

Your coding agent said it’s done. Make the browser prove it.

Cairntrace is a local-first browser testing layer for AI coding agents. Define the user outcome once, replay it through a real browser, and return failures with the evidence needed to fix them.

Run your first spec View on GitHub

git clone https://github.com/abdul-hamid-achik/cairntrace && cd cairntrace && bun install

Open source. MIT licensed. Runs from source with Bun.

flows/orders.ymlcontract locked

version: 1
name: orders_filter
intent: an admin can find failed orders

session:
  resume: admin

outcomes:
  - id: failed_orders_visible
    description: only failed orders remain
    verify:
      text: { contains: "Payment failed" }

steps:
  - open: { path: /orders, waitUntil: networkidle }
  - click: { by: role, role: button, name: "Failed" }

cairn run flows/orders.yml --cold-start --json

passed1 outcome · 2 steps · 3.8s

report.html · agent_context.md · outcomes/

Intent stays fixedSteps can be repairedEvidence stays local

Local-firstYour browser state and run evidence stay on your machine.

Agent-neutralOne CLI, MCP surface, and artifact shape for every harness.

Real browsersUse agent-browser by default or switch to Playwright.

Typed outcomesAssert UI, URL, network, console, files, JSON, and more.

The missing acceptance layer

A green build is not proof the user journey works.

Coding agents can change the code, run unit tests, and still miss a broken checkout, an empty dashboard, or a button that no longer responds. Cairntrace moves the final check into the browser and makes its result legible to the next agent.

Read the contract-first authoring guide

Behavior contract

intent + outcomes define what success means.

fixed

Repairable path

steps are executable hints, not the contract itself.

editable

Evidence pack

Reports, snapshots, console, network, and outcome files.

portable

One behavioral promise, replayed and explained end to end.

A tighter agent loop

Specify. Replay. Repair.

Cairntrace gives the agent a deterministic route from product intent to browser evidence without coupling the spec to one model or one test runner.

01
Declare the outcome
Write the intent and typed observables before scripting the clicks.
cairn spec verify flows/checkout.yml --stamp
02
Replay from a clean browser
Use a login action, checkpoint, or deterministic precondition for cold-start replay.
cairn run flows/checkout.yml --cold-start --json
03
Hand the failure back
Read the focused agent context, inspect the evidence, and repair only the path.
cairn context latest

Built for work that survives the demo

A browser spec your whole toolchain can understand.

Human-readable contracts at authoring time. Stable machine-readable output at run time. Rich evidence when the browser disagrees.

Contract safety

Change the route without moving the finish line.

A contract hash covers intent + outcomes. Healing can rewrite drifted steps, but it cannot silently weaken what the spec promises.

contractHashsha256:98b7…4a21verified

Backend choice

Agent workflow now. Playwright when you need it.

agent-browserdefault
Playwrighttraces · video · CI
Mockfast offline tests

Repair-ready evidence

Start with the answer, then drill into the trace.

run/checkout-2026…├─ agent_context.md├─ report.html├─ outcomes/├─ snapshots/└─ network/ + console/

Stable agent interface

No Claude branch. No Codex shim. No vendor lock-in.

CLI commands support JSON, YAML, and Markdown. MCP tools mirror the same surface, so any capable coding agent can author, run, and read the same spec.

CLIMCPJSONYAMLMD

Use it where confidence is expensive

Give every feature task a real browser definition of done.

Cairntrace fits the moment between “the code compiles” and “ship it.” Keep the spec beside the feature, let the agent run it while working, and preserve the evidence for review or CI.

01
Agent-built features
Verify the user-visible outcome before the task is called complete.
02
High-value workflows
Cover login, checkout, imports, dashboards, and multi-step operations.
03
Regression repair
Compare the browser state and patch locator drift without rewriting intent.
04
Human review
Open a self-contained report instead of reconstructing the run from raw logs.

Questions, answered

What teams ask before the first run.

Still evaluating the fit? The docs stay concrete and the repository is public.

Inspect the source on GitHub

What is Cairntrace?

Cairntrace is a local-first behavioral browser-spec layer for coding agents. A YAML spec defines the product intent, the observable outcomes, and a repairable sequence of browser steps.

Is Cairntrace a replacement for Playwright?

No. Cairntrace adds a contract and agent-readable evidence layer. It can use Playwright as a backend and export stable specs to Playwright when conventional CI tests are the better destination.

Which coding agents can use it?

Any agent that can call a CLI or MCP server can use the same Cairntrace surface. There are no product-specific branches for Codex, Claude Code, Cursor, or OpenCode.

Does run data leave my machine?

Normal runs are local-first. Browser state and artifact packs are written locally. Optional integrations only run when you configure or invoke them.

How does it handle UI drift?

Semantic locators fail with diagnostics, and the healer can propose step changes from fresh browser snapshots. The contract hash prevents those repairs from silently changing the intended outcome.

The browser gets the final word

Turn “looks done” into evidence.

Clone Cairntrace, run the demo flow, and give your next coding task a browser contract.

Start the quickstart Connect an agent