---
name: carbon-browser
description: Test a live website, local app, preview, page, element, or user flow with the coding agent's installed local browser. Use for page inspection, bug finding, adaptive exploration, test generation, record/replay, accessibility audits, persona feedback, AI-builder previews, form testing, screenshots, evidence capture, bug reports, and candidate automation export. No testers.ai account or API key is required.
user-invocable: false
---

# CARBON Browser

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

Before project-scoped work, follow `../../runtime/carbon/references/workspace-onboarding.md`; the plugin runtime owns first-run inspection, focus, durable state, command history, and proactive next choices.

At the start, call `carbon_set_preferences` with no arguments and apply the returned local execution preferences.

Apply the returned `executionContext`: honor its reusable prompt, read every configured context document, and use the configured username. Never request or reveal its password. Direct agent-controlled browser sessions must use existing authenticated state or let the user sign in; executable browser runners may receive the password only through `carbon-runtime context exec -- <runner command>`.

Recreate the useful classic CARBON browser-extension workflows through the
coding agent's local browser. Do not require an API key.

## Confirm and negotiate local capability

1. Call `carbon_get_browser_capabilities`.
   Read `browserControl.preferred` and `browserControl.allowed` and preserve them in adapter negotiation. An explicit preference goes first; Automatic may try only allowed controllers in the settings-page order. If no permitted controller meets the required operations or evidence channels, report the gap and link the user to `/carbon-settings` instead of silently selecting another controller. Never use `user-chrome` unless it is explicitly allowed.
2. Call `carbon_manage_browser_session` with `action=negotiate`, the selected
   adapter manifest, and the operations/evidence channels required by the
   planned pass. Missing capabilities must remain visible; select another
   adapter or explicitly re-plan a smaller pass instead of silently
   downgrading.
3. Use the host's installed browser-control capability beneath
   `carbon-browser/v1`. Prefer the
   in-app browser for an isolated session, the user's Chrome only when existing
   authenticated state is needed, and terminal browser automation when that is
   the reliable local option.
   When the user requests Vibium, existing Vibium tests, or Vibium-compatible
   commands, call `carbon_vibium`: use `doctor` first, `exec` for the native CLI,
   `run-test` for an existing suite, and `generate` for CARBON candidates above
   an optional Vibium map. Never set `allowInstall=true` without explicit
   installation approval.
4. Create a durable session with `carbon_manage_browser_session` action `init`,
   and record each observed adapter result with action `record`. The result
   envelope preserves semantic intent separately from selectors and includes
   before/after state, timestamps, adapter identity, actual behavior, evidence
   handles, and unavailable evidence channels.
5. Keep execution inside the selected local controller. If the required local
   capability is unavailable, report the evidence gap instead of switching backends.

## Choose the smallest useful workflow

- **Inspect**: capture the current URL, title, visible state, important elements,
  accessibility structure, and one screenshot when visual evidence matters.
- **Bugfinder**: examine functionality, errors, usability, security indicators,
  privacy, accessibility, performance, SEO, and content. Report only observed
  failures or clearly labeled hypotheses.
- **Generate**: propose positive, negative, boundary, interruption, state,
  permission, security, accessibility, and recovery cases from the observed
  page. Keep them `candidate` until executed.
- **Explore**: adapt after each observation. Use critical mode for high-risk
  investigation, creative mode for unusual combinations and edge conditions,
  or both when the request is broad. Choose **breadth** to sample many routes,
  widgets, states, transitions, roles, and linked APIs; choose **depth** to
  follow one risky journey through boundaries, interruption, retry, recovery,
  persistence, and neighboring state; use **balanced** for breadth first and
  depth on the strongest risk signal.
- **Playback**: execute supplied or generated natural-language steps. Resolve
  elements from roles, labels, visible text, test IDs, and stable selectors;
  capture step outcomes and recover from stale page state before declaring a
  failure.
- **Accessibility**: combine DOM/semantic checks with keyboard traversal,
  focus, contrast, target size, zoom/reflow, and visual review. Separate
  automated failures from manual-review items.
- **Persona feedback**: exercise realistic goals and report feedback across
  visual design, usability, content, features, competitiveness, emotional
  appeal, value, and accessibility. Derive generated users from actual product
  roles, goals, flows, and access needs; keep them separate from the 21 named
  CARBON specialists and keep their qualitative opinion separate from
  deterministic pass/fail results.
- **Builder loop**: test previews from AI coding tools like Lovable, Bolt, v0,
  Replit, Firebase Studio, Base44, or similar environments. Show the proposed
  fix prompt before sending or applying it; make no mutation without scoped
  user approval.
- **Copilot**: inspect an element, suggest form data, preserve session notes,
  draft a tracker-ready bug, or export a candidate automated test.

Use `$carbon` when the user asks for CARBON by name, wants its full
Plan/Test/Review/Focused/Learn workflow, needs a durable clickable run, or
wants recording and playback. CARBON uses this same local-browser preference
but persists evidence under `.carbon/`.

Use the plugin runtime contracts at
`../../runtime/carbon/references/browser/carbon-browser-v1.md` and
`../../runtime/carbon/references/classic-browser-capabilities.md` when selecting
detailed operations, capability requirements, evidence fields, coverage, or
handoff behavior.

## Apply confidence engineering

When the browser surface contains AI-generated code, model behavior, RAG,
ranking, personalization, an agent, or another non-deterministic component,
route the observed browser evidence through CARBON's confidence workflows.

1. Name the decision the evidence must support: investigate, compare, canary,
   ship, hold, roll back, or gather more evidence.
2. Use deterministic browser assertions for stable invariants and
   `carbon-eval` for variable AI behavior.
3. Repeat non-deterministic cases and report distributions, uncertainty, and
   severe failures separately from averages.
4. Challenge generated tests, rubrics, judges, and oracles. Keep the builder and
   evaluator independent for meaningful risk.
5. Preserve prompt, model, data, retrieval, tool, policy, browser, and
   environment versions when they affect the result.
6. Use `carbon-review` for independent challenge and `carbon-release` for a
   ship, canary, hold, rollback, or more-evidence decision.
For an ordinary deterministic website, keep the browser workflow lightweight;
do not introduce statistical evaluation unless the behavior and decision require it.

## Execute locally

1. Establish scope: target, goal, credentials supplied for testing, destructive
   boundaries, and whether third-party or production side effects are allowed.
2. Inspect before acting. Record the initial URL and state.
3. Build a short risk-ranked charter. Explicitly select breadth, depth, or
   balanced coverage and state why. For broad requests, cover a representative
   happy path plus negative, boundary, accessibility, interruption, and recovery
   behavior before adding more volume.
4. Perform one action at a time and observe the resulting URL, visible state,
   errors, and relevant browser telemetry.
5. For every page or materially different page state exercised, create a CARBON
   page-evidence bundle. Capture the richest safely available screenshot,
   DOM/accessibility snapshot, console and page errors, network requests and
   responses, timing/performance, synthetic input/output data, storage-safe
   metadata, trace, and recording/video. Inspect every captured screenshot for
   general layout, clipping, overlap, content, error-state, and responsive
   issues and persist that visual review. Record unsupported or privacy-withheld
   channels as gaps; never invent telemetry.
6. Run the page bundle through the general artifact review: DOM, accessibility,
   console, network, mixed content/security, performance, privacy/redaction,
   failed-test, and cross-channel correlation signals. Repeated cross-page
   issues should be summarized once while every affected page remains linked.
7. During every browser pass, exercise the planned generated user perspectives
   against realistic goals and attach their ratings, what worked, friction, and
   recommendation to the exact page screenshot and test IDs. Record each
   breadth/depth charter observation, action, coverage, and next probe. Persona
   feedback is evidence about experience, not automatic proof of correctness.
8. Capture evidence near the failure: screenshot, exact step, expected behavior,
   actual behavior, console/network signal when available, and whether the
   result reproduced.
9. Re-check surprising failures once from a known state. Do not erase the
   original reproduction.
10. Stop before purchases, messages, account changes, deletions, publication,
   external tracker writes, or other consequential actions unless the user
   explicitly authorized that scope.

## Return the result

Lead with:

- local backend and scope;
- pass, fail, blocked, and not-run counts;
- highest-risk observed findings with reproduction and evidence;
- coverage completed and important gaps;
- candidate tests or automation exports, clearly labeled;
- remaining uncertainty and the next smallest useful check.

Then show a compact visual story directly in chat. Select two to four safe,
visually distinct browser screenshots—prefer three or four when available—and
order them as representative states such as start, interaction, failure, and
completion. Pass them to `carbon_publish_command_report` as privacy-reviewed
`chatScreenshots`, then render every returned Markdown image with its caption.
If fewer than two safe screenshots exist, show what exists and name the gap;
never substitute duplicates or expose sensitive evidence to meet the count.

When a durable run directory exists, use `carbon_record_page_evidence` or
`carbon_evidence.py page` after each tested page/state and
`carbon_analyze_run_evidence` or `carbon_evidence.py analyze` before the final
report. Use `carbon_set_test_strategy`, `carbon_record_persona_feedback`, and
`carbon_record_exploration` (or their `carbon_evidence.py` equivalents) during
the pass. The report must show safe screenshots in context, a per-page channel
matrix, artifact provenance, persona cards/ratings, breadth/depth exploratory
observations, general issue signals, and explicit evidence gaps.

For every actionable finding, include severity, user impact, reproduction,
expected versus actual behavior, evidence, and a copy-ready fix prompt. Do not
equate a screenshot-only suspicion, generated oracle, or green action sequence
with confirmed correctness.

## Required HTML result

Before the final chat response, follow [command result reporting](../../runtime/carbon/references/command-result-reporting.md). Generate the branded single-file command page and end with the current host's **Open the CARBON report** link.
