Getting Started

Quick Start (Recommended)

Run the setup wizard in your project directory. It configures the MCP server, adds Greenrun instructions to your CLAUDE.md, and installs slash commands.

npx greenrun-cli init

The wizard will ask for your API token and walk you through each step. Restart Claude Code after setup to connect the MCP server.

Manual Setup

If you prefer to configure manually, add the MCP server directly:

claude mcp add --transport stdio \
  -e GREENRUN_API_TOKEN=your-token-here \
  greenrun -- npx -y greenrun-cli@latest

Then restart Claude Code. Verify the connection by typing /mcp in Claude Code — you should see greenrun listed as a connected server.

Project-Scoped Config

To share the MCP config with your team via source control, use the --scope project flag during init, or create a .mcp.json in your project root:

{
  "mcpServers": {
    "greenrun": {
      "command": "npx",
      "args": ["-y", "greenrun-cli@latest"],
      "env": { "GREENRUN_API_TOKEN": "${GREENRUN_API_TOKEN}" }
    }
  }
}

Each team member sets GREENRUN_API_TOKEN in their .env file.

Run browser tests. Without arguments, runs all active tests for the current project. You can filter by test name, page, or tag:

Impact analysis. Looks at your recent git changes, maps them to pages, and finds which tests are affected. Then offers to run them.

Run tests by tag

Run all tests tagged new for your project:

can you run tests for greenrun.dev tagged new

Claude will fetch all active tests with the new tag, open Chrome, execute each test's instructions, and report the results.

Run a specific test

Run a single test by name:

run the "User can log in" test

Claude matches the test by name, starts a run, executes the instructions in the browser, and records the result.

Run tests for a page

Run every test linked to a specific page:

run all tests for the /checkout page

Useful after making changes to a specific area of your app. Claude finds all tests linked to that page and runs them.

Sweep after changes

Find and run tests affected by your recent code changes:

I just updated the checkout flow, can you sweep and run any affected tests

Claude analyses your git changes, maps modified files to pages, finds linked tests, and offers to run them.

Run everything

Run the full test suite for your project:

run all greenrun tests

Claude runs every active test in the project and gives you a summary table with pass/fail results.

Projects

A project represents one application or website. Everything — tests, pages, tags, and runs — lives under a project. The MCP server matches your current working directory to a project by name or base URL.

Tests

A test is a set of plain-text instructions that describe what to do and what to verify. Claude reads these instructions and executes them step by step in the browser. Tests have a status: active (will be run), draft (work in progress), or archived (retired).

Pages

Pages are URL paths that you link to tests as metadata. They serve two purposes: organising tests by the area of your app they cover, and enabling impact analysis. When you change code that affects /checkout, sweep finds all tests linked to that page.

Tags

Tags are free-form labels for grouping tests. Use them however you like — by feature area (auth, checkout), by test type (smoke, regression), or by priority. Filter tests by tag with /greenrun tag:smoke.

Runs

Each time a test is executed, a run is recorded with the result (passed, failed, or error) and a summary. Runs are created automatically by the slash commands and MCP tools.