Overview
Cairntrace is a local-first behavioral browser-spec layer for coding agents. Specs define intent + outcomes as the behavior contract and steps as repairable hints for reaching that state. The same spec can run from the CLI, through the MCP server, be compiled into an agent journey brief, or be exported to Playwright.
It captures DOM snapshots, screenshots, console logs, network traffic, and outcome evidence into one agent-readable artifact pack. Heals common locator drift without changing the behavior contract. Agent-neutral: there are no Claude, Codex, Cursor, or OpenCode branches in core.
Why browser specs for agents
A real browser acceptance check is the difference between "the model says it's done" and "this is what the user will see." Cairntrace gives your agent the means to write that check, run it, and read what failed — without inventing new verifier types every run.
The "intent + outcomes" pair is the contract. Steps are repairable hints. When the contract changes, the spec is broken (use cairn spec verify --stamp to re-stamp). When only the steps change, the contract survives and the runner keeps trusting the spec.
Companion product: chalupa.run
Cairntrace pairs with chalupa.run, a fleet console for disposable Docker Compose environments on DigitalOcean — status, activity, test runs, and estimated cost, with every service port bound to 127.0.0.1 and only SSH exposed. Install with curl -fsSL https://chalupa.run/install.sh | bash. The same author runs Cairntrace specs against chalupa-spawned stacks: cairn owns the spec/seed lifecycle on a shared Docker host while chalupa provisions and sinks the ephemeral compute behind an SSH tunnel.
Where to go next
- Quickstart — install
cairnand run your first browser spec. - Authoring, Steps, and Verifiers — the typed vocabularies and what makes a contract survive.
- Commands — the
cairnCLI surface: doctor, discover, briefs, checkpoints, stash, investigate, annotate, clip, process monitoring, secrets, and services. - Journey briefs — hand a passing spec to a harness when locators will not replay in another environment.