The Vera Claude Code plugin

Install the Vera plugin for Claude Code, what it is for and what it is not, its commands, and the confirmation rule it always follows.

Gives a coding agent the ability to verify UI work in a real browser, as a real logged-in user, and to keep the checks that turn out to be worth keeping.

Ships a skill (vera-testing), six commands, and the MCP server wiring.

Install

The plugin lives in this repo under integrations/claude-plugin, published through the marketplace manifest at .claude-plugin/marketplace.json.

/plugin marketplace add <owner>/<repo>
/plugin install vera

Then set the two variables the MCP server needs:

Variable	Value
`VERA_MCP_URL`	`https://your-vera-host/api/mcp`
`VERA_TOKEN`	a `vera_…` token from Settings → CI Tokens

Not using the plugin, or want the repo linked to a project as well? npx vera-agent init registers the same MCP server (and writes .vera/config.json + the instructions block) — see Getting started. You don't need both wirings: with the plugin installed, run init --no-mcp.

The token is a bearer credential scoped to one workspace. Mint a personal one so audit rows and usage counters name a human rather than collapsing into a shared actor.

What it is for — and what it is not

Vera is not a general browser-automation tool, and it is not trying to replace one. Reach for it when the thing you need is one of these:

Credentialed — runs as a captured auth role, so the logged-in app is testable and credentials never enter the agent's context.
Environment-scoped — a named environment binds base URL, variables and role together.
Persistent — every run leaves a row, artifacts, and a link a human can open.
Promotable — a throwaway check becomes durable coverage in one call.

If you just want to read a public page, a plain browser tool is lighter. The skill says so too.

Commands

Command	Does
`/vera:verify [what]`	Run a check of a change in a real browser and report the observation. Saves nothing unless asked.
`/vera:cover [goal]`	Propose durable coverage — count first, agreement, then author.
`/vera:fix [runId]`	Triage a red run. Decides test-wrong vs app-wrong, proposes, waits for a yes.
`/vera:status [project]`	Read-only: what exists, what is red, what is flaky.
`/vera:check`	Map a diff to the tests and rules it touches, then offer the next action per finding. Read-only: it runs nothing.
`/vera:repro <issueId\|description>`	Turn a bug report into a failing regression test. Files the issue first when given a description.

The confirm rule

Reading and running a scenario are cheap and reversible, so the agent does them freely. Anything that writes is confirmed first — promoting a scenario, creating or editing a test, applying a repair, filing an issue. This is in the skill, not just in this doc, so it holds without being restated per session.

The reason is specific: apply_repair edits a durable test, and a wrong repair that makes a test green is worse than a red test, because it converts a known failure into a silent one.

"Scenario" and "journey" each mean two things

The skill leads with this, because an agent that guesses wrong here builds the wrong object and then reports success:

You say	It means	What the agent reaches for
Run these steps once, nothing saved	an ad-hoc scenario	`run_scenario`, then `save_scenario_as_test` only if you ask
Test A in one project, then test B in another	a chain	`create_chain` / `run_chain`
One story, a different person at each stage	an Actor Scenario	`create_scenario` / `run_actor_scenario`
A named path through the app, for coverage	a coverage-map journey	`create_journey` — which never runs anything

The last row is the one that bites: a journey is a map entry, not an execution. Asking for "a journey that runs nightly" gets you a suite on a schedule instead.

Troubleshooting

401 on every tool. The reply carries a code, and two of the causes now name themselves rather than hiding behind a generic refusal:

Code	What happened
`token_expired`	The token had an expiry and it has passed. Mint a new one.
`token_owner_lost`	A personal token whose owner left the workspace or was disabled.
`token_rejected`	One of three merged causes: Vera does not recognise the token, it was revoked, or the workspace's plan no longer includes API tokens at all.

The three behind token_rejected stay merged on purpose, so an attacker cannot use the error to probe which one applies. That is why "rotate the token" is not the automatic answer — check the plan too, especially on a workspace that was recently downgraded, where the token is still perfectly valid and simply no longer entitled. A token needs api-access (Pro) or mcp-basic (free tier) to exist at all; a fourth code, token_plan_inactive, is the narrower case where a token works on the MCP surface but not on the CI API, and it says so.

plan_required. The workspace is on cloud and has never picked a plan, so every product route refuses until it does. Nothing is wrong with the token.

scenario_cloud_only. This deployment executes tests on a queue worker, which cannot run an unsaved step list. Save the scenario as a test and run that, or point the environment at an enrolled vera-agent (runTarget: 'agent'), which runs the steps on your own machine and can reach localhost.

scenario_rate_limited / scenario_already_running / scenario_runs_disabled. Bounds, each naming itself and its limit. One scenario runs at a time per workspace, with an hourly cap an admin sets. Wait, or promote and run the test.

ai_key_required. Only generation and repair need the workspace's own AI key (Vera is BYOK). Inspecting, running, scenarios, promoting, failure details, issues, suites and chains all work without one.

Runs never finish. wait_for_run returns status: 'running' past its timeout rather than blocking forever. Call it again — do not loop instantly.