Getting started

Requirements

• Node.js 20 or newer
• A project with a runnable local application
• Playwright-compatible browser tooling for browser journeys

Install

Install Bugmole from the repository or from the published package:

npm install -g @theaiinc/bugmole

For local development:

git clone <your-bugmole-checkout>
cd bugmole
npm install

Initialize a project

From the project you want to verify:

bugmole init

Initialization creates the local Bugmole configuration and prepares the project for an exploration-first workflow. Review the generated configuration before running a plan.

Explore, plan, and run

Start by inspecting the project:

bugmole:explore

Create an executable plan from the discovered application structure and a real actor journey:

bugmole:plan

Run the plan:

bugmole:run

To run across several browsers and devices at once:

bugmole --mode run --plan-id <plan> --browsers chromium,firefox,webkit,msedge --devices "iPhone 15,Pixel 7"

Bugmole installs Chromium. Install the other engines once per machine:

npx playwright install firefox webkit msedge

The framework records lifecycle state and evidence for each project-scoped run. A missing proof or an unsafe action should be reported as blocked or escalated rather than silently marked as passing.

Local project worker

For dashboard-created runs, keep the project worker running:

bugmole serve

The worker keeps MCP available, claims authorized queued runs, executes them locally, and reports progress. Local artifact bytes stay on the client machine.