How Ranger Works

Ranger Feature Review is a system of interconnected components that bring browser-based QA to agentic development. This page explains what each piece does and how they fit together.

Architecture

Your coding agent (Claude Code) drives the workflow. You prompt your coding agent exactly as you normally do, and the Ranger plugin hooks remind your agent to create a Ranger feature review and define the user workflows as scenarios, using the ranger CLI.

Under the hood, the CLI calls Ranger’s API to store your feature review and make it available to you on the Ranger Dashboard. When your agent is ready to test its work, it calls ranger go, which kicks off a local browser agent to navigate through your site. It verifies each scenario separately and evidence flows to the Ranger API and becomes reviewable on the dashboard.

Components

Ranger CLI

Package: @ranger-testing/ranger-cli (installed globally via npm)

The CLI is the primary interface between your local development environment and Ranger. It handles:

• Project setup (ranger setup): authentication, browser installation, plugin and skill setup
• Feature review management (ranger create/resume/show): creating and tracking feature reviews with scenarios
• Browser verification (ranger go): orchestrating a browser agent to verify your UI
• Profile management (ranger profile add/use/ls): configuring how the browser agent accesses your app

The CLI stores project-level config in a .ranger/ directory and credentials locally on your system.

Skills

Location: .claude/skills/ranger/ (project or user level)

Skills are markdown files that teach Claude the Ranger workflow. They cover four scenarios:

1. Starting a session: check for existing feature reviews before creating new ones
2. Creating a feature review: write scenarios as E2E test scenarios, not TODO lists
3. Verifying a feature review: run browser verification and interpret results
4. Addressing feedback: read reviewer comments, fix code, and re-verify

Skills are installed via ranger skillup and injected into Claude’s context when you run /ranger:enable.

Claude Code Plugin

Package: ranger@trailhead (installed via Claude Code marketplace)

The plugin integrates Ranger into Claude Code’s lifecycle through hooks, automatic triggers that fire at key moments:

• When you start a session, Ranger checks if it should auto-enable for your branch
• When you edit files, Ranger suggests tracking your work as a feature review
• When you enter plan mode, Ranger reminds you to include a feature review specification
• When your session ends, Ranger concludes the active feature review session

This helps to make using Ranger Feature Review seamless because Claude doesn’t forget about it when starting development or after compaction. Hooks are opt-in. Run /ranger:enable to activate them for your session & branch.

Browser Verification Agent

When ranger go runs, the CLI spawns a sub-agent: a separate Claude SDK instance with access to Playwright-like browser tools. This agent:

1. Opens your app in Chromium (using saved authentication)
2. Follows the scenario description as a test script
3. Navigates, clicks, types, and takes screenshots
4. Evaluates whether the scenario works correctly
5. Returns a structured verdict: verified, partial, blocked, or failed

All evidence (screenshots, video, Playwright traces, conversation logs) is uploaded to Ranger’s API and becomes visible on the dashboard.

The browser agent runs locally on your machine, against your local dev server. It has a 59-minute timeout and stays within your configured base URL.

Ranger API

The backend stores all feature review data: feature reviews, scenarios, sessions, verification evidence, reviews, and comments.

None of your code is ever stored on Ranger servers.

Feature Review Dashboard

URL: dashboard.ranger.net

The web UI where you and your team review verified feature reviews. It provides:

• Feature reviews list with status, branch, and creator
• Feature review detail page displaying scenarios, screenshot/video evidence, and a comments thread on the right
• Review workflow to approve feature reviews, request changes, or leave comments
• PR description generation with markdown summaries and screenshots
• Test generation to turn verified scenarios into permanent E2E tests as part of your Ranger test suite

How Verification Fits Into Development

A typical flow looks like this:

1. You enable Ranger (/ranger:enable) and ask Claude to build a feature
2. Claude creates a Ranger feature review with 1-2 scenarios describing the expected behavior
3. Claude implements the code
4. Claude runs ranger go. Ranger’s browser agent tests the feature review scenarios.
5. If the agent finds issues, Claude sees the failure reason and fixes the code
6. Steps 4-5 repeat until verification passes
7. Claude shares the feature review link with you
8. You (or a teammate) review the evidence on the dashboard
9. If you leave comments, Claude reads them via ranger get-review and addresses them
10. Once approved, the feature review can become a permanent E2E test in your organization’s Ranger test suite

Verification happens in a separate browser agent, not in Claude Code’s main context. Claude doesn’t need to reason about browser interactions directly.

Authentication

Ranger uses two layers of authentication.

When you run ranger setup, you log in via browser (WorkOS). The CLI provisions an API key and stores it locally. This authenticates all CLI-to-API communication.

Separately, when you run ranger profile add local, you log in to your app in a Chromium browser. Ranger saves the session cookies so the verification agent can access your app the same way you do.

Data Flow