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 and define the user workflows as checklist items, using the ranger CLI.

Under the hood, the CLI calls Ranger’s API to store your feature and make it available to you on the Ranger Dashboard. When your agent is ready to test its work, it calls ranger verify-feature, which kicks off a local browser agent to navigate through your site. It verifies each checklist item 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 start): authentication, browser installation, plugin and skill setup
• Feature management (ranger feature create/resume/show): creating and tracking features with checklist items
• Browser verification (ranger verify-feature): orchestrating a browser agent to verify your UI
• Environment management (ranger add env/use/env 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 features before creating new ones
2. Creating a feature: write checklist items as E2E test scenarios, not TODO lists
3. Verifying a feature: 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
• When you enter plan mode, Ranger reminds you to include a feature specification
• When your session ends, Ranger concludes the active feature 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 verify-feature 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 checklist item description as a test script
3. Navigates, clicks, types, and takes screenshots
4. Evaluates whether the feature 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 data: features, checklist items, 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 features. It provides:

• Features list with status, branch, and creator
• Feature detail page displaying checklist items, screenshot/video evidence, and a comments thread on the right
• Review workflow to approve features, request changes, or leave comments
• PR description generation with markdown summaries and screenshots
• Test generation to turn verified checklist items 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 with 1-2 checklist items describing the expected behavior
3. Claude implements the code
4. Claude runs ranger verify-feature. Ranger’s browser agent tests the feature.
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 feature get-feedback and addresses them
10. Once approved, the feature 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 start, 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 add env 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