This is the full developer documentation for Feature Review # Ranger Feature Review > Automated browser verification and feature review for agentic development. [Ranger](https://www.ranger.net) is the always-on AI QA platform for teams that gives you higher signal, less noise, and faster launches. Ranger Feature Review brings that QA expertise to agentic development. When you ask an AI coding agent to build a feature, Ranger verifies it actually works in a real browser, with real evidence, and gives your team a way to review it collaboratively. ## Demo [Section titled “Demo”](#demo) Want to see it in action? Here’s a quick demo. [Ranger Feature Review Demo](https://www.youtube.com/embed/TB6eHLGtaD4) ## The Problem [Section titled “The Problem”](#the-problem) When you ask Claude to build a feature, it might come back to you with a fully working feature, but you can’t tell until you open your app and click through the full workflow involved. And half the time, it writes code that can’t even be built or fails as soon as the page is loaded. ## How Ranger Feature Review Fixes This [Section titled “How Ranger Feature Review Fixes This”](#how-ranger-feature-review-fixes-this) Ranger acts as your AI agent’s QA team. When your coding agent says it’s done, Ranger runs local browser agents that step through your user flows and verify your features truly look and work the way they’re supposed to. ### 1. Automated Browser Verification [Section titled “1. Automated Browser Verification”](#1-automated-browser-verification) Before your agent says “done,” Ranger tests the feature in a real browser. If something’s broken, Ranger tells the agent to fix it automatically. The agent keeps iterating until Ranger confirms everything works. ### 2. Feature Review Dashboard [Section titled “2. Feature Review Dashboard”](#2-feature-review-dashboard) Every verification produces evidence: screenshots, video recordings, and Playwright traces. Ranger presents this in a review interface (think GitHub PR review, but for UI features). You and your team can browse the evidence, leave comments, approve, or request changes. ### 3. One-Click E2E Tests [Section titled “3. One-Click E2E Tests”](#3-one-click-e2e-tests) Once a feature is verified and approved, you’re one click away from turning it into a permanent end-to-end test in your Ranger test suite. ## The Development Cycle [Section titled “The Development Cycle”](#the-development-cycle) When you start working on something new, create a `feature review` with the Ranger CLI that describes what should be verified (this is a natural extension of an agent’s Plan mode). After your agent writes code, it should automatically run `ranger go` to walk through the flows, capturing evidence of everything it encounters. If everything works, great! Your agent can wrap up, let you know it’s done, and you can take a look at the Ranger Feature Review link to get a walkthrough and ask for changes. If the browser agent finds an issue, it’ll describe it to your coding agent and they’ll iterate until it works or your coding agent decides the work is fully blocked and it needs a human in the loop.  Hey Agents Sound interesting? We’ve got docs just for you. Take a look at [llms.txt](llms.txt). ## Get Started [Section titled “Get Started”](#get-started) * [Quickstart](/getting-started/quickstart). Set up Ranger in 5 minutes and verify your first feature review. * [OpenCode Quickstart](/getting-started/quickstart-opencode). Use OpenCode instead? We can work with that. * [Supported Coding Agents](/getting-started/supported-agents). Using Cursor, Codex, or another agent? Find setup instructions here. * [How It Works](/concepts/how-it-works). The architecture: CLI, plugin, browser agents, and dashboard. * [Ranger In Autonomous Loops](/concepts/autonomous-loop). How Ranger Feature Review supports more autonomous agentic coding. # Quickstart > Get Ranger Feature Review running in your project in about 5 minutes. Already set up? Head to the [Ranger Feature Review Dashboard](https://dashboard.ranger.net) to manage your feature reviews, or check out the [CLI Overview](/reference/cli-overview) for a full list of commands. Get Ranger Feature Review running in your project in about 5 minutes. By the end, your AI coding agent will be able to verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 18 or later * **Claude Code** (or your favorite AI coding agent) * A web application running locally (e.g., on `localhost:3000`) ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project’s root directory (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh ``` This installs the CLI and walks you through interactive setup. If you prefer to install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup ``` ** *Note: If `ranger` conflicts with another program on your system (e.g. the ranger file manager), you can use `ranger-cli` instead for all commands.* This walks you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or another non-interactive setting like an agent sandbox, see the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. The short version: pass a token directly (`ranger setup [token]`) or set the `RANGER_CLI_TOKEN` env var. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). If API keys are challenging in your setup, other approaches are available for enterprise customers — [get in touch](mailto:support@ranger.net). ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### Claude Code Plugin [Section titled “Claude Code Plugin”](#claude-code-plugin) The plugin connects Ranger to Claude’s workflow so it can use the Ranger CLI intuitively. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git (requires a `.claude/` directory). Not using Claude Code? This workflow is focused on Claude Code because that’s what we used when developing and testing it. We also have an OpenCode plugin & skill installation, see [Getting Started with OpenCode](/getting-started/quickstart-opencode). And the skills and CLI work for any coding agent with shell access. See [Supported Coding Agents](/getting-started/supported-agents/) for more detail on how we recommend configuring it for Cursor, Codex and more. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. ```plaintext Would you like to install skills? (Y/n) ``` Say **yes**. Skills are markdown files that get installed into your `.claude/skills/` directory. They tell Claude when and how to create feature reviews, run verifications, and address feedback. ### Profile [Section titled “Profile”](#profile) A profile tells Ranger where your app runs and how to log in. See [Managing Profiles](/concepts/profiles) for the full picture; the quickstart covers the simplest case. After `ranger setup` finishes, create a profile for your app. Use a stable name (an email works well): ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` Ranger checks the URL is reachable, then opens Chromium so you can log in (if your app needs that). **Close the browser when you’re done.** Ranger saves the session, and the verification agent reuses it on every run. Profiles are shared with everyone in your organization by default, so name them by the account they represent. Run `ranger profile ls` to see what’s set up. Different setup for your app? * **No login at all** (logged-out flows, public pages): `ranger profile add my-site --url http://localhost:3000 --skip-auth` * **Running in CI or a background agent** (no human at a keyboard): see [Background Agent and CI Setup](/reference/background-agents-and-ci/). * **Short-lived tokens or a debug auth endpoint**: see [Login instructions](/concepts/profiles/#login-instructions). *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open Claude Code in your project. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, run the slash command: ```plaintext /ranger:enable ``` This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask Claude to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, Claude will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, Claude fixes them and re-verifies automatically. 5. Once everything passes, Claude shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you run `/ranger:resume` in Claude Code.  ## What’s Next [Section titled “What’s Next”](#whats-next) * [Profiles](/concepts/profiles) define where to test and how to access it. * [Scenarios](/concepts/scenarios) are the user flows to guide the verification agent. * [CLI Overview](/reference/cli-overview) gives you (or your agent) extra info about all the available commands. * [CLI Overview](/reference/cli-overview/#authentication) covers all authentication options including CI tokens and managed platforms. # OpenCode Quickstart > Set up Ranger Feature Review with OpenCode. Get Ranger Feature Review running with OpenCode. By the end, your agent will verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Node.js 18 or later * OpenCode * A web application running locally ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project root (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh -s -- --opencode ``` This installs the CLI and runs interactive setup with OpenCode preconfigured. Or install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup --opencode ``` This command will walk you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or from a non-interactive agent, pass a token directly: `ranger setup --opencode [token]`. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). See also the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### OpenCode Plugin [Section titled “OpenCode Plugin”](#opencode-plugin) The plugin reminds OpenCode to use Ranger at various points in the workflow. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git. Under the hood, this adds the following block to your `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@ranger-testing/opencode-plugin"] } ``` For user scope, the config file is at `~/.config/opencode/opencode.json` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. For project scope, it’s at `.opencode/opencode.json` in your repo. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. Ranger installs skills automatically at the same scope you chose for the plugin. Skills are markdown files that tell your coding agent when and how to create feature reviews, run verifications, and address feedback. Project installs go to `.opencode/skills/`. User installs go to `~/.config/opencode/skills/` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. ### Profile [Section titled “Profile”](#profile) Ranger needs to know how to access your running app and how to authenticate. We manage that information in [profiles](/concepts/profiles). After `ranger setup` finishes, create a profile for your app. Use a stable name (an email works well): ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` Ranger checks the URL is reachable, then opens Chromium so you can log in to your app (if it requires authentication). **Close the browser when you’re done.** Ranger saves the session cookies so the verification agent can authenticate the same way. Profiles are shared with everyone in your organization by default, so name them by the account they represent. If your app doesn’t require login, pass `--skip-auth`. *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open OpenCode in your project directory. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, tell your agent to `enable ranger`. This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask your coding agent to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, your coding agent will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, it fixes them and re-verifies automatically. 5. Once everything passes, it shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you ask it to `resume ranger` in OpenCode.  # CLI Overview > All Ranger CLI commands at a glance. The Ranger CLI (`@ranger-testing/ranger-cli`) is the primary tool for setting up, managing, and running Ranger in your project. Install it globally: ```bash npm install -g @ranger-testing/ranger-cli ``` This page covers all commands at a human-readable level. Your AI coding agent has its own detailed skill docs, so you don’t need to memorize flags. ## Setup [Section titled “Setup”](#setup) | Command | What it does | | --------------- | -------------------------------------------------------------------------------- | | `ranger setup` | Full interactive setup: auth, Chromium, plugin, profile, skills. Run this first. | | `ranger login` | Re-authenticate without running full setup again. | | `ranger status` | Show everything: version, org, plugin status, skills, profiles. | | `ranger update` | Update the CLI to the latest version and refresh installed skills. | | `ranger clean` | Remove all Ranger artifacts from the project (nuclear option). | ### `ranger setup` [Section titled “ranger setup”](#ranger-setup) The recommended way to get started. Run it in your project root (should be a git repo for feature review tracking) and it walks you through: 1. Browser-based authentication (or pass a token for CI: `ranger setup [token]`) 2. Chromium installation for browser verification 3. Claude Code plugin installation 4. Profile setup (your app’s URL + login) 5. Skill installation If you skip any step, you can run it individually later — each phase is also available as a subcommand. #### Subcommands [Section titled “Subcommands”](#subcommands) | Command | What it does | | ----------------------- | ------------------------------------------------------------------------------------------ | | `ranger setup` | Full interactive setup (default). | | `ranger setup all` | Explicit full setup — same as bare `ranger setup`. | | `ranger setup deps` | Install Chromium only. No auth, no git repo required. Use `--with-deps` for OS packages. | | `ranger setup login` | Authenticate only. Use `--token ` or `--mcp` for non-interactive auth. | | `ranger setup skills` | Install Claude Code plugin and skills only. Use `--scope user\|project`, `--opencode`. | | `ranger setup profiles` | Set up a local browser profile only. Use `--url`, `--force`, `--allow-insecure-localhost`. | #### Non-interactive mode [Section titled “Non-interactive mode”](#non-interactive-mode) Individual subcommands are the preferred way to script setup in containers and CI: ```bash # Docker build time — no auth needed ranger setup deps --with-deps # Runtime — auth and skills ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` The full `ranger setup` command also accepts flags for non-interactive use: | Flag | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `--url ` | Base URL for profile setup. A browser still opens for auth. | | `--force` | Skip URL reachability check. | | `--skip-chromium` | Skip Chromium installation. | | `--skip-auth` | Skip authentication — install deps only. Useful for container/CI image builds where auth happens at runtime. | | `--with-deps` | Install OS-level dependencies for Chromium (apt packages for Debian/Ubuntu). Pair with `--skip-auth` for container builds. | | `--allow-insecure-localhost` | Allow localhost content in deployed environments (micro frontends). | | `--mcp-bootstrap` | Bootstrap auth via an MCP auth server instead of browser login. Used by managed agent platforms and MCP-compatible tools. | ```bash ranger setup $TOKEN --url http://localhost:3000 ``` #### Headless / Scripted Setup [Section titled “Headless / Scripted Setup”](#headless--scripted-setup) For Docker containers and CI images, use subcommands to separate build-time deps from runtime auth: ```dockerfile # Dockerfile (build time) RUN npm install -g @ranger-testing/ranger-cli RUN ranger setup deps --with-deps ``` ```bash # Runtime startup script ranger setup login --token $RANGER_CLI_TOKEN # or: ranger setup login --mcp ranger setup skills --scope user ``` For a complete CI / background-agent walkthrough, see [Background Agent and CI Setup](/reference/background-agents-and-ci/). ### Authenticating the Ranger CLI to Ranger [Section titled “Authenticating the Ranger CLI to Ranger”](#authenticating-the-ranger-cli-to-ranger) **Interactive (laptops, developer machines)** `ranger setup` opens a browser for login. The CLI manages token refresh automatically. If your session expires, run `ranger login` to re-authenticate. **CI and scripted environments** Pass an API token from your [Ranger Dashboard](https://dashboard.ranger.net/cli): ```bash ranger setup ``` Or set the `RANGER_CLI_TOKEN` environment variable — the CLI reads it automatically. **MCP authentication** The CLI can authenticate via MCP, which may be useful in non-interactive environments where you would like the Ranger CLI to act on a real user’s behalf: ```bash ranger setup --mcp-bootstrap ``` Set `RANGER_MCP_AUTH_URL` to point at your platform’s MCP proxy if applicable. [Contact us](mailto:support@ranger.net) for setup guidance. ### Logging the agent into your app (profiles) [Section titled “Logging the agent into your app (profiles)”](#logging-the-agent-into-your-app-profiles) CLI auth (above) identifies *you* to the Ranger API. Separately, the verification agent needs to log in to *your app*. That’s what [profiles](/concepts/profiles) handle — see that page for setup details. ## Profiles [Section titled “Profiles”](#profiles) Profiles tell Ranger where your app runs and how the agent gets in. | Command | What it does | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ranger profile add ` | Add a profile. Opens a browser for you to log in (or use `--skip-auth` for apps without login). Supports `--url`, `--force`, `--skip-auth`, `--cdp-endpoint`, `--allow-insecure-localhost`, `--safe-mode`, `--setup-header`. | | `ranger profile update ` | Refresh authentication for an existing profile. Runs server-side login when configured; otherwise opens a browser. | | `ranger profile use ` | Switch which profile is active. | | `ranger profile ls` | List all profiles with their URLs and status. | | `ranger profile delete ` | Delete a cloud profile. Asks you to type the name to confirm; pass `--yes` to skip. | Profiles are shared with everyone in your organization by default — name them by the account they represent. Use `--cdp-endpoint` on `profile add` to connect to an Electron app or existing browser via Chrome DevTools Protocol instead of a URL. ## Profile Config [Section titled “Profile Config”](#profile-config) Fine-tune browser behavior per profile. | Command | What it does | | --------------------------------------------------- | ---------------------------------- | | `ranger profile config set ` | Set a config value. | | `ranger profile config get ` | Read a config value. | | `ranger profile config list ` | Show all config for a profile. | | `ranger profile config unset ` | Remove a config value. | | `ranger profile config reset ` | Clear all per-directory overrides. | Supported keys: `baseUrl`, `headless` (true/false), `allowInsecureLocalhost` (true/false), `safeMode` (true/false, disables browser features like Bluetooth that can cause crashes on some systems), `userAgent`, `storageState`, `cdpEndpoint`, `loginInstructions`, `headers.` (custom HTTP headers sent with every request), `setupHeaders.` (HTTP headers sent only during profile setup auth — see below). ```bash ranger profile config set local headless true ranger profile config set local allowInsecureLocalhost true ranger profile config set ci header.Authorization '${AUTH_TOKEN}' ranger profile config set my-electron-app cdpEndpoint http://localhost:9222 ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' ``` Environment variables like `${AUTH_TOKEN}` are resolved at runtime. ### Setup-Only Headers [Section titled “Setup-Only Headers”](#setup-only-headers) Some apps require a custom HTTP header to bypass login protection (e.g. Cloudflare Turnstile) during initial setup, but that header causes problems if sent on every request during test runs (e.g. CORS failures with third-party services). Use `setupHeader.` to set headers that are only sent during the `ranger profile add` auth browser session: ```bash # Via config (applied on next profile add) ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' # Or inline during profile creation ranger profile add local --url https://app.example.com --setup-header "x-bypass-turnstile: a1b2c3d4..." ``` These headers are persisted in the profile and reused when you re-add or overwrite the profile. They are **not** sent during `ranger go` verification runs. ### Custom Login Instructions [Section titled “Custom Login Instructions”](#custom-login-instructions) If your app uses short-lived cookies or tokens that expire before Ranger can use them, you can provide custom login instructions instead of relying on saved auth state. Set `loginInstructions` to tell the Ranger agent how to authenticate before each verification run: ```bash ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', ''). Refresh the page." ``` The agent will follow these instructions as a mandatory first step before every verification. This works with any auth mechanism — local debug endpoints, API keys, token injection, etc. Environment variables are supported: ```bash ranger profile config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token." ``` ## Feature Reviews [Section titled “Feature Reviews”](#feature-reviews) Feature reviews are the core unit of work in Ranger. Each feature review has a name, description, and scenarios to verify in the browser. | Command | What it does | | ------------------------------ | -------------------------------------------------------------------------------------- | | `ranger create ""` | Create a new feature review. Use `-c` for scenarios, `-d` for description. | | `ranger list` | List feature reviews. Use `--current-branch` to filter by your git branch. | | `ranger show` | Show the active feature review’s status and scenarios. | | `ranger resume ` | Set a feature review as active and start its session. | | `ranger add-scenario ""` | Add a scenario to the active feature review. | | `ranger get-review` | Show unaddressed reviewer comments across all scenarios. | | `ranger report [id]` | Generate PR description markdown with screenshots. Use `--json` for structured output. | | `ranger delete` | Soft delete the active feature review. | | `ranger restore ` | Restore a soft-deleted feature review. | ### Creating a Feature Review [Section titled “Creating a Feature Review”](#creating-a-feature-review) ```bash ranger create "Dark Mode Toggle" \ -d "Add dark mode support to settings page" \ -c "User opens settings, toggles dark mode, and the page switches themes" ``` Feature reviews auto-detect your git repo and branch. The feature review becomes active immediately. ### Resuming Work [Section titled “Resuming Work”](#resuming-work) At the start of a session, check for existing feature reviews: ```bash ranger list --current-branch ranger resume feat_abc123 ``` ### Generating Reports [Section titled “Generating Reports”](#generating-reports) `ranger report` generates a PR description from the active feature review’s verified scenarios, including screenshots. ```bash ranger report ranger report feat_abc123 ``` By default, output is markdown. Use `--json` for structured output that other tools can consume: ```bash ranger report --json ``` The JSON output contains the feature review dashboard URL and an array of scenarios: ```json { "url": "https://dashboard.ranger.net/features/feat_...", "scenarios": [ { "description": "string", "result": "verified | incomplete | blocked | in_progress | pending | approved | cancelled | superseded | closed", "rationale": "string | null", "steps": [ { "description": "string", "screenshot": "string (URL) | null", "is_key_step": true } ] } ] } ``` `result` reflects the scenario’s verification status. `rationale` is the agent’s response or the reason for a blocked/incomplete/cancelled status. Each step includes a screenshot URL when available; `is_key_step` marks the most important moments. Use `--exclude` to omit specific scenarios by number (1-based): ```bash ranger report --exclude 2 4 ``` ## Verification [Section titled “Verification”](#verification) `ranger go` spawns a browser agent to test your scenarios. ```bash ranger go ``` The CLI prompts you to select which scenario to verify. The browser agent navigates your app, interacts with the UI, takes screenshots, and returns a verdict (verified, partial, blocked, or failed). Common options: * `--scenario `: skip the selection prompt, verify scenario N directly (1-based) * `--notes ""`: override what the agent does (defaults to the scenario description) * `--start-path /settings`: start the agent on a specific page instead of the base URL * `--base-url `: override the profile’s base URL for this run (also reads `RANGER_BASE_URL`) * `--profile `: use a specific profile instead of the active one (also reads `RANGER_PROFILE`) * `--headed`: force a headed browser for this run only (does not change profile config) ### One-shot verification with credentials inline [Section titled “One-shot verification with credentials inline”](#one-shot-verification-with-credentials-inline) If your team has [automated login](/concepts/profiles/#automated-login) set up with us, you can skip `profile add` entirely and pass credentials inline: ```bash RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --base-url http://localhost:3000 \ --notes "user logs in and sees the dashboard" ``` Ranger logs in for you and saves the session for next time. Automated login is set up per-app — works for any login flow we can run deterministically (username/password, SSO, OAuth, MFA, passkeys). [Reach out](mailto:eng@ranger.net) and we’ll scope your case. ## In Claude Code [Section titled “In Claude Code”](#in-claude-code) These aren’t CLI commands. They’re slash commands inside Claude Code: | Command | What it does | | ----------------- | -------------------------------------------------------------------- | | `/ranger:enable` | Enable Ranger hooks for this session and branch. | | `/ranger:disable` | Disable Ranger hooks. | | `/ranger` | Invoke the Ranger skill (create, verify, or manage feature reviews). | Ranger stays enabled on your branch across sessions (except on `main`/`master`, where it’s session-only). You only need to enable once per branch. # Ranger Feature Review > Automated browser verification and feature review for agentic development. [Ranger](https://www.ranger.net) is the always-on AI QA platform for teams that gives you higher signal, less noise, and faster launches. Ranger Feature Review brings that QA expertise to agentic development. When you ask an AI coding agent to build a feature, Ranger verifies it actually works in a real browser, with real evidence, and gives your team a way to review it collaboratively. ## Demo [Section titled “Demo”](#demo) Want to see it in action? Here’s a quick demo. [Ranger Feature Review Demo](https://www.youtube.com/embed/Y3xUpBtakIE) ## The Problem [Section titled “The Problem”](#the-problem) When you ask Claude to build a feature, it might come back to you with a fully working feature, but you can’t tell until you open your app and click through the full workflow involved. And half the time, it writes code that can’t even be built or fails as soon as the page is loaded. ## How Ranger Feature Review Fixes This [Section titled “How Ranger Feature Review Fixes This”](#how-ranger-feature-review-fixes-this) Ranger acts as your AI agent’s QA team. When your coding agent says it’s done, Ranger runs local browser agents that step through your user flows and verify your features truly look and work the way they’re supposed to. ### 1. Automated Browser Verification [Section titled “1. Automated Browser Verification”](#1-automated-browser-verification) Before your agent says “done,” Ranger tests the feature in a real browser. If something’s broken, Ranger tells the agent to fix it automatically. The agent keeps iterating until Ranger confirms everything works. ### 2. Feature Review Dashboard [Section titled “2. Feature Review Dashboard”](#2-feature-review-dashboard) Every verification produces evidence: screenshots, video recordings, and Playwright traces. Ranger presents this in a review interface (think GitHub PR review, but for UI features). You and your team can browse the evidence, leave comments, approve, or request changes. ### 3. One-Click E2E Tests [Section titled “3. One-Click E2E Tests”](#3-one-click-e2e-tests) Once a feature is verified and approved, you’re one click away from turning it into a permanent end-to-end test in your Ranger test suite. ## The Development Cycle [Section titled “The Development Cycle”](#the-development-cycle) When you start working on something new, create a `feature` with the Ranger CLI that describes what should be verified (this is a natural extension of an agent’s Plan mode). After your agent writes code, it should automatically run `ranger verify-feature` to walk through the flows, capturing evidence of everything it encounters. If everything works, great! Your agent can wrap up, let you know it’s done, and you can take a look at the Ranger Feature Review link to get a walkthrough and ask for changes. If the browser agent finds an issue, it’ll describe it to your coding agent and they’ll iterate until it works or your coding agent decides the work is fully blocked and it needs a human in the loop.  ## Get Started [Section titled “Get Started”](#get-started) * [Quickstart](/getting-started/quickstart). Set up Ranger in 5 minutes and verify your first feature. * [How It Works](/concepts/how-it-works). The architecture: CLI, plugin, browser agents, and dashboard. * [Ranger In Autonomous Loops](/concepts/autonomous-loop). How Ranger Feature Review supports more autonomous agentic coding. # Autonomous Coding Loops > How Ranger fits into agentic development As our team has experimented with agentic development, we’ve come to the same conclusion as many others: an agent needs tools to verify its own work. The more effective those tools are, the longer an agent can productively run and stay on track. An agent that can verify its own work as it goes can ask for less direction and is much more likely to return with a mostly done (and mostly correct) result. Many tools exist to help agents verify their work. The most obvious ones are exactly the same ones that humans use – compilers, type checkers, tests. But UI development is different. Human developers examine results visually, interact with them, navigate through flows. This is a harder step for an agent. Playwright (often via Playwright MCP) is a powerful tool to give an agent insight into the browser experience. But it also incredibly context-hungry and testing multiple or repeated flows very often blows through the context and leads to repeated compactions and the corresponding loss of fidelity. An agent that spends most of its context on browser navigation has little left for the actual coding. ## Separating verification from coding [Section titled “Separating verification from coding”](#separating-verification-from-coding) Ideally, verification should be a separate process that’s hands-off for the coding agent. The agent kicks off a verification task, gets structured results back, and keeps its context for the work that matters: reading code, reasoning about architecture, writing changes. That’s what Ranger Feature Review does for browser-based verification. It does this by spawning a separate browser agent for each verification. This agent has its own context window and its own Playwright session, meaning that it doesn’t distract from coding and many can be run in parallel. The only job of each of these agents is to navigate the app and determine whether a specific behavior works. It returns a verdict (verified, failed, partial, or blocked) along with screenshots, video, and traces. The coding agent never touches the browser directly. This has a practical consequence: the write-verify loop can run many times without degrading. A coding agent using Playwright MCP might get three or four verification cycles before context pressure forces a compaction. With verification offloaded, the coding agent can iterate dozens of times and still have full recall of the codebase, the task, and its earlier decisions. ## Running without supervision [Section titled “Running without supervision”](#running-without-supervision) This also changes what it means to supervise an agent. With inline browser testing, you’re often watching the session because the agent will go off track after a compaction or two. When verification runs separately and returns structured results, the agent can self-correct reliably. It reads the verdict, looks at the failure reason, fixes the code, and verifies again. This is a loop that works while you’re not watching. This matters most for long-running sessions and background agents. If you kick off an agent before stepping away, you want to come back to a result, not a question. An agent with reliable UI verification can work through a feature end-to-end: implement the code, verify it in the browser, read the failure, fix the issue, verify again. Each iteration is cheap in context, and the structured feedback prevents the kind of drift that makes agents go in circles. Evidence accumulates as the agent works. Screenshots, video, and Playwright traces are uploaded to the dashboard at each verification step. When you come back, you’re not reading a conversation log trying to reconstruct what happened. You’re looking at screenshots of your app and a clear pass/fail for each behavior. ## The human review step [Section titled “The human review step”](#the-human-review-step) The agent writes and verifies in a tight inner cycle, then surfaces its work for human review.  The review happens asynchronously on the Ranger dashboard, where you can see exactly what the agent built and how it verified each behavior. If something needs to change, you leave a comment. The agent picks up that feedback, makes the fix, and re-verifies. This is a different relationship with the agent than live pair programming. You define the feature, the agent does the work and checks itself, and you review the evidence when it’s done. The agent’s ability to verify its own UI work is what makes the handoff trustworthy. # Hook System > How Ranger integrates with Claude Code through automatic hooks. Ranger integrates with Claude Code through hooks: automatic triggers that fire at key moments in the coding session. Hooks guide Claude through the Feature Review workflow without requiring you to remember commands or prompt for it repeatedly. The Claude Code plugin should be automatically installed when you run `ranger start`. If you need to re-install them at any point, you can run: ```plaintext /plugin marketplace add ranger-testing/trailhead /plugin install ranger@trailhead ``` from inside Claude or: ```plaintext claude plugin marketplace add ranger-testing/trailhead claude plugin install ranger@trailhead ``` from the terminal. After installing, you may need to restart Claude Code before you can use the plugin. ## Why Hooks [Section titled “Why Hooks”](#why-hooks) We started with just the skills and discovered that Claude kept forgetting to use `ranger` and would return to us with errors that would have been caught with verification. We temporarily solved that with careful and repeated prompting, but wanted to automate it. Claude Code plugins offer “hooks” that can be used to remind Claude–if relevant–to use Ranger and check its work before returning to the user. We’ve found that enabling hooks whenever we’re working on UI-related work has dramatically improved Claude’s reliability with Feature Review. ## Opt-In Model [Section titled “Opt-In Model”](#opt-in-model) Hooks are **off by default**. Run `/ranger:enable` in Claude Code to activate them for your current session and branch. Once enabled on a branch, Ranger stays enabled across sessions. Use `/ranger:disable` to explicitly turn hooks off. On `main`/`master`, hooks only enable at the session level (not branch-persisted), since these branches are shared. ## Hook Reference [Section titled “Hook Reference”](#hook-reference) | Hook | When It Fires | What It Does | | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **session-start** | Session created | Checks if the branch is enabled; auto-enables if so. | | **session-end** | Session ended | If reason is `/clear` and session was enabled, auto-enables on next session. | | **enable** | `/ranger:enable` | Runs `ranger update`, enables session + branch, outputs the full skill content to Claude’s context. | | **disable** | `/ranger:disable` | Disables session + branch, tells Claude to stop using Ranger commands. | | **stop** | Session stopping | If the active feature session still has unfinished items, adds a non-blocking reminder to verify before replying, unless verification is already running. If items are terminal, it tries to conclude the session. Fails open on conclude errors. | | **post-edit** | After file write/edit | If Ranger is enabled but no feature is registered, suggests using `/ranger`. If a feature exists, hints about adding checklist items if scope expanded. | | **pre-compact** | Before context compaction | Reminds Claude to preserve the Ranger Feature Specification in the compacted summary. | | **plan-start** | Entering plan mode | Instructs Claude to include a Ranger Feature Specification in the plan. | | **exit-plan-mode** | Leaving plan mode | Reminds Claude to create the feature with `ranger feature create` before starting implementation. | # How Ranger Works > The architecture behind Ranger: CLI, plugin, browser agents, and dashboard. 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 [Section titled “Architecture”](#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 [Section titled “Components”](#components) ### Ranger CLI [Section titled “Ranger CLI”](#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 [Section titled “Skills”](#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 [Section titled “Claude Code Plugin”](#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 [Section titled “Browser Verification Agent”](#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 [Section titled “Ranger API”](#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 [Section titled “Feature Review Dashboard”](#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 [Section titled “How Verification Fits Into Development”](#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 [Section titled “Authentication”](#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 [Section titled “Data Flow”](#data-flow)  # Quickstart > Get Ranger Feature Review running in your project in about 5 minutes. Get Ranger Feature Review running in your project in about 5 minutes. By the end, your AI coding agent will be able to verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 18 or later * **Claude Code** (or your favorite AI coding agent) * A web application running locally (e.g., on `localhost:3000`) ## Install the CLI [Section titled “Install the CLI”](#install-the-cli) ```bash npm install -g @ranger-testing/ranger-cli ``` ## Run Setup [Section titled “Run Setup”](#run-setup) From your project’s root directory (should be a git repo for feature tracking): ```bash ranger start ``` This walks you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI, pass a token directly: `ranger start `. See the [CI Quickstart](/getting-started/quickstart-ci) for details. ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### Claude Code Plugin [Section titled “Claude Code Plugin”](#claude-code-plugin) The plugin connects Ranger to Claude’s workflow so it can use the Ranger CLI intuitively. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git (requires a `.claude/` directory). ### Browser Environment [Section titled “Browser Environment”](#browser-environment) Ranger needs to know how to access your locally running app and how to authenticate. ```plaintext Enter the base URL for your application: http://localhost:3000 ``` Enter the URL where your app runs locally. Ranger checks that it’s reachable, then opens Chromium so you can log in to your app (if it requires authentication). **Close the browser when you’re done.** Ranger saves the session cookies so the verification agent can authenticate the same way. If your app doesn’t require login, you can close the browser immediately. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. ```plaintext Would you like to install skills? (Y/n) ``` Say **yes**. Skills are markdown files that get installed into your `.claude/skills/` directory. They tell Claude when and how to create features, run verifications, and address feedback. *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open Claude Code in your project. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, run the slash command: ```plaintext /ranger:enable ``` This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask Claude to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, Claude will: 1. Create a feature with checklist items describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger verify-feature`. A browser agent tests the feature in your running app. 4. If verification finds issues, Claude fixes them and re-verifies automatically. 5. Once everything passes, Claude shares a link to the feature review page. ### Review the Feature [Section titled “Review the Feature”](#review-the-feature) Open the feature review link (e.g., `https://dashboard.ranger.net/features/feat_abc123`). You’ll see: * Screenshots and video from the browser verification * A checklist of what was verified * A comments section where you can leave feedback If everything looks good, approve it. If not, leave comments. ## What’s Next [Section titled “What’s Next”](#whats-next) * [CLI Overview](/reference/cli-overview) gives you (or your agent) extra info about all the available commands. # CLI Overview > All Ranger CLI commands at a glance. The Ranger CLI (`@ranger-testing/ranger-cli`) is the primary tool for setting up, managing, and running Ranger in your project. Install it globally: ```bash npm install -g @ranger-testing/ranger-cli ``` This page covers all commands at a human-readable level. Your AI coding agent has its own detailed skill docs, so you don’t need to memorize flags. ## Setup [Section titled “Setup”](#setup) | Command | What it does | | --------------- | ------------------------------------------------------------------------------------ | | `ranger start` | Full interactive setup: auth, Chromium, plugin, environment, skills. Run this first. | | `ranger login` | Re-authenticate without running full setup again. | | `ranger status` | Show everything: version, org, plugin status, skills, environments. | | `ranger update` | Update the CLI to the latest version and refresh installed skills. | | `ranger clean` | Remove all Ranger artifacts from the project (nuclear option). | ### `ranger start` [Section titled “ranger start”](#ranger-start) The recommended way to get started. Run it in your project root (should be a git repo for feature tracking) and it walks you through: 1. Browser-based authentication (or pass a token for CI: `ranger start `) 2. Chromium installation for browser verification 3. Claude Code plugin installation 4. Browser environment setup (your app’s URL + login) 5. Skill installation If you skip any step, you can run it individually later. ## Environments [Section titled “Environments”](#environments) Environments tell Ranger how to access your application: the URL, authentication cookies, and browser settings. | Command | What it does | | -------------------------- | --------------------------------------------------------- | | `ranger add env ` | Add a new environment. Opens a browser for you to log in. | | `ranger use ` | Switch which environment is active. | | `ranger env ls` | List all environments with their URLs and status. | | `ranger env update ` | Re-capture authentication for an existing environment. | Adding an environment with `--ci` creates an encrypted auth file that’s safe to commit to git. See [Managing Profiles](/concepts/profiles) for details. ## Environment Config [Section titled “Environment Config”](#environment-config) Fine-tune browser behavior per environment. | Command | What it does | | --------------------------------------- | ----------------------------------- | | `ranger config set ` | Set a config value. | | `ranger config get ` | Read a config value. | | `ranger config list ` | Show all config for an environment. | | `ranger config unset ` | Remove a config value. | Supported keys: `headless` (true/false), `userAgent`, `storageState`, `loginInstructions`, `header.` (custom HTTP headers). ```bash ranger config set local headless true ranger config set ci header.Authorization '${AUTH_TOKEN}' ``` Environment variables like `${AUTH_TOKEN}` are resolved at runtime. ### Custom Login Instructions [Section titled “Custom Login Instructions”](#custom-login-instructions) If your app uses short-lived cookies or tokens that expire before Ranger can use them, you can provide custom login instructions instead of relying on saved auth state. Set `loginInstructions` to tell the Ranger agent how to authenticate before each verification run: ```bash ranger config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', ''). Refresh the page." ``` The agent will follow these instructions as a mandatory first step before every verification. This works with any auth mechanism — local debug endpoints, API keys, token injection, etc. Environment variables are supported: ```bash ranger config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token." ``` ## Features [Section titled “Features”](#features) Features are the core unit of work in Ranger. Each feature has a name, description, and a checklist of items to verify in the browser. | Command | What it does | | -------------------------------------------- | ------------------------------------------------------------------------- | | `ranger feature create ""` | Create a new feature. Use `-c` for checklist items, `-d` for description. | | `ranger feature list` | List features. Use `--current-branch` to filter by your git branch. | | `ranger feature show` | Show the active feature’s status and checklist. | | `ranger feature resume ` | Set a feature as active and start its session. | | `ranger feature add-checklist-item ""` | Add a checklist item to the active feature. | | `ranger feature get-feedback` | Show unaddressed reviewer comments across all items. | | `ranger feature sessions` | List all sessions (iterations) for the active feature. | | `ranger feature conclude-session` | End the current session, even if items are incomplete. | ### Creating a Feature [Section titled “Creating a Feature”](#creating-a-feature) ```bash ranger feature create "Dark Mode Toggle" \ -d "Add dark mode support to settings page" \ -c "User opens settings, toggles dark mode, and the page switches themes" ``` Features auto-detect your git repo and branch. The feature becomes active immediately. ### Resuming Work [Section titled “Resuming Work”](#resuming-work) At the start of a session, check for existing features: ```bash ranger feature list --current-branch ranger feature resume feat_abc123 ``` ## Verification [Section titled “Verification”](#verification) `ranger verify-feature` spawns a browser agent to test your checklist items. ```bash ranger verify-feature ``` The CLI prompts you to select which checklist item to verify. The browser agent navigates your app, interacts with the UI, takes screenshots, and returns a verdict (verified, partial, blocked, or failed). Common options: * `--item `: skip the selection prompt, verify item N directly (1-based) * `--task ""`: override what the agent does (defaults to the checklist item’s description) * `--start-path /settings`: start the agent on a specific page instead of the base URL * `--env `: use a specific environment instead of the active one * `--headed`: force a headed browser for this run only (does not change environment/profile config) ## Authentication [Section titled “Authentication”](#authentication) | Command | What it does | | --------------------------- | ----------------------------------------------------------------- | | `ranger auth encrypt ` | Encrypt an environment’s auth.json for safe git storage (CI use). | ## In Claude Code [Section titled “In Claude Code”](#in-claude-code) These aren’t CLI commands. They’re slash commands inside Claude Code: | Command | What it does | | ----------------- | ------------------------------------------------------------- | | `/ranger:enable` | Enable Ranger hooks for this session and branch. | | `/ranger:disable` | Disable Ranger hooks. | | `/ranger` | Invoke the Ranger skill (create, verify, or manage features). | Ranger stays enabled on your branch across sessions (except on `main`/`master`, where it’s session-only). You only need to enable once per branch. # Ranger Feature Review > Automated browser verification and feature review for agentic development. [Ranger](https://www.ranger.net) is the always-on AI QA platform for teams that gives you higher signal, less noise, and faster launches. Ranger Feature Review brings that QA expertise to agentic development. When you ask an AI coding agent to build a feature, Ranger verifies it actually works in a real browser, with real evidence, and gives your team a way to review it collaboratively. ## Demo [Section titled “Demo”](#demo) Want to see it in action? Here’s a quick demo. [Ranger Feature Review Demo](https://www.youtube.com/embed/TB6eHLGtaD4) ## The Problem [Section titled “The Problem”](#the-problem) When you ask Claude to build a feature, it might come back to you with a fully working feature, but you can’t tell until you open your app and click through the full workflow involved. And half the time, it writes code that can’t even be built or fails as soon as the page is loaded. ## How Ranger Feature Review Fixes This [Section titled “How Ranger Feature Review Fixes This”](#how-ranger-feature-review-fixes-this) Ranger acts as your AI agent’s QA team. When your coding agent says it’s done, Ranger runs local browser agents that step through your user flows and verify your features truly look and work the way they’re supposed to. ### 1. Automated Browser Verification [Section titled “1. Automated Browser Verification”](#1-automated-browser-verification) Before your agent says “done,” Ranger tests the feature in a real browser. If something’s broken, Ranger tells the agent to fix it automatically. The agent keeps iterating until Ranger confirms everything works. ### 2. Feature Review Dashboard [Section titled “2. Feature Review Dashboard”](#2-feature-review-dashboard) Every verification produces evidence: screenshots, video recordings, and Playwright traces. Ranger presents this in a review interface (think GitHub PR review, but for UI features). You and your team can browse the evidence, leave comments, approve, or request changes. ### 3. One-Click E2E Tests [Section titled “3. One-Click E2E Tests”](#3-one-click-e2e-tests) Once a feature is verified and approved, you’re one click away from turning it into a permanent end-to-end test in your Ranger test suite. ## The Development Cycle [Section titled “The Development Cycle”](#the-development-cycle) When you start working on something new, create a `feature review` with the Ranger CLI that describes what should be verified (this is a natural extension of an agent’s Plan mode). After your agent writes code, it should automatically run `ranger go` to walk through the flows, capturing evidence of everything it encounters. If everything works, great! Your agent can wrap up, let you know it’s done, and you can take a look at the Ranger Feature Review link to get a walkthrough and ask for changes. If the browser agent finds an issue, it’ll describe it to your coding agent and they’ll iterate until it works or your coding agent decides the work is fully blocked and it needs a human in the loop.  Hey Agents Sound interesting? We’ve got docs just for you. Take a look at [llms.txt](llms.txt). ## Get Started [Section titled “Get Started”](#get-started) * [Quickstart](/getting-started/quickstart). Set up Ranger in 5 minutes and verify your first feature review. * [OpenCode Quickstart](/getting-started/quickstart-opencode). Use OpenCode instead? We can work with that. * [Supported Coding Agents](/getting-started/supported-agents). Using Cursor, Codex, or another agent? Find setup instructions here. * [How It Works](/concepts/how-it-works). The architecture: CLI, plugin, browser agents, and dashboard. * [Ranger In Autonomous Loops](/concepts/autonomous-loop). How Ranger Feature Review supports more autonomous agentic coding. # Autonomous Coding Loops > How Ranger fits into agentic development As our team has experimented with agentic development, we’ve come to the same conclusion as many others: an agent needs tools to verify its own work. The more effective those tools are, the longer an agent can productively run and stay on track. An agent that can verify its own work as it goes can ask for less direction and is much more likely to return with a mostly done (and mostly correct) result. Many tools exist to help agents verify their work. The most obvious ones are exactly the same ones that humans use – compilers, type checkers, tests. But UI development is different. Human developers examine results visually, interact with them, navigate through flows. This is a harder step for an agent. Playwright (often via Playwright MCP) is a powerful tool to give an agent insight into the browser experience. But it also incredibly context-hungry and testing multiple or repeated flows very often blows through the context and leads to repeated compactions and the corresponding loss of fidelity. An agent that spends most of its context on browser navigation has little left for the actual coding. ## Separating verification from coding [Section titled “Separating verification from coding”](#separating-verification-from-coding) Ideally, verification should be a separate process that’s hands-off for the coding agent. The agent kicks off a verification task, gets structured results back, and keeps its context for the work that matters: reading code, reasoning about architecture, writing changes. That’s what Ranger Feature Review does for browser-based verification. It does this by spawning a separate browser agent for each verification. This agent has its own context window and its own Playwright session, meaning that it doesn’t distract from coding and many can be run in parallel. The only job of each of these agents is to navigate the app and determine whether a specific behavior works. It returns a verdict (verified, failed, partial, or blocked) along with screenshots, video, and traces. The coding agent never touches the browser directly. This has a practical consequence: the write-verify loop can run many times without degrading. A coding agent using Playwright MCP might get three or four verification cycles before context pressure forces a compaction. With verification offloaded, the coding agent can iterate dozens of times and still have full recall of the codebase, the task, and its earlier decisions. ## Running without supervision [Section titled “Running without supervision”](#running-without-supervision) This also changes what it means to supervise an agent. With inline browser testing, you’re often watching the session because the agent will go off track after a compaction or two. When verification runs separately and returns structured results, the agent can self-correct reliably. It reads the verdict, looks at the failure reason, fixes the code, and verifies again. This is a loop that works while you’re not watching. This matters most for long-running sessions and background agents. If you kick off an agent before stepping away, you want to come back to a result, not a question. An agent with reliable UI verification can work through a feature end-to-end: implement the code, verify it in the browser, read the failure, fix the issue, verify again. Each iteration is cheap in context, and the structured feedback prevents the kind of drift that makes agents go in circles. Evidence accumulates as the agent works. Screenshots, video, and Playwright traces are uploaded to the dashboard at each verification step. When you come back, you’re not reading a conversation log trying to reconstruct what happened. You’re looking at screenshots of your app and a clear pass/fail for each behavior. ## The human review step [Section titled “The human review step”](#the-human-review-step) The agent writes and verifies in a tight inner cycle, then surfaces its work for human review.  The review happens asynchronously on the Ranger dashboard, where you can see exactly what the agent built and how it verified each behavior. If something needs to change, you leave a comment. The agent picks up that feedback, makes the fix, and re-verifies. This is a different relationship with the agent than live pair programming. You define the feature, the agent does the work and checks itself, and you review the evidence when it’s done. The agent’s ability to verify its own UI work is what makes the handoff trustworthy. # How Ranger Works > The architecture behind Ranger: CLI, plugin, browser agents, and dashboard. 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 [Section titled “Architecture”](#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 [Section titled “Components”](#components) ### Ranger CLI [Section titled “Ranger CLI”](#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 [Section titled “Skills”](#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 [Section titled “Claude Code Plugin”](#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 [Section titled “Browser Verification Agent”](#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 [Section titled “Ranger API”](#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 [Section titled “Feature Review Dashboard”](#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 [Section titled “How Verification Fits Into Development”](#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 [Section titled “Authentication”](#authentication) Ranger uses two layers of authentication. When you run `ranger setup`, you log in via browser. The CLI stores credentials locally and uses them to authenticate all CLI-to-API communication. Tokens refresh automatically. For details, see [Authentication](/reference/cli-overview/#authentication). 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 [Section titled “Data Flow”](#data-flow)  # Managing Profiles > Control where to test and how to access it Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how to access it. ## Architecture of Profiles [Section titled “Architecture of Profiles”](#architecture-of-profiles) Profiles are made up of three components: * endpoint * auth * settings The endpoint is where the test runs. Auth and settings define how the browser verification agent gets in. You can create as many profiles as you need. ### Endpoint [Section titled “Endpoint”](#endpoint) Endpoints keep Ranger’s browser agent focused on the environment you want to test. For local development, this is usually a `localhost` host and port where your app is running. The browser agent is restricted to this endpoint, which helps prevent your coding agent from seeing a staging or prod URL in the codebase and attempting to test that instead. In some cases, the goal is to verify behavior in a non-local environment. A profile can be set up for a remote endpoint as well. The endpoint needs to include a URL protocol (usually `http://` or `https://`). Example endpoints: * `http://localhost:3000` * `https://staging.example.com` ### Auth [Section titled “Auth”](#auth) Many testing scenarios require a logged-in user. Asking you to log in every run defeats the purpose of autonomous testing. In some cases, basic username/password auth could live in a `.env` file, but many apps use SSO, 2FA, or magic link login. Instead, Ranger opens a headed browser when you create a profile. You log in once, and Ranger saves the cookies and session state for each test run. This handles more complicated auth reliably. Cookies expire, so profile auth goes stale over time. For most apps this is fine during a coding session. For background agents and CI, plan to refresh auth when it expires. #### Custom Login Instructions [Section titled “Custom Login Instructions”](#custom-login-instructions) If your app has short-lived cookies or tokens that expire too quickly for saved auth to work, you can provide `loginInstructions` instead. This tells the browser agent how to authenticate before each verification run — for example, by hitting a local debug endpoint that issues fresh credentials: ```bash ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', ''). Refresh the page." ``` The agent follows these instructions as a mandatory first step before every verification. You can use `${VAR_NAME}` syntax to reference environment variables. This approach works alongside or instead of saved auth state — if both exist, the agent will execute the login instructions regardless. ### Settings [Section titled “Settings”](#settings) Settings fine-tune browser behavior per profile. Update any setting with: ```bash ranger profile config set ``` | Key | Type | Description | | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `headless` | `true`/`false` | Run the browser in headless (no GUI) or headed (visible) mode. Headed is useful for observing verification firsthand. | | `allowInsecureLocalhost` | `true`/`false` | Allow localhost content in deployed environments for micro frontend workflows (e.g. single-spa). **Warning:** this relaxes browser security (disables same-origin protections / allows insecure mixed content) and should be used only for local development, not CI or production verification. Also available as `--allow-insecure-localhost` on `profile add`, `profile update`, and `setup`. | | `userAgent` | string | Override the browser user agent. Useful for bypassing bot protection. | | `storageState` | path | Path to a Playwright storage state file (cookies/localStorage). Usually managed automatically by profile auth. | | `cdpEndpoint` | URL | Chrome DevTools Protocol endpoint for Electron apps or existing browsers (e.g. `http://localhost:9222`). | | `loginInstructions` | string | Natural language instructions the agent follows to authenticate before each verification run. See [Custom Login Instructions](#custom-login-instructions) below. | | `header.` | string | Custom HTTP header sent with every request (e.g. `header.Authorization`). Supports `${VAR}` syntax for env vars. | | `setupHeader.` | string | HTTP header sent only during the `ranger profile add` auth browser session, not during test runs. Useful for bypassing login protection (e.g. Cloudflare Turnstile) without affecting third-party requests. Also available as `--setup-header` on `profile add`. | ### Active Profile [Section titled “Active Profile”](#active-profile) A single profile is set as active and used as the default for `ranger go`, unless you pass another profile via `--profile`. Use `ranger profile use ` to switch and `ranger profile ls` to see what is available. ### Local vs CI Profiles [Section titled “Local vs CI Profiles”](#local-vs-ci-profiles) Local profiles are meant for day-to-day development by a single user and the auth is stored in plaintext. This is convenient and fast, but not safe to share. They’re added to a ranger-specific `.gitignore` to prevent them from being committed to version control. CI profiles are meant for pipelines and other shared usages. The auth file is encrypted and safe to commit. Use the `--ci` flag when adding the profile and in CI or the remote environment, running `ranger setup [token]` will decrypt it. ### User vs Project Scope [Section titled “User vs Project Scope”](#user-vs-project-scope) By default, profiles are stored in the project’s `.ranger/` directory (found by walking up from your current directory). This means each project has its own profiles. If you want a profile available across all your projects, use `--scope user` to store it in `~/.ranger/` instead: ```bash ranger profile add local --scope user --url http://localhost:3000 ``` When a project-level `.ranger/` directory exists, profiles go there unless you explicitly pass `--scope user`. The `--scope` flag on `ranger setup` also applies to profile creation: ```bash ranger setup --scope user --url http://localhost:3000 # plugin, skills, AND profile all go to user level ``` ## Adding and Updating Profiles [Section titled “Adding and Updating Profiles”](#adding-and-updating-profiles) ### Adding (interactive) [Section titled “Adding (interactive)”](#adding-interactive) 1. Run `ranger profile add `. 2. Enter the base URL when prompted. 3. A browser opens. Log in to the account you want the agent to use. 4. Close the browser to save the profile. Ranger sets the new profile as active. Your app should be running before you start. ### Adding (non-interactive) [Section titled “Adding (non-interactive)”](#adding-non-interactive) Pass `--url` to skip the interactive prompt. The CLI checks reachability — use `--force` to bypass. A browser still opens for auth (agents should background this and notify the user). Use `--skip-auth` to skip auth entirely. Use `--scope user` to store the profile in `~/.ranger/` instead of the project. ```bash ranger profile add local --url http://localhost:3000 ranger profile add local --url http://localhost:3000 --force # skip reachability check ranger profile add local --url http://localhost:3000 --skip-auth # no browser auth ranger profile add local --url http://localhost:3000 --scope user # store in ~/.ranger/ ``` ### Updating [Section titled “Updating”](#updating) Update a profile when auth expires or you need a different user. Run `ranger profile update `. Ranger opens a browser with your current session if available. Log in again if needed, then close the browser to save the new auth. For CI profiles, this writes a new encrypted auth file. ## Electron and Desktop Apps [Section titled “Electron and Desktop Apps”](#electron-and-desktop-apps) Ranger can test Electron apps and other desktop applications that expose a Chrome DevTools Protocol (CDP) endpoint. Electron apps don’t have an HTTP URL — they’re native desktop processes. Instead of navigating a browser to a URL, Ranger connects to the app’s already-running Chromium renderer directly over CDP. This gives the browser verification agent full access to the app’s UI: it can take snapshots, click buttons, type text, and take screenshots, just like with a web app. ### How to set up an Electron profile [Section titled “How to set up an Electron profile”](#how-to-set-up-an-electron-profile) **1. Start your Electron app with remote debugging enabled:** ```bash your-electron-app --remote-debugging-port=9222 ``` Any port works. The app must be running before Ranger connects. **2. Add a profile using the `--cdp-endpoint` flag:** ```bash ranger profile add my-electron-app --cdp-endpoint http://localhost:9222 ``` Because there’s no URL to log into, `--cdp-endpoint` skips the URL reachability check and browser auth flow entirely. No browser opens during setup. **3. Run verifications normally:** ```bash ranger go --scenario 1 ``` The browser agent connects to your running Electron app via CDP, takes a snapshot of the current UI state, and starts interacting with it. ### Differences from web profiles [Section titled “Differences from web profiles”](#differences-from-web-profiles) | | Web profile | Electron (CDP) profile | | --------------- | --------------------- | -------------------------------- | | Setup | URL + browser login | CDP endpoint only | | Auth | Saved cookies | Not applicable | | Agent start | Navigates to base URL | Snapshots the existing app state | | URL restriction | Locked to base URL | No URL constraint | Because the app is already running and connected, the agent skips navigation and goes straight to interacting with the UI. ### Limitations [Section titled “Limitations”](#limitations) **Saved login sessions are not supported in CDP mode.** With web profiles, Ranger captures your login (cookies, localStorage, sessionStorage) and replays it into a fresh browser on each run. This isn’t possible with Electron apps — Ranger attaches to an already-running process rather than launching a new browser, so there’s no way to inject a saved session before the app starts. If your Electron app requires a logged-in user, handle that at the application level before Ranger connects (e.g., persist credentials to disk, use environment variables for auth tokens, or configure the app to skip login in development mode). ## Workflows with Multiple Profiles [Section titled “Workflows with Multiple Profiles”](#workflows-with-multiple-profiles) ### Testing interconnected apps [Section titled “Testing interconnected apps”](#testing-interconnected-apps) One use of multiple profiles is to handle feature reviews that involve scenarios in different but connected applications. For instance, if your customer-facing app runs on `localhost:3000` and your internal tool runs on `localhost:3001`, you could set up a profile for each of those endpoints and then tell your coding agent to use a specific one for each scenario. ```plaintext $ ranger profile add customer-app ? What is the URL of your running app? http://localhost:3000 Saving authentication state... ✓ Created settings Set active profile: customer-app Profile "customer-app" configured $ ranger profile add internal-app ? What is the URL of your running app? http://localhost:3001 Saving authentication state... ✓ Created settings Set active profile: internal-app Profile "internal-app" configured ``` ### Testing with different user types [Section titled “Testing with different user types”](#testing-with-different-user-types) Another use of multiple profiles is to run scenarios against different types of users. As an example, if your app has free, paid, and enterprise customers and you’re adding a feature that affects all of them, create a profile for each user type. All profiles can point at the same endpoint. Use the `Authentication Setup` step in the browser to log into a different account for each. Prompt your coding agent to use each of the profiles for a different scenario so that you can see each one in the Feature Review UI. # Using Scenarios > Describe what to verify Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how to access it. Unlike profiles, scenarios are generally written by the coding agent. If you enable Ranger while in Plan Mode, the coding agent should include the scenarios it believes are necessary in the plan for implementation. These can be iterated on until you think they capture the flows correctly. The scenarios are also visible and editable on the Feature Review dashboard. ## Scenarios Basics [Section titled “Scenarios Basics”](#scenarios-basics) A scenario is a short, concrete user flow with an expected result. Ranger’s browser agent treats it both as a path to follow and a success condition to verify against. Scenarios are not entirely deterministic and are guidance more than a script. Like people visiting a site, each agent may take a slightly different path to accomplish the goal it’s given and the amount of variance depends on the specificity of the task. For instance, “Mark a checklist item as completed. Verify that the text is crossed out and the box is checked.” leaves agents room to choose any non-completed checklist item. They would also successfully toggle a “non-completed only” filter if they had to in order to find an appropriate example. Each scenario is verified on its own. They are not done in the same browser session (so frontend state does not carry over) or necessarily in the same order. Running a scenario can be backgrounded by the agent, so multiple may be run at once. If they are likely to interfere with each other’s background data, prompt the coding agent to run them serially. ## Writing Scenarios [Section titled “Writing Scenarios”](#writing-scenarios) A good scenario names the starting point, the action, and the expected result. Scenarios can contain complex paths through the app, but are generally easiest to verify and understand if they don’t contain multiple conditions. **Clear**: “User opens settings, toggles dark mode, page switches to dark theme.” **Vague**: “Add dark mode toggle.” **Too many conditions**: “A user should see the toggle on the top of the page if they’re logged in and at the bottom otherwise.” ## Shaping the List [Section titled “Shaping the List”](#shaping-the-list) Most feature reviews need only a few scenarios. The scenarios should focus on frontend behaviors and observable UI. A long checklist might be indicative of too many implementation details. The most effective scenarios are focused on what a person would do and see. # Quickstart > Get Ranger Feature Review running in your project in about 5 minutes. Already set up? Head to the [Ranger Feature Review Dashboard](https://dashboard.ranger.net) to manage your feature reviews, or check out the [CLI Overview](/reference/cli-overview) for a full list of commands. Get Ranger Feature Review running in your project in about 5 minutes. By the end, your AI coding agent will be able to verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 18 or later * **Claude Code** (or your favorite AI coding agent) * A web application running locally (e.g., on `localhost:3000`) ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project’s root directory (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh ``` This installs the CLI and walks you through interactive setup. If you prefer to install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup ``` ** *Note: If `ranger` conflicts with another program on your system (e.g. the ranger file manager), you can use `ranger-cli` instead for all commands.* This walks you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or another non-interactive setting like an agent sandbox, see the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. The short version: pass a token directly (`ranger setup [token]`) or set the `RANGER_CLI_TOKEN` env var. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). If API keys are challenging in your setup, other approaches are available for enterprise customers — [get in touch](mailto:support@ranger.net). ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### Claude Code Plugin [Section titled “Claude Code Plugin”](#claude-code-plugin) The plugin connects Ranger to Claude’s workflow so it can use the Ranger CLI intuitively. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git (requires a `.claude/` directory). Not using Claude Code? This workflow is focused on Claude Code because that’s what we used when developing and testing it. We also have an OpenCode plugin & skill installation, see [Getting Started with OpenCode](/getting-started/quickstart-opencode). And the skills and CLI work for any coding agent with shell access. See [Supported Coding Agents](/getting-started/supported-agents/) for more detail on how we recommend configuring it for Cursor, Codex and more. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. ```plaintext Would you like to install skills? (Y/n) ``` Say **yes**. Skills are markdown files that get installed into your `.claude/skills/` directory. They tell Claude when and how to create feature reviews, run verifications, and address feedback. ### Profile [Section titled “Profile”](#profile) Ranger needs to know how to access your locally running app and how to authenticate. We manage that information in [profiles](/concepts/profiles). ```plaintext What is the URL of your running app? (http://localhost:3000) ``` Enter the URL where your app runs locally. Ranger checks that it’s reachable, then opens Chromium so you can log in to your app (if it requires authentication). **Close the browser when you’re done.** Ranger saves the session cookies so the verification agent can authenticate the same way. Your app needs to be running at this endpoint when you add the profile. If it’s not, you can run `ranger profile add local` when you’re ready to set it up. If your app doesn’t require login, you can close the browser immediately. *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open Claude Code in your project. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, run the slash command: ```plaintext /ranger:enable ``` This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask Claude to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, Claude will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, Claude fixes them and re-verifies automatically. 5. Once everything passes, Claude shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you run `/ranger:resume` in Claude Code.  ## What’s Next [Section titled “What’s Next”](#whats-next) * [Profiles](/concepts/profiles) define where to test and how to access it. * [Scenarios](/concepts/scenarios) are the user flows to guide the verification agent. * [CLI Overview](/reference/cli-overview) gives you (or your agent) extra info about all the available commands. * [CLI Overview](/reference/cli-overview/#authentication) covers all authentication options including CI tokens and managed platforms. # OpenCode Quickstart > Set up Ranger Feature Review with OpenCode. Get Ranger Feature Review running with OpenCode. By the end, your agent will verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Node.js 18 or later * OpenCode * A web application running locally ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project root (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh -s -- --opencode ``` This installs the CLI and runs interactive setup with OpenCode preconfigured. Or install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup --opencode ``` This command will walk you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or from a non-interactive agent, pass a token directly: `ranger setup --opencode [token]`. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). See also the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### OpenCode Plugin [Section titled “OpenCode Plugin”](#opencode-plugin) The plugin reminds OpenCode to use Ranger at various points in the workflow. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git. Under the hood, this adds the following block to your `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@ranger-testing/opencode-plugin"] } ``` For user scope, the config file is at `~/.config/opencode/opencode.json` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. For project scope, it’s at `.opencode/opencode.json` in your repo. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. Ranger installs skills automatically at the same scope you chose for the plugin. Skills are markdown files that tell your coding agent when and how to create feature reviews, run verifications, and address feedback. Project installs go to `.opencode/skills/`. User installs go to `~/.config/opencode/skills/` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. ### Profile [Section titled “Profile”](#profile) Ranger needs to know how to access your locally running app and how to authenticate. We manage that information in [profiles](/concepts/profiles). ```plaintext What is the URL of your running app? (http://localhost:3000) ``` If you’re in an interactive terminal, Ranger asks whether you want to set up the profile now. If you say yes, it asks for the URL where your app runs locally. Ranger checks that it’s reachable, then opens Chromium so you can log in to your app (if it requires authentication). **Close the browser when you’re done.** Ranger saves the session cookies so the verification agent can authenticate the same way. Your app needs to be running at this endpoint when you add the profile. If it’s not, you can run `ranger profile add local` when you’re ready to set it up. If your app doesn’t require login, you can close the browser immediately. *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open OpenCode in your project directory. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, tell your agent to `enable ranger`. This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask your coding agent to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, your coding agent will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, it fixes them and re-verifies automatically. 5. Once everything passes, it shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you ask it to `resume ranger` in OpenCode.  # Supported Coding Agents > Ranger works with Claude Code, OpenCode, Cursor, Codex, and any agent with shell access. Here's how to set up each one. Ranger Feature Review works with any coding agent that can run bash commands. The table below shows what’s supported out of the box and links to the setup instructions for each agent. | Agent | Plugin | Skills | Setup Command | | ----------------------------- | --------------------------------------- | ---------------------------------- | ------------------------- | | [Claude Code](#claude-code) | Yes (`ranger@trailhead`) | `.claude/skills/` | `ranger setup` | | [OpenCode](#opencode) | Yes (`@ranger-testing/opencode-plugin`) | `.opencode/skills/` | `ranger setup --opencode` | | [Cursor](#cursor) | No | `.cursor/skills/` (via sym link) | `ranger setup` | | [Codex](#codex) | No | `.codex/skills/` (via sym link) | `ranger setup` | | [Other agents](#other-agents) | No | directory of choice (via sym link) | `ranger setup` | In the setup instructions below, we provide commands to sym link the skills into the appropriate directory. It will also work to copy or move them, but the `ranger update` command will automatically update the skills to match new CLI versions and sym linking allows those updates to be immediately picked up by your coding agent. *** ## Claude Code [Section titled “Claude Code”](#claude-code) Claude Code is Ranger’s primary integration. The `ranger setup` command installs a Claude Code plugin and skills automatically. **Quickstart:** Follow the full [Quickstart](/getting-started/quickstart/) guide. **What you get:** * **Plugin** — Connects Ranger to Claude’s hook system. Ranger can automatically activate at the right moments in your workflow. * **Skills** — Markdown files installed to `.claude/skills/` that teach Claude how to create feature reviews, run verifications, and address feedback. * **Slash commands** — `/ranger:enable`, `/ranger:disable`, and `/ranger:resume` for quick control. *** ## OpenCode [Section titled “OpenCode”](#opencode) OpenCode has its own plugin and skill paths. Use the `--opencode` flag during setup. **Quickstart:** Follow the [OpenCode Quickstart](/getting-started/quickstart-opencode/) guide. **What you get:** * **Plugin** — The `@ranger-testing/opencode-plugin` package, configured in your `opencode.json`. * **Skills** — Markdown files installed to `.opencode/skills/`. * **Natural language activation** — Tell your agent to “enable ranger” instead of slash commands. *** ## Cursor [Section titled “Cursor”](#cursor) Cursor 2.4+ reads `.claude/skills/` for compatibility, so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the `.cursor/skills` directory: ```sh ln -s ~/.claude/skills/ranger ~/.cursor/skills/ranger ``` The skills work without a plugin, but you may have to remind the agent to use it after compaction or later in the context window. Invoke the skill with `/ranger` or `@ranger` in Cursor’s Agent chat (e.g. “Use @ranger to create a feature review and verify it”). *** ## Codex [Section titled “Codex”](#codex) Codex reads `.claude/skills/` (and `.codex/skills/`), so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the Codex skills directory: ```sh ln -s ~/.claude/skills/ranger ~/.codex/skills/ranger ``` Codex’s default permissions mode blocks most network access, so Ranger will fail until permissions are adjusted. For an individual session, the slash command `/permissions` will allow you to update to Full Access. For a more enduring fix, you can add Ranger and network permissions by default: ```sh echo 'prefix_rule(pattern=["ranger"], decision="allow")' >> ~/.codex/rules/default.rules ``` and update `~/.codex/config.toml` with: ```plaintext sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true ``` *** ## Other Agents [Section titled “Other Agents”](#other-agents) Any coding agent that can execute bash commands can use Ranger. The core workflow is: 1. Install CLI and authenticate: `npm install -g @ranger-testing/ranger-cli && ranger setup` 2. Install skills: Say yes when prompted, or run `ranger skillup` separately. Skills are installed to `.claude/skills/ranger/` by default. 3. (optional) Link skills: if your agent looks for skills in a specific directory, sym link the ranger skill into that directory. 4. Use the CLI: Your agent runs `ranger create`, `ranger go`, `ranger show`, etc. The skill files are plain markdown — they work as instructions for any LLM-based agent. Want a dedicated integration? If you’re using an agent or harness that would benefit from an integration, [let us know](mailto:eng@ranger.net)! # Background Agent and CI Setup > Run Ranger in hosted environments — background agents running on isolated VMs, and CI pipelines. Beta   > **This feature is in beta.** We are actively developing background agent and CI support. If you’d like to get started using Ranger with a background agent, [reach out to us](mailto:eng@ranger.net) and we’ll help you set it up. This guide covers running Ranger in hosted environments, including background agents running on isolated VMs, and CI workflows (GitHub Actions, GitLab CI, etc.). The same steps apply regardless of the platform - anywhere you can run Node.js and a headless browser. Ranger works with any coding agent that can execute bash commands — Claude Code, OpenCode, Codex, or any other agent with shell access. ## A Note on Auth [Section titled “A Note on Auth”](#a-note-on-auth) The challenge for running in non-tty environments is authentication. The verification usually needs to happen in a logged-in context, which is where human intervention usually comes into play. We have two main approaches to make this work. ### One-Time CI Profile Creation [Section titled “One-Time CI Profile Creation”](#one-time-ci-profile-creation) The first option is to manually login to the app once, save the session state, and encrypt it so that it can be committed and used in different environments. This works well in situations where sessions are long-lived or a bot bypassing auth is not possible. ### Login Instructions [Section titled “Login Instructions”](#login-instructions) The second option is to give Ranger “login instructions” that it can use to construct its own auth state. This is a very flexible and open-ended option but may take more customization to set up. Some options that users have configured with login instructions include using a username and password or hitting a specific endpoint to obtain a token to include in an auth header. The options here are fairly unlimited ## Overview [Section titled “Overview”](#overview) The setup has two parts: a **one-time local setup** (creating a CI profile and committing it), and the **hosted environment itself** (installing tools, activating the profile, and running your coding agent with Ranger). ## Option A: One-Time CI Profile Creation (configure locally) [Section titled “Option A: One-Time CI Profile Creation (configure locally)”](#option-a-one-time-ci-profile-creation-configure-locally) ### 1. Create a CI profile [Section titled “1. Create a CI profile”](#1-create-a-ci-profile) Run this on your local machine, from your project root. Here we name the profile `preview` - you can use any name, but the rest of this guide assumes `preview`. ```bash ranger profile add preview --ci ``` This will open a browser pointed at your app’s URL. **Log in to the environment that the hosted agent will verify against** (e.g. your staging or preview deployment). The browser session cookies are captured and encrypted — these are the exact cookies Ranger will use to authenticate in the hosted environment, so they must be valid for the target URL. The encrypted auth state is saved to `.ranger/ci/preview/`: ```plaintext .ranger/ci/preview/ settings.json # baseUrl and browser config auth.json.enc # encrypted auth state (safe to commit) ``` #### Dynamic base URLs [Section titled “Dynamic base URLs”](#dynamic-base-urls) If your deployment URL changes per environment (e.g. Vercel preview URLs, Heroku review apps), you can use `${VAR_NAME}` syntax in your profile’s `baseUrl`. Ranger resolves environment variables at runtime. When running `ranger profile add preview --ci`, enter the URL of a representative deployment (e.g. your current staging URL). This is needed so you can log in and capture valid auth cookies. After the profile is created, update the `baseUrl` to use a variable: > **Note:** The cookies captured during login must be valid for all target deployments. If your staging and preview environments use different auth providers or cookie domains, the captured cookies won’t work across them. ```bash ranger profile config set preview baseUrl '${PREVIEW_URL}' ``` The auth cookies captured during setup will still be used — only the URL changes at runtime. This works as long as the cookies are valid across deployments (e.g. same domain, shared auth provider). At runtime, Ranger replaces `${PREVIEW_URL}` with the value of that environment variable: ```bash export PREVIEW_URL=https://my-app-pr-123.vercel.app ``` This works for any settings value, not just `baseUrl`. For example, you can use env vars in custom headers: ```bash ranger profile config set preview header.Authorization '${AUTH_TOKEN}' ``` ### 2. Commit the profile to version control [Section titled “2. Commit the profile to version control”](#2-commit-the-profile-to-version-control) ```bash git add .ranger/ci/ git commit -m "Add Ranger CI profile" ``` If you use encrypted auth, `auth.json.enc` can only be decrypted at runtime using your Ranger API token, so it’s safe to store in git. ## Option B: `loginInstructions` (no saved session) [Section titled “Option B: loginInstructions (no saved session)”](#option-b-logininstructions-no-saved-session) If your app uses short-lived cookies/tokens or a custom auth bootstrap endpoint, configure `loginInstructions` instead of relying on a long-lived encrypted browser session. Create the CI profile without capturing login state: ```bash ranger profile add preview --skip-auth ``` Then set login instructions that Ranger will run before every verification: ```bash ranger profile config set preview loginInstructions 'Navigate to ${PREVIEW_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token.' ``` `loginInstructions` supports environment variables and works with any auth mechanism (debug endpoints, token injection, API-key bootstrap, etc.). ### 2. Make secrets available to the environment [Section titled “2. Make secrets available to the environment”](#2-make-secrets-available-to-the-environment) Your environment needs this secret: | Secret | Description | | ------------------ | ---------------------------------------------------------------------------------------------- | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth and decrypting the encrypted auth state. | You’ll also need an API key for whatever coding agent you use (e.g. `ANTHROPIC_API_KEY` for Claude Code). If your `loginInstructions` references environment variables, provide those as well. How you provide these depends on your platform - GitHub repo secrets, GitLab CI variables, environment variables in a VM, etc. ## Environment Setup Steps [Section titled “Environment Setup Steps”](#environment-setup-steps) These are the steps your environment needs to run, in order. The commands below are plain bash — adapt them to your platform’s syntax. ### 1. Check out the repository [Section titled “1. Check out the repository”](#1-check-out-the-repository) Clone with full git history (needed if you want to generate diffs): ```bash git clone ``` ### 2. Install Node.js [Section titled “2. Install Node.js”](#2-install-nodejs) Ranger CLI requires Node.js 18+. ### 3. Install project dependencies [Section titled “3. Install project dependencies”](#3-install-project-dependencies) ```bash npm install ``` ### 4. Install a virtual display (Linux only) [Section titled “4. Install a virtual display (Linux only)”](#4-install-a-virtual-display-linux-only) Ranger runs a headless Chromium browser. On Linux environments without a display server, you need Xvfb: ```bash apt-get install -y xvfb Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 ``` Not needed on macOS or environments with a display server. ### 5. Install your coding agent and Ranger CLI [Section titled “5. Install your coding agent and Ranger CLI”](#5-install-your-coding-agent-and-ranger-cli) Install Ranger CLI globally, along with whatever coding agent you’re using: ```bash npm install -g @ranger-testing/ranger-cli # Plus your coding agent, e.g.: npm install -g @anthropic-ai/claude-code ``` ### 6. Install Chromium and authenticate [Section titled “6. Install Chromium and authenticate”](#6-install-chromium-and-authenticate) Pass your Ranger API token to the setup command. In non-interactive mode, this authenticates and installs the Playwright Chromium browser: ```bash export RANGER_CLI_TOKEN= ranger setup $RANGER_CLI_TOKEN ``` See [Authentication](/reference/cli-overview/#authenticating-the-ranger-cli-to-ranger) for all auth options. #### Separating install from auth (Docker / custom images) [Section titled “Separating install from auth (Docker / custom images)”](#separating-install-from-auth-docker--custom-images) If you’re building a container image, you can install Chromium and dependencies at **build time** (no token needed), then authenticate at **runtime**: ```dockerfile # -- Build time: bake deps into the image -- FROM node:20 RUN npm install -g @ranger-testing/ranger-cli @anthropic-ai/claude-code RUN ranger setup deps --with-deps ``` `ranger setup deps` installs Chromium without requiring authentication or a git repo. `--with-deps` tells Playwright to also install OS-level libraries (fonts, libx11, etc.) that headless Chromium needs on Debian/Ubuntu. At runtime, authenticate and set up skills: ```bash # -- Runtime: per-user or per-job auth -- export RANGER_CLI_TOKEN= ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ranger profile use preview ``` Each subcommand runs only its phase — `login` handles auth, `skills` installs the Claude Code plugin and skill files. You can also still use `ranger setup $RANGER_CLI_TOKEN` to run everything at once. ### 7. Activate the CI profile [Section titled “7. Activate the CI profile”](#7-activate-the-ci-profile) Tell Ranger to use the CI profile you committed in the one-time setup: ```bash ranger profile use preview ``` If the profile includes `auth.json.enc`, Ranger decrypts it at runtime using `RANGER_CLI_TOKEN`. If the profile uses `loginInstructions`, Ranger follows those instructions before each verification run. ### 8. Install Ranger skills [Section titled “8. Install Ranger skills”](#8-install-ranger-skills) Install the Ranger skill files that teach your coding agent how to create feature reviews and run verifications: ```bash ranger skillup ``` This places skill markdown files in `.claude/skills/` (compatible with any agent that reads skill files from the project directory). ### 9. Configure your coding agent’s permissions [Section titled “9. Configure your coding agent’s permissions”](#9-configure-your-coding-agents-permissions) Your coding agent needs permission to run bash commands (for `ranger`, `gh`, `git`, etc.) and read files. How you configure this depends on your agent. **Claude Code example** — write `.claude/settings.local.json`: ```json { "permissions": { "allow": ["Bash(*)", "Read(*)", "Glob(*)", "Grep(*)"], "deny": [] } } ``` Other agents may need equivalent configuration, or may not require it at all. ### 10. Run your coding agent with Ranger [Section titled “10. Run your coding agent with Ranger”](#10-run-your-coding-agent-with-ranger) Invoke your coding agent in non-interactive mode with a prompt that tells it to use the Ranger skill. The skill files teach the agent how to create feature reviews, write scenarios, and run browser verification. Here are two possible use cases: #### CI workflow: Bug bash a PR’s changes [Section titled “CI workflow: Bug bash a PR’s changes”](#ci-workflow-bug-bash-a-prs-changes) Trigger on every pull request. The agent reads the diff, creates scenarios based on what changed, and verifies them in the browser. Results get posted as a PR comment. ```bash claude --print "Look at the git diff for this branch against main. \ Use the /ranger skill to create a feature review from the UI changes \ and verify each scenario. Post results as a PR comment using gh." ``` #### Background agent: Build and verify a feature [Section titled “Background agent: Build and verify a feature”](#background-agent-build-and-verify-a-feature) Give a coding agent a feature task and let it implement the code, then verify its own work in the browser before reporting back. ```bash claude --print "Read the task requirements and document a plan in docs/feature/{feature-name}.md. \ Implement the feature in the codebase, referencing the original task for context. \ Commit changes and push to the current branch. \ Use the Ranger skill to authenticate against the current environment and verify the feature works end-to-end in the browser." ``` ## Updating the Encrypted Profile [Section titled “Updating the Encrypted Profile”](#updating-the-encrypted-profile) When your app’s auth expires or login flow changes, update the profile locally: ```bash ranger profile update preview ``` Then commit the updated `.ranger/ci/preview/auth.json.enc`. If you use `loginInstructions`, update the instruction text instead: ```bash ranger profile config set preview loginInstructions "" ``` ## Limitations [Section titled “Limitations”](#limitations) * **Encrypted auth state doesn’t auto-refresh.** The encrypted `auth.json.enc` is a snapshot of browser cookies/session from when you ran `ranger profile add`. If your app’s sessions expire, you’ll need to re-run `ranger profile update preview` locally and commit the updated file, or switch to `loginInstructions`. * **`loginInstructions` must stay valid.** If the bootstrap endpoint, login flow, or required env vars change, update `loginInstructions` in the profile settings. * **One profile per environment.** Each CI profile is tied to a single base URL and auth config. If you need to verify against multiple environments (e.g. staging and production), create separate profiles (`ranger profile add staging --ci`, `ranger profile add production --ci`). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### “No CI profiles found” [Section titled ““No CI profiles found””](#no-ci-profiles-found) Make sure `.ranger/ci/preview/` is committed to git with both `settings.json` and `auth.json.enc`. ### “Failed to verify encrypted auth” [Section titled ““Failed to verify encrypted auth””](#failed-to-verify-encrypted-auth) The `RANGER_CLI_TOKEN` must belong to the same organization as the token used when the profile was created. ### Coding agent blocks commands [Section titled “Coding agent blocks commands”](#coding-agent-blocks-commands) Some agents sandbox tool calls by default. Make sure your agent has permission to run bash commands before invoking it. For Claude Code, this means writing `.claude/settings.local.json` (see step 9). ### Browser fails to launch [Section titled “Browser fails to launch”](#browser-fails-to-launch) On Linux, make sure Xvfb is running and `DISPLAY` is set before the agent starts. Chromium needs a display server even in headless mode on some configurations. ### Vercel preview environments return 401/403 [Section titled “Vercel preview environments return 401/403”](#vercel-preview-environments-return-401403) Vercel’s [Deployment Protection](https://vercel.com/docs/deployment-protection) blocks automated access to preview URLs by default. To bypass it, generate a protection bypass token in your Vercel project settings and add it as a custom header on the profile: ```bash ranger profile config set preview header.x-vercel-protection-bypass '' ``` See [Vercel’s bypass automation docs](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) for how to generate the token. ## Example: GitHub Actions Workflow [Section titled “Example: GitHub Actions Workflow”](#example-github-actions-workflow) A complete workflow using Claude Code. Copy to `.github/workflows/ranger-pr-verify.yaml`. **Required secrets** (Settings > Secrets and variables > Actions): * `RANGER_CLI_TOKEN` — Your Ranger API token * `ANTHROPIC_API_KEY` — Anthropic API key for Claude Code ```yaml name: Ranger PR Verification on: pull_request: types: [opened, synchronize, reopened] workflow_dispatch: inputs: pr_number: description: 'PR number to verify (optional, uses current branch if empty)' required: false type: string env: HUSKY: 0 jobs: verify: name: Ranger PR Verification runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm install - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y xvfb - name: Install Claude Code and Ranger CLI run: npm install -g @anthropic-ai/claude-code @ranger-testing/ranger-cli - name: Setup Ranger CLI env: RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} run: ranger setup ${{ secrets.RANGER_CLI_TOKEN }} - name: Activate CI profile run: ranger profile use preview - name: Configure Claude Code permissions run: | mkdir -p .claude cat > .claude/settings.local.json << 'EOF' { "permissions": { "allow": [ "Bash(*)", "Read(*)", "Glob(*)", "Grep(*)" ], "deny": [] } } EOF - name: Run Ranger verification env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} DISPLAY: ':99' GH_TOKEN: ${{ github.token }} run: | Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 sleep 2 claude --print "Look at the git diff for this branch against main. Use the /ranger skill to create a feature review from the changes and verify each scenario. Post results as a PR comment using gh." timeout-minutes: 30 ``` # CLI Overview > All Ranger CLI commands at a glance. The Ranger CLI (`@ranger-testing/ranger-cli`) is the primary tool for setting up, managing, and running Ranger in your project. Install it globally: ```bash npm install -g @ranger-testing/ranger-cli ``` This page covers all commands at a human-readable level. Your AI coding agent has its own detailed skill docs, so you don’t need to memorize flags. ## Setup [Section titled “Setup”](#setup) | Command | What it does | | --------------- | -------------------------------------------------------------------------------- | | `ranger setup` | Full interactive setup: auth, Chromium, plugin, profile, skills. Run this first. | | `ranger login` | Re-authenticate without running full setup again. | | `ranger status` | Show everything: version, org, plugin status, skills, profiles. | | `ranger update` | Update the CLI to the latest version and refresh installed skills. | | `ranger clean` | Remove all Ranger artifacts from the project (nuclear option). | ### `ranger setup` [Section titled “ranger setup”](#ranger-setup) The recommended way to get started. Run it in your project root (should be a git repo for feature review tracking) and it walks you through: 1. Browser-based authentication (or pass a token for CI: `ranger setup [token]`) 2. Chromium installation for browser verification 3. Claude Code plugin installation 4. Profile setup (your app’s URL + login) 5. Skill installation If you skip any step, you can run it individually later — each phase is also available as a subcommand. #### Subcommands [Section titled “Subcommands”](#subcommands) | Command | What it does | | ----------------------- | ------------------------------------------------------------------------------------------ | | `ranger setup` | Full interactive setup (default). | | `ranger setup all` | Explicit full setup — same as bare `ranger setup`. | | `ranger setup deps` | Install Chromium only. No auth, no git repo required. Use `--with-deps` for OS packages. | | `ranger setup login` | Authenticate only. Use `--token ` or `--mcp` for non-interactive auth. | | `ranger setup skills` | Install Claude Code plugin and skills only. Use `--scope user\|project`, `--opencode`. | | `ranger setup profiles` | Set up a local browser profile only. Use `--url`, `--force`, `--allow-insecure-localhost`. | #### Non-interactive mode [Section titled “Non-interactive mode”](#non-interactive-mode) Individual subcommands are the preferred way to script setup in containers and CI: ```bash # Docker build time — no auth needed ranger setup deps --with-deps # Runtime — auth and skills ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` The full `ranger setup` command also accepts flags for non-interactive use: | Flag | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `--scope user\|project` | Install scope for plugin, skills, and profile (defaults to `user`). `user` keeps everything in your home directory; `project` stores in the repo. | | `--url ` | Base URL for profile setup. A browser still opens for auth. | | `--force` | Skip URL reachability check. | | `--skip-chromium` | Skip Chromium installation. | | `--skip-auth` | Skip authentication — install deps only. Useful for container/CI image builds where auth happens at runtime. | | `--with-deps` | Install OS-level dependencies for Chromium (apt packages for Debian/Ubuntu). Pair with `--skip-auth` for container builds. | | `--allow-insecure-localhost` | Allow localhost content in deployed environments (micro frontends). | | `--mcp-bootstrap` | Bootstrap auth via an MCP auth server instead of browser login. Used by managed agent platforms and MCP-compatible tools. | ```bash ranger setup $TOKEN --scope project --url http://localhost:3000 ``` #### Headless / Scripted Setup [Section titled “Headless / Scripted Setup”](#headless--scripted-setup) For Docker containers and CI images, use subcommands to separate build-time deps from runtime auth: ```dockerfile # Dockerfile (build time) RUN npm install -g @ranger-testing/ranger-cli RUN ranger setup deps --with-deps ``` ```bash # Runtime startup script ranger setup login --token $RANGER_CLI_TOKEN # or: ranger setup login --mcp ranger setup skills --scope user ranger profile use preview ``` ### Authenticating the Ranger CLI to Ranger [Section titled “Authenticating the Ranger CLI to Ranger”](#authenticating-the-ranger-cli-to-ranger) **Interactive (laptops, developer machines)** `ranger setup` opens a browser for login. The CLI manages token refresh automatically. If your session expires, run `ranger login` to re-authenticate. **CI and scripted environments** Pass an API token from your [Ranger Dashboard](https://dashboard.ranger.net/cli): ```bash ranger setup ``` Or set the `RANGER_CLI_TOKEN` environment variable — the CLI reads it automatically. **MCP authentication** The CLI can authenticate via MCP, which may be useful in non-interactive environments where you would like the Ranger CLI to act on a real user’s behalf: ```bash ranger setup --mcp-bootstrap ``` Set `RANGER_MCP_AUTH_URL` to point at your platform’s MCP proxy if applicable. [Contact us](mailto:support@ranger.net) for setup guidance. ### Logging the CLI into your App (Profiles) [Section titled “Logging the CLI into your App (Profiles)”](#logging-the-cli-into-your-app-profiles) CLI auth (above) identifies *you* to the Ranger API. Separately, the browser agent needs to log in to *your app* so it can verify features. This is handled by [Profiles](/concepts/profiles) — when you run `ranger profile add`, you log in to your app in a browser, and Ranger saves the session cookies. | Command | What it does | | --------------------------------------- | ------------------------------------------------------------ | | `ranger profile encrypt-auth ` | Encrypt a profile’s auth.json for safe git storage (CI use). | See [Managing Profiles](/concepts/profiles) for full details on login instructions. ## Profiles [Section titled “Profiles”](#profiles) Profiles tell Ranger how to access your application: the URL, authentication cookies, and browser settings. | Command | What it does | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ranger profile add ` | Add a new profile. Opens a browser for you to log in. Supports `--url`, `--force`, `--ci`, `--skip-auth`, `--cdp-endpoint`, `--allow-insecure-localhost`, `--safe-mode`, `--setup-header`, `--scope user\|project`. | | `ranger profile use ` | Switch which profile is active. | | `ranger profile ls` | List all profiles with their URLs and status. | | `ranger profile update ` | Re-capture authentication for an existing profile. Supports `--allow-insecure-localhost`. | | `ranger profile encrypt-auth ` | Encrypt auth.json for safe git storage (CI use). | Adding a profile with `--ci` creates an encrypted auth file that’s safe to commit to git. Use `--cdp-endpoint` to connect to an Electron app or existing browser via Chrome DevTools Protocol instead of a URL. See [Managing Profiles](/concepts/profiles) for details. ## Profile Config [Section titled “Profile Config”](#profile-config) Fine-tune browser behavior per profile. | Command | What it does | | --------------------------------------------------- | ------------------------------ | | `ranger profile config set ` | Set a config value. | | `ranger profile config get ` | Read a config value. | | `ranger profile config list ` | Show all config for a profile. | | `ranger profile config unset ` | Remove a config value. | Supported keys: `headless` (true/false), `allowInsecureLocalhost` (true/false), `safeMode` (true/false, disables browser features like Bluetooth that can cause crashes on some systems), `userAgent`, `storageState`, `cdpEndpoint`, `loginInstructions`, `header.` (custom HTTP headers sent with every request), `setupHeader.` (HTTP headers sent only during profile setup auth — see below). ```bash ranger profile config set local headless true ranger profile config set local allowInsecureLocalhost true ranger profile config set ci header.Authorization '${AUTH_TOKEN}' ranger profile config set my-electron-app cdpEndpoint http://localhost:9222 ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' ``` Environment variables like `${AUTH_TOKEN}` are resolved at runtime. ### Setup-Only Headers [Section titled “Setup-Only Headers”](#setup-only-headers) Some apps require a custom HTTP header to bypass login protection (e.g. Cloudflare Turnstile) during initial setup, but that header causes problems if sent on every request during test runs (e.g. CORS failures with third-party services). Use `setupHeader.` to set headers that are only sent during the `ranger profile add` auth browser session: ```bash # Via config (applied on next profile add) ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' # Or inline during profile creation ranger profile add local --url https://app.example.com --setup-header "x-bypass-turnstile: a1b2c3d4..." ``` These headers are persisted in the profile and reused when you re-add or overwrite the profile. They are **not** sent during `ranger go` verification runs. ### Custom Login Instructions [Section titled “Custom Login Instructions”](#custom-login-instructions) If your app uses short-lived cookies or tokens that expire before Ranger can use them, you can provide custom login instructions instead of relying on saved auth state. Set `loginInstructions` to tell the Ranger agent how to authenticate before each verification run: ```bash ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', ''). Refresh the page." ``` The agent will follow these instructions as a mandatory first step before every verification. This works with any auth mechanism — local debug endpoints, API keys, token injection, etc. Environment variables are supported: ```bash ranger profile config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token." ``` ## Feature Reviews [Section titled “Feature Reviews”](#feature-reviews) Feature reviews are the core unit of work in Ranger. Each feature review has a name, description, and scenarios to verify in the browser. | Command | What it does | | ------------------------------ | -------------------------------------------------------------------------------------- | | `ranger create ""` | Create a new feature review. Use `-c` for scenarios, `-d` for description. | | `ranger list` | List feature reviews. Use `--current-branch` to filter by your git branch. | | `ranger show` | Show the active feature review’s status and scenarios. | | `ranger resume ` | Set a feature review as active and start its session. | | `ranger add-scenario ""` | Add a scenario to the active feature review. | | `ranger get-review` | Show unaddressed reviewer comments across all scenarios. | | `ranger report [id]` | Generate PR description markdown with screenshots. Use `--json` for structured output. | | `ranger delete` | Soft delete the active feature review. | | `ranger restore ` | Restore a soft-deleted feature review. | ### Creating a Feature Review [Section titled “Creating a Feature Review”](#creating-a-feature-review) ```bash ranger create "Dark Mode Toggle" \ -d "Add dark mode support to settings page" \ -c "User opens settings, toggles dark mode, and the page switches themes" ``` Feature reviews auto-detect your git repo and branch. The feature review becomes active immediately. ### Resuming Work [Section titled “Resuming Work”](#resuming-work) At the start of a session, check for existing feature reviews: ```bash ranger list --current-branch ranger resume feat_abc123 ``` ### Generating Reports [Section titled “Generating Reports”](#generating-reports) `ranger report` generates a PR description from the active feature review’s verified scenarios, including screenshots. ```bash ranger report ranger report feat_abc123 ``` By default, output is markdown. Use `--json` for structured output that other tools can consume: ```bash ranger report --json ``` The JSON output contains the feature review dashboard URL and an array of scenarios: ```json { "url": "https://dashboard.ranger.net/features/feat_...", "scenarios": [ { "description": "string", "result": "verified | incomplete | blocked | in_progress | pending | approved | cancelled | superseded | closed", "rationale": "string | null", "steps": [ { "description": "string", "screenshot": "string (URL) | null", "is_key_step": true } ] } ] } ``` `result` reflects the scenario’s verification status. `rationale` is the agent’s response or the reason for a blocked/incomplete/cancelled status. Each step includes a screenshot URL when available; `is_key_step` marks the most important moments. Use `--exclude` to omit specific scenarios by number (1-based): ```bash ranger report --exclude 2 4 ``` ## Verification [Section titled “Verification”](#verification) `ranger go` spawns a browser agent to test your scenarios. ```bash ranger go ``` The CLI prompts you to select which scenario to verify. The browser agent navigates your app, interacts with the UI, takes screenshots, and returns a verdict (verified, partial, blocked, or failed). Common options: * `--scenario `: skip the selection prompt, verify scenario N directly (1-based) * `--notes ""`: override what the agent does (defaults to the scenario description) * `--start-path /settings`: start the agent on a specific page instead of the base URL * `--profile `: use a specific profile instead of the active one * `--headed`: force a headed browser for this run only (does not change profile config) ## In Claude Code [Section titled “In Claude Code”](#in-claude-code) These aren’t CLI commands. They’re slash commands inside Claude Code: | Command | What it does | | ----------------- | -------------------------------------------------------------------- | | `/ranger:enable` | Enable Ranger hooks for this session and branch. | | `/ranger:disable` | Disable Ranger hooks. | | `/ranger` | Invoke the Ranger skill (create, verify, or manage feature reviews). | Ranger stays enabled on your branch across sessions (except on `main`/`master`, where it’s session-only). You only need to enable once per branch. # Hook System > How Ranger integrates with Claude Code through automatic hooks. Ranger integrates with Claude Code through hooks: automatic triggers that fire at key moments in the coding session. Hooks guide Claude through the Feature Review workflow without requiring you to remember commands or prompt for it repeatedly. The Claude Code plugin should be automatically installed when you run `ranger setup`. If you need to re-install them at any point, you can run: ```plaintext /plugin marketplace add ranger-testing/trailhead /plugin install ranger@trailhead ``` from inside Claude or: ```plaintext claude plugin marketplace add ranger-testing/trailhead claude plugin install ranger@trailhead ``` from the terminal. After installing, you may need to restart Claude Code before you can use the plugin. ## Why Hooks [Section titled “Why Hooks”](#why-hooks) We started with just the skills and discovered that Claude kept forgetting to use `ranger` and would return to us with errors that would have been caught with verification. We temporarily solved that with careful and repeated prompting, but wanted to automate it. Claude Code plugins offer “hooks” that can be used to remind Claude–if relevant–to use Ranger and check its work before returning to the user. We’ve found that enabling hooks whenever we’re working on UI-related work has dramatically improved Claude’s reliability with Feature Review. ## Opt-In Model [Section titled “Opt-In Model”](#opt-in-model) Hooks are **off by default**. Run `/ranger:enable` in Claude Code to activate them for your current session and branch. Once enabled on a branch, Ranger stays enabled across sessions. Use `/ranger:disable` to explicitly turn hooks off. On `main`/`master`, hooks only enable at the session level (not branch-persisted), since these branches are shared. ## Hook Reference [Section titled “Hook Reference”](#hook-reference) | Hook | When It Fires | What It Does | | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **session-start** | Session created | Checks if the branch is enabled; auto-enables if so. | | **session-end** | Session ended | If reason is `/clear` and session was enabled, auto-enables on next session. | | **enable** | `/ranger:enable` | Runs `ranger update`, enables session + branch, outputs the full skill content to Claude’s context. | | **disable** | `/ranger:disable` | Disables session + branch, tells Claude to stop using Ranger commands. | | **stop** | Session stopping | If the active feature review still has unfinished items, adds a non-blocking reminder to verify before replying, unless verification is already running. If items are terminal, it tries to conclude the session. Fails open on conclude errors. | | **post-edit** | After file write/edit | If Ranger is enabled but no feature review is registered, suggests using `/ranger`. If a feature review exists, hints about adding scenarios if scope expanded. | | **pre-compact** | Before context compaction | Reminds Claude to preserve the Ranger Feature Review Specification in the compacted summary. | | **plan-start** | Entering plan mode | Instructs Claude to include a Ranger Feature Review Specification in the plan. | | **exit-plan-mode** | Leaving plan mode | Reminds Claude to create the feature review with `ranger create` before starting implementation. | # Ranger Feature Review > Automated browser verification and feature review for agentic development. [Ranger](https://www.ranger.net) is the always-on AI QA platform for teams that gives you higher signal, less noise, and faster launches. Ranger Feature Review brings that QA expertise to agentic development. When you ask an AI coding agent to build a feature, Ranger verifies it actually works in a real browser, with real evidence, and gives your team a way to review it collaboratively. ## Demo [Section titled “Demo”](#demo) Want to see it in action? Here’s a quick demo. [Ranger Feature Review Demo](https://www.youtube.com/embed/TB6eHLGtaD4) ## The Problem [Section titled “The Problem”](#the-problem) When you ask Claude to build a feature, it might come back to you with a fully working feature, but you can’t tell until you open your app and click through the full workflow involved. And half the time, it writes code that can’t even be built or fails as soon as the page is loaded. ## How Ranger Feature Review Fixes This [Section titled “How Ranger Feature Review Fixes This”](#how-ranger-feature-review-fixes-this) Ranger acts as your AI agent’s QA team. When your coding agent says it’s done, Ranger runs local browser agents that step through your user flows and verify your features truly look and work the way they’re supposed to. ### 1. Automated Browser Verification [Section titled “1. Automated Browser Verification”](#1-automated-browser-verification) Before your agent says “done,” Ranger tests the feature in a real browser. If something’s broken, Ranger tells the agent to fix it automatically. The agent keeps iterating until Ranger confirms everything works. ### 2. Feature Review Dashboard [Section titled “2. Feature Review Dashboard”](#2-feature-review-dashboard) Every verification produces evidence: screenshots, video recordings, and Playwright traces. Ranger presents this in a review interface (think GitHub PR review, but for UI features). You and your team can browse the evidence, leave comments, approve, or request changes. ### 3. One-Click E2E Tests [Section titled “3. One-Click E2E Tests”](#3-one-click-e2e-tests) Once a feature is verified and approved, you’re one click away from turning it into a permanent end-to-end test in your Ranger test suite. ## The Development Cycle [Section titled “The Development Cycle”](#the-development-cycle) When you start working on something new, create a `feature review` with the Ranger CLI that describes what should be verified (this is a natural extension of an agent’s Plan mode). After your agent writes code, it should automatically run `ranger go` to walk through the flows, capturing evidence of everything it encounters. If everything works, great! Your agent can wrap up, let you know it’s done, and you can take a look at the Ranger Feature Review link to get a walkthrough and ask for changes. If the browser agent finds an issue, it’ll describe it to your coding agent and they’ll iterate until it works or your coding agent decides the work is fully blocked and it needs a human in the loop.  Hey Agents Sound interesting? We’ve got docs just for you. Take a look at [llms.txt](llms.txt). ## Get Started [Section titled “Get Started”](#get-started) * [Quickstart](/getting-started/quickstart). Set up Ranger in 5 minutes and verify your first feature review. * [OpenCode Quickstart](/getting-started/quickstart-opencode). Use OpenCode instead? We can work with that. * [Supported Coding Agents](/getting-started/supported-agents). Using Cursor, Codex, or another agent? Find setup instructions here. * [How It Works](/concepts/how-it-works). The architecture: CLI, plugin, browser agents, and dashboard. * [Ranger In Autonomous Loops](/concepts/autonomous-loop). How Ranger Feature Review supports more autonomous agentic coding. # Autonomous Coding Loops > How Ranger fits into agentic development As our team has experimented with agentic development, we’ve come to the same conclusion as many others: an agent needs tools to verify its own work. The more effective those tools are, the longer an agent can productively run and stay on track. An agent that can verify its own work as it goes can ask for less direction and is much more likely to return with a mostly done (and mostly correct) result. Many tools exist to help agents verify their work. The most obvious ones are exactly the same ones that humans use – compilers, type checkers, tests. But UI development is different. Human developers examine results visually, interact with them, navigate through flows. This is a harder step for an agent. Playwright (often via Playwright MCP) is a powerful tool to give an agent insight into the browser experience. But it also incredibly context-hungry and testing multiple or repeated flows very often blows through the context and leads to repeated compactions and the corresponding loss of fidelity. An agent that spends most of its context on browser navigation has little left for the actual coding. ## Separating verification from coding [Section titled “Separating verification from coding”](#separating-verification-from-coding) Ideally, verification should be a separate process that’s hands-off for the coding agent. The agent kicks off a verification task, gets structured results back, and keeps its context for the work that matters: reading code, reasoning about architecture, writing changes. That’s what Ranger Feature Review does for browser-based verification. It does this by spawning a separate browser agent for each verification. This agent has its own context window and its own Playwright session, meaning that it doesn’t distract from coding and many can be run in parallel. The only job of each of these agents is to navigate the app and determine whether a specific behavior works. It returns a verdict (verified, failed, partial, or blocked) along with screenshots, video, and traces. The coding agent never touches the browser directly. This has a practical consequence: the write-verify loop can run many times without degrading. A coding agent using Playwright MCP might get three or four verification cycles before context pressure forces a compaction. With verification offloaded, the coding agent can iterate dozens of times and still have full recall of the codebase, the task, and its earlier decisions. ## Running without supervision [Section titled “Running without supervision”](#running-without-supervision) This also changes what it means to supervise an agent. With inline browser testing, you’re often watching the session because the agent will go off track after a compaction or two. When verification runs separately and returns structured results, the agent can self-correct reliably. It reads the verdict, looks at the failure reason, fixes the code, and verifies again. This is a loop that works while you’re not watching. This matters most for long-running sessions and background agents. If you kick off an agent before stepping away, you want to come back to a result, not a question. An agent with reliable UI verification can work through a feature end-to-end: implement the code, verify it in the browser, read the failure, fix the issue, verify again. Each iteration is cheap in context, and the structured feedback prevents the kind of drift that makes agents go in circles. Evidence accumulates as the agent works. Screenshots, video, and Playwright traces are uploaded to the dashboard at each verification step. When you come back, you’re not reading a conversation log trying to reconstruct what happened. You’re looking at screenshots of your app and a clear pass/fail for each behavior. ## The human review step [Section titled “The human review step”](#the-human-review-step) The agent writes and verifies in a tight inner cycle, then surfaces its work for human review.  The review happens asynchronously on the Ranger dashboard, where you can see exactly what the agent built and how it verified each behavior. If something needs to change, you leave a comment. The agent picks up that feedback, makes the fix, and re-verifies. This is a different relationship with the agent than live pair programming. You define the feature, the agent does the work and checks itself, and you review the evidence when it’s done. The agent’s ability to verify its own UI work is what makes the handoff trustworthy. # How Ranger Works > The architecture behind Ranger: CLI, plugin, browser agents, and dashboard. 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 [Section titled “Architecture”](#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 [Section titled “Components”](#components) ### Ranger CLI [Section titled “Ranger CLI”](#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 [Section titled “Skills”](#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 [Section titled “Claude Code Plugin”](#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 [Section titled “Browser Verification Agent”](#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 [Section titled “Ranger API”](#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 [Section titled “Feature Review Dashboard”](#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 [Section titled “How Verification Fits Into Development”](#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 [Section titled “Authentication”](#authentication) Ranger uses two layers of authentication. When you run `ranger setup`, you log in via browser. The CLI stores credentials locally and uses them to authenticate all CLI-to-API communication. Tokens refresh automatically. For details, see [Authentication](/reference/cli-overview/#authentication). 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 [Section titled “Data Flow”](#data-flow)  # Managing Profiles > Tell Ranger where your app runs and how to log in Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how the verification agent gets in. ## What a profile is [Section titled “What a profile is”](#what-a-profile-is) A profile bundles three things: * **An endpoint** — the URL where your app runs (e.g. `http://localhost:3000`, `https://staging.example.com`). * **An auth strategy** — how the verification agent gets logged in, if your app needs that. * **Browser settings** — headers, user agent, headless mode, and other knobs. Profiles are shared with everyone in your organization by default. That means a teammate can run `ranger go --profile alice@example.com` and reuse the session you captured — useful for sharing test accounts and for keeping CI in sync with what works on a developer’s laptop. Name profiles by the account they represent. Run `ranger profile ls` to see what’s set up. Run `ranger profile use ` to switch which profile `ranger go` uses by default. Create as many as you need — common patterns are one per environment, one per persona (free / paid / admin), or one per app you test. ## How Ranger logs into your app [Section titled “How Ranger logs into your app”](#how-ranger-logs-into-your-app) Ranger uses a profile to log into your app and capture a browser session it can use on every subsequent Feature Review. Three login mechanisms exist; Ranger uses them in this priority order: 1. **[Automated login](#automated-login)** — Ranger logs into your app for you, headless and deterministic, on every CI run, every background agent, every machine. Best for heavy usage and complex login flows involving SSO, OAuth, MFA, passkeys, custom auth, etc. If it’s configured for your app, this is the path that runs. Enterprise customers only. 2. **[Login instructions](#login-instructions)** — Ranger’s verification agent follows natural-language steps in a browser. Useful for flows an agent can complete on its own: hitting a debug-auth endpoint, setting a token in localStorage, navigating a custom form. Won’t work if a step needs a human or a second factor that Ranger can’t access. 3. **[Headed login](#headed-login)** — a browser opens, you log in once, Ranger captures the session. The universal default — works for any web app a person can sign into. Captured sessions are reused on every subsequent `ranger go` until they expire. When that happens, Ranger captures a fresh one using the same priority order. Two cases skip the login question entirely: * **[No login](#no-login)** — public sites, marketing pages, logged-out flows. Pass `--skip-auth`. * **[Electron / desktop apps](#electron-and-desktop-apps)** — speaks Chrome DevTools Protocol. Pass `--cdp-endpoint`. *** ### No login [Section titled “No login”](#no-login) For sites without authentication, just point Ranger at the URL: ```bash ranger profile add my-site --url http://localhost:3000 --skip-auth ``` `--skip-auth` skips the browser auth step. The profile is ready immediately. You can also use this for testing logged-out flows of an app that *does* have auth (e.g. the public landing page) — just don’t log in. *** ### Headed login [Section titled “Headed login”](#headed-login) The default for local development. Works with anything: username + password, SSO (Google, Okta, GitHub, WorkOS, etc.), OAuth, MFA at login. If a real user can log in, headed login captures the session. ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` A browser opens. Log in once with the account you want the agent to use. Close the browser when you’re done — Ranger saves the session. After that, every `ranger go` reuses the saved session until it expires. When it expires, run `ranger profile add` again to refresh. > **Naming tip.** Use a name that’s stable for the account you’re logging in as. An email works well; for accounts identified by username, phone, or anything else, use whatever’s stable. The name is just a label you’ll type when switching between profiles. #### Limits of headed login [Section titled “Limits of headed login”](#limits-of-headed-login) * A real human has to be at a keyboard to complete the initial login. For CI and background agents, see [automated login](#automated-login) or [login instructions](#login-instructions). * Magic-link, SMS-MFA, and hardware-key flows work if you can complete them in your browser, but the captured session is only as long-lived as the cookies your app issues. *** ### Automated login [Section titled “Automated login”](#automated-login) Enterprise customers only. Ranger logs into your app for you — no browser, no human in the loop — and captures a session that’s reused across every machine, CI run, and background agent. Set credentials as env vars and run `ranger go`: ```bash RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --base-url http://localhost:3000 \ --notes "user logs in and sees the dashboard" ``` When the session expires, Ranger logs in again automatically. #### Does this fit my app? [Section titled “Does this fit my app?”](#does-this-fit-my-app) Works for any login flow — SSO (Google, Okta, GitHub, WorkOS, etc.), OAuth, MFA, passkeys, magic links, custom forms, corporate auth. Bot protection, SSO routing, expiry rules, anything quirky about your app — we tune for it during onboarding. Setup is a call with our team. [Reach out](mailto:eng@ranger.net) and we’ll scope your case. While automated login is being configured: * For local dev, [headed login](#headed-login) works for any web app you can log into in a browser. * For CI, [login instructions](#login-instructions) is a fast bridge if your app has a debug-auth endpoint or short-lived tokens. #### What `--base-url` does and doesn’t change [Section titled “What --base-url does and doesn’t change”](#what---base-url-does-and-doesnt-change) `--base-url` controls **where the verification runs** — the URL the agent navigates to and interacts with. It does *not* control where login happens. Login runs against a stable URL we configure with you; the captured session is then reused against whatever `--base-url` you pass. This is by design: one profile, many environments. Your local dev instance, a Vercel preview, staging, prod — same session across all of them. If you find a case where a session doesn’t carry over between two of your domains, [let us know](mailto:eng@ranger.net) and we’ll tune the profile so it does. #### Multi-factor authentication [Section titled “Multi-factor authentication”](#multi-factor-authentication) Automated login handles MFA for any factor we can hold for your test account. Anything that needs a human in the moment with a personal device — push notifications to your phone, SMS or email codes Ranger can’t reach, a passkey registered to a personal account — won’t work for automated login. Use [headed login](#headed-login) once on your own machine for those; Ranger reuses the captured session for every subsequent run, anywhere. #### Bypassing bot protection during login [Section titled “Bypassing bot protection during login”](#bypassing-bot-protection-during-login) If your login page is behind a bot challenge that can be bypassed with a custom header (Cloudflare Turnstile, Datadome, etc.), set it on your profile and Ranger will send it during login: ```bash ranger profile config set alice@example.com setupHeaders.x-skip-turnstile "" ``` `setupHeaders.` is sent only during login, not during verification runs, so it won’t leak into third-party requests during the actual test. *** ### Login instructions [Section titled “Login instructions”](#login-instructions) Natural-language steps an LLM-driven browser follows to log in. Useful when [automated login](#automated-login) isn’t set up but the login flow is something an agent can complete — hitting a debug-auth endpoint, setting a token in localStorage, navigating a custom multi-step form. Create a profile without capturing login state, then describe the login flow in plain language: ```bash ranger profile add preview --url https://staging.example.com --skip-auth ranger profile config set preview loginInstructions \ "Navigate to ${BASE_URL}/api/debug-auth?email=test@example.com. \ Copy the token from the JSON response. \ Run in the browser console: localStorage.setItem('auth_token', ''). \ Refresh the page." ``` `${VAR_NAME}` resolves environment variables at runtime, so credentials don’t have to live in the instruction text. #### Limits of login instructions [Section titled “Limits of login instructions”](#limits-of-login-instructions) * Each step must be something the agent can do in a browser. Anything requiring a human (push notifications, hardware key taps, codes from inboxes Ranger can’t read) won’t work. * For deterministic flows that you’d want to run the same way every time, [automated login](#automated-login) is more reliable — talk to us about getting it set up. *** ## Browser settings [Section titled “Browser settings”](#browser-settings) Once a profile exists, fine-tune browser behavior with `ranger profile config`: ```bash ranger profile config set ``` | Key | What it does | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseUrl` | Override the profile’s URL for this directory (useful when one profile’s session works against multiple endpoints — local + staging, etc.) | | `headless` | `true`/`false`. Run the browser without a visible window. Headed is useful when you’re watching verification firsthand. | | `headers.` | Send a custom HTTP header with every request, e.g. `headers.Authorization`. Supports `${VAR}` for env vars. | | `setupHeaders.` | Like `headers.`, but only sent during the `ranger profile add` browser session — useful for bypassing login protection (Cloudflare Turnstile, etc.) without affecting third-party requests during runs. | | `userAgent` | Override the browser user agent. Useful for bypassing bot protection. | | `loginInstructions` | Plain-language login steps. See [Login instructions](#login-instructions). | | `allowInsecureLocalhost` | `true`/`false`. Allow localhost content in deployed environments (micro frontends, single-spa). Relaxes browser security; use only in dev. | | `cdpEndpoint` | Chrome DevTools Protocol endpoint for [Electron / desktop apps](#electron-and-desktop-apps). | ```bash ranger profile config list # show what's set ranger profile config unset # remove one key ranger profile config reset # clear all overrides ``` *** ## Picking which profile a run uses [Section titled “Picking which profile a run uses”](#picking-which-profile-a-run-uses) `ranger go` uses the active profile by default. Switch with: ```bash ranger profile use ``` Override per run with `--profile ` (or `RANGER_PROFILE=`). The flag wins. If you pass `--profile` for a name that doesn’t exist, the run fails immediately rather than falling back silently. The active profile is tracked per directory. Two checkouts of the same repo, in different directories, can each have their own active profile — useful when you’re running parallel agents against different environments. *** ## Multiple profiles [Section titled “Multiple profiles”](#multiple-profiles) You’ll want more than one profile when: ### Different environments for the same app [Section titled “Different environments for the same app”](#different-environments-for-the-same-app) Local dev, staging, preview deploys — each with its own URL but possibly the same login. ```bash ranger profile add alice@example.com --url http://localhost:3000 # initial setup ranger profile config set alice@example.com baseUrl '${PREVIEW_URL}' # in CI: PREVIEW_URL is set per-deploy ``` `${VAR}` references resolve at runtime, so one profile can target many deploys. ### Different accounts on the same app [Section titled “Different accounts on the same app”](#different-accounts-on-the-same-app) Free, paid, and enterprise users; admin vs. member; tenant A vs. tenant B. Add a profile per account; tell your coding agent which one to use for each scenario. ```bash ranger profile add free@example.com --url http://localhost:3000 ranger profile add admin@example.com --url http://localhost:3000 ``` Then in your prompt: *“Verify scenario 1 with `--profile free@example.com` and scenario 2 with `--profile admin@example.com`.”* ### Multiple apps that talk to each other [Section titled “Multiple apps that talk to each other”](#multiple-apps-that-talk-to-each-other) Customer-facing app on `localhost:3000`, internal admin tool on `localhost:3001`. One profile per app; the coding agent uses the right one per scenario. *** ## Electron and desktop apps [Section titled “Electron and desktop apps”](#electron-and-desktop-apps) Ranger can test Electron apps and other desktop applications that expose a Chrome DevTools Protocol (CDP) endpoint. There’s no URL to navigate to and no browser auth — Ranger attaches to the running app over CDP and starts interacting with the UI directly. **1. Start your app with remote debugging enabled:** ```bash your-electron-app --remote-debugging-port=9222 ``` Any port works. The app must be running before Ranger connects. **2. Add a profile pointing at the CDP endpoint:** ```bash ranger profile add my-electron-app --cdp-endpoint http://localhost:9222 ``` `--cdp-endpoint` skips URL reachability checks and browser auth — there’s no URL or browser to set up. **3. Run verifications normally:** ```bash ranger go --scenario 1 ``` The agent connects to your running app, takes a snapshot, and starts interacting. ### Limits of CDP profiles [Section titled “Limits of CDP profiles”](#limits-of-cdp-profiles) **Saved login sessions don’t work in CDP mode.** With web profiles, Ranger replays saved cookies into a fresh browser on every run. With Electron, Ranger attaches to a process that’s already running, so there’s no place to inject auth. If your Electron app needs a logged-in user, handle that at the app level — persist credentials, use env vars at launch, or skip login in development mode. *** ## Refreshing authentication [Section titled “Refreshing authentication”](#refreshing-authentication) When a saved session expires, the next `ranger go` will fail to authenticate. Refresh the session with: ```bash ranger profile update ``` `profile update` picks the right path based on how the profile is set up: * **Automated login configured**: re-runs server-side login (no browser, no human in the loop). * **Headed login**: opens a browser so you can log in again, then captures the session back to the cloud profile. * **Login instructions**: nothing to refresh — the verification agent re-runs them on every `ranger go`. You can also just re-run `ranger go` with `RANGER_TEST_USERNAME` / `RANGER_TEST_PASSWORD` set when automated login is configured — Ranger detects the stale session and logs in again automatically. ## Deleting a profile [Section titled “Deleting a profile”](#deleting-a-profile) ```bash ranger profile delete ``` This deletes the shared profile for everyone in your organization. You’ll be asked to type the name to confirm; pass `--yes` in scripted contexts. # Using Scenarios > Describe what to verify Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how to access it. Unlike profiles, scenarios are generally written by the coding agent. If you enable Ranger while in Plan Mode, the coding agent should include the scenarios it believes are necessary in the plan for implementation. These can be iterated on until you think they capture the flows correctly. The scenarios are also visible and editable on the Feature Review dashboard. ## Scenarios Basics [Section titled “Scenarios Basics”](#scenarios-basics) A scenario is a short, concrete user flow with an expected result. Ranger’s browser agent treats it both as a path to follow and a success condition to verify against. Scenarios are not entirely deterministic and are guidance more than a script. Like people visiting a site, each agent may take a slightly different path to accomplish the goal it’s given and the amount of variance depends on the specificity of the task. For instance, “Mark a checklist item as completed. Verify that the text is crossed out and the box is checked.” leaves agents room to choose any non-completed checklist item. They would also successfully toggle a “non-completed only” filter if they had to in order to find an appropriate example. Each scenario is verified on its own. They are not done in the same browser session (so frontend state does not carry over) or necessarily in the same order. Running a scenario can be backgrounded by the agent, so multiple may be run at once. If they are likely to interfere with each other’s background data, prompt the coding agent to run them serially. ## Writing Scenarios [Section titled “Writing Scenarios”](#writing-scenarios) A good scenario names the starting point, the action, and the expected result. Scenarios can contain complex paths through the app, but are generally easiest to verify and understand if they don’t contain multiple conditions. **Clear**: “User opens settings, toggles dark mode, page switches to dark theme.” **Vague**: “Add dark mode toggle.” **Too many conditions**: “A user should see the toggle on the top of the page if they’re logged in and at the bottom otherwise.” ## Shaping the List [Section titled “Shaping the List”](#shaping-the-list) Most feature reviews need only a few scenarios. The scenarios should focus on frontend behaviors and observable UI. A long checklist might be indicative of too many implementation details. The most effective scenarios are focused on what a person would do and see. # Quickstart > Get Ranger Feature Review running in your project in about 5 minutes. Already set up? Head to the [Ranger Feature Review Dashboard](https://dashboard.ranger.net) to manage your feature reviews, or check out the [CLI Overview](/reference/cli-overview) for a full list of commands. Get Ranger Feature Review running in your project in about 5 minutes. By the end, your AI coding agent will be able to verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 18 or later * **Claude Code** (or your favorite AI coding agent) * A web application running locally (e.g., on `localhost:3000`) ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project’s root directory (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh ``` This installs the CLI and walks you through interactive setup. If you prefer to install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup ``` ** *Note: If `ranger` conflicts with another program on your system (e.g. the ranger file manager), you can use `ranger-cli` instead for all commands.* This walks you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or another non-interactive setting like an agent sandbox, see the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. The short version: pass a token directly (`ranger setup [token]`) or set the `RANGER_CLI_TOKEN` env var. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). If API keys are challenging in your setup, other approaches are available for enterprise customers — [get in touch](mailto:support@ranger.net). ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### Claude Code Plugin [Section titled “Claude Code Plugin”](#claude-code-plugin) The plugin connects Ranger to Claude’s workflow so it can use the Ranger CLI intuitively. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git (requires a `.claude/` directory). Not using Claude Code? This workflow is focused on Claude Code because that’s what we used when developing and testing it. We also have an OpenCode plugin & skill installation, see [Getting Started with OpenCode](/getting-started/quickstart-opencode). And the skills and CLI work for any coding agent with shell access. See [Supported Coding Agents](/getting-started/supported-agents/) for more detail on how we recommend configuring it for Cursor, Codex and more. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. ```plaintext Would you like to install skills? (Y/n) ``` Say **yes**. Skills are markdown files that get installed into your `.claude/skills/` directory. They tell Claude when and how to create feature reviews, run verifications, and address feedback. ### Profile [Section titled “Profile”](#profile) A profile tells Ranger where your app runs and how to log in. See [Managing Profiles](/concepts/profiles) for the full picture; the quickstart covers the simplest case. After `ranger setup` finishes, create a profile for your app. Use a stable name (an email works well): ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` Ranger checks the URL is reachable, then opens Chromium so you can log in (if your app needs that). **Close the browser when you’re done.** Ranger saves the session, and the verification agent reuses it on every run. Profiles are shared with everyone in your organization by default, so name them by the account they represent. Run `ranger profile ls` to see what’s set up. Different setup for your app? * **No login at all** (logged-out flows, public pages): `ranger profile add my-site --url http://localhost:3000 --skip-auth` * **Running in CI or a background agent** (no human at a keyboard): see [Background Agent and CI Setup](/reference/background-agents-and-ci/). * **Short-lived tokens or a debug auth endpoint**: see [Login instructions](/concepts/profiles/#login-instructions). *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open Claude Code in your project. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, run the slash command: ```plaintext /ranger:enable ``` This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask Claude to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, Claude will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, Claude fixes them and re-verifies automatically. 5. Once everything passes, Claude shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you run `/ranger:resume` in Claude Code.  ## What’s Next [Section titled “What’s Next”](#whats-next) * [Profiles](/concepts/profiles) define where to test and how to access it. * [Scenarios](/concepts/scenarios) are the user flows to guide the verification agent. * [CLI Overview](/reference/cli-overview) gives you (or your agent) extra info about all the available commands. * [CLI Overview](/reference/cli-overview/#authentication) covers all authentication options including CI tokens and managed platforms. # OpenCode Quickstart > Set up Ranger Feature Review with OpenCode. Get Ranger Feature Review running with OpenCode. By the end, your agent will verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Node.js 18 or later * OpenCode * A web application running locally ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project root (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh -s -- --opencode ``` This installs the CLI and runs interactive setup with OpenCode preconfigured. Or install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup --opencode ``` This command will walk you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or from a non-interactive agent, pass a token directly: `ranger setup --opencode [token]`. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). See also the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### OpenCode Plugin [Section titled “OpenCode Plugin”](#opencode-plugin) The plugin reminds OpenCode to use Ranger at various points in the workflow. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git. Under the hood, this adds the following block to your `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@ranger-testing/opencode-plugin"] } ``` For user scope, the config file is at `~/.config/opencode/opencode.json` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. For project scope, it’s at `.opencode/opencode.json` in your repo. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. Ranger installs skills automatically at the same scope you chose for the plugin. Skills are markdown files that tell your coding agent when and how to create feature reviews, run verifications, and address feedback. Project installs go to `.opencode/skills/`. User installs go to `~/.config/opencode/skills/` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. ### Profile [Section titled “Profile”](#profile) Ranger needs to know how to access your running app and how to authenticate. We manage that information in [profiles](/concepts/profiles). After `ranger setup` finishes, create a profile for your app. Use a stable name (an email works well): ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` Ranger checks the URL is reachable, then opens Chromium so you can log in to your app (if it requires authentication). **Close the browser when you’re done.** Ranger saves the session cookies so the verification agent can authenticate the same way. Profiles are shared with everyone in your organization by default, so name them by the account they represent. If your app doesn’t require login, pass `--skip-auth`. *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open OpenCode in your project directory. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, tell your agent to `enable ranger`. This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask your coding agent to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, your coding agent will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, it fixes them and re-verifies automatically. 5. Once everything passes, it shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you ask it to `resume ranger` in OpenCode.  # Supported Coding Agents > Ranger works with Claude Code, OpenCode, Cursor, Codex, and any agent with shell access. Here's how to set up each one. Ranger Feature Review works with any coding agent that can run bash commands. The table below shows what’s supported out of the box and links to the setup instructions for each agent. | Agent | Plugin | Skills | Setup Command | | ----------------------------- | --------------------------------------- | ---------------------------------- | ------------------------- | | [Claude Code](#claude-code) | Yes (`ranger@trailhead`) | `.claude/skills/` | `ranger setup` | | [OpenCode](#opencode) | Yes (`@ranger-testing/opencode-plugin`) | `.opencode/skills/` | `ranger setup --opencode` | | [Cursor](#cursor) | No | `.cursor/skills/` (via sym link) | `ranger setup` | | [Codex](#codex) | No | `.codex/skills/` (via sym link) | `ranger setup` | | [Other agents](#other-agents) | No | directory of choice (via sym link) | `ranger setup` | In the setup instructions below, we provide commands to sym link the skills into the appropriate directory. It will also work to copy or move them, but the `ranger update` command will automatically update the skills to match new CLI versions and sym linking allows those updates to be immediately picked up by your coding agent. *** ## Claude Code [Section titled “Claude Code”](#claude-code) Claude Code is Ranger’s primary integration. The `ranger setup` command installs a Claude Code plugin and skills automatically. **Quickstart:** Follow the full [Quickstart](/getting-started/quickstart/) guide. **What you get:** * **Plugin** — Connects Ranger to Claude’s hook system. Ranger can automatically activate at the right moments in your workflow. * **Skills** — Markdown files installed to `.claude/skills/` that teach Claude how to create feature reviews, run verifications, and address feedback. * **Slash commands** — `/ranger:enable`, `/ranger:disable`, and `/ranger:resume` for quick control. *** ## OpenCode [Section titled “OpenCode”](#opencode) OpenCode has its own plugin and skill paths. Use the `--opencode` flag during setup. **Quickstart:** Follow the [OpenCode Quickstart](/getting-started/quickstart-opencode/) guide. **What you get:** * **Plugin** — The `@ranger-testing/opencode-plugin` package, configured in your `opencode.json`. * **Skills** — Markdown files installed to `.opencode/skills/`. * **Natural language activation** — Tell your agent to “enable ranger” instead of slash commands. *** ## Cursor [Section titled “Cursor”](#cursor) Cursor 2.4+ reads `.claude/skills/` for compatibility, so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the `.cursor/skills` directory: ```sh ln -s ~/.claude/skills/ranger ~/.cursor/skills/ranger ``` The skills work without a plugin, but you may have to remind the agent to use it after compaction or later in the context window. Invoke the skill with `/ranger` or `@ranger` in Cursor’s Agent chat (e.g. “Use @ranger to create a feature review and verify it”). *** ## Codex [Section titled “Codex”](#codex) Codex reads `.claude/skills/` (and `.codex/skills/`), so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the Codex skills directory: ```sh ln -s ~/.claude/skills/ranger ~/.codex/skills/ranger ``` Codex’s default permissions mode blocks most network access, so Ranger will fail until permissions are adjusted. For an individual session, the slash command `/permissions` will allow you to update to Full Access. For a more enduring fix, you can add Ranger and network permissions by default: ```sh echo 'prefix_rule(pattern=["ranger"], decision="allow")' >> ~/.codex/rules/default.rules ``` and update `~/.codex/config.toml` with: ```plaintext sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true ``` *** ## Other Agents [Section titled “Other Agents”](#other-agents) Any coding agent that can execute bash commands can use Ranger. The core workflow is: 1. Install CLI and authenticate: `npm install -g @ranger-testing/ranger-cli && ranger setup` 2. Install skills: Say yes when prompted, or run `ranger skillup` separately. Skills are installed to `.claude/skills/ranger/` by default. 3. (optional) Link skills: if your agent looks for skills in a specific directory, sym link the ranger skill into that directory. 4. Use the CLI: Your agent runs `ranger create`, `ranger go`, `ranger show`, etc. The skill files are plain markdown — they work as instructions for any LLM-based agent. Want a dedicated integration? If you’re using an agent or harness that would benefit from an integration, [let us know](mailto:eng@ranger.net)! # Background Agent and CI Setup > Run Ranger in hosted environments — background agents running on isolated VMs, and CI pipelines. Beta   > **This feature is in beta.** We are actively developing background agent and CI support. If you’d like to get started using Ranger with a background agent, [reach out to us](mailto:eng@ranger.net) and we’ll help you set it up. This guide covers running Ranger in hosted environments, including background agents running on isolated VMs, and CI workflows (GitHub Actions, GitLab CI, etc.). The same steps apply regardless of the platform - anywhere you can run Node.js and a headless browser. Ranger works with any coding agent that can execute bash commands — Claude Code, OpenCode, Codex, or any other agent with shell access. ## How auth works without a human [Section titled “How auth works without a human”](#how-auth-works-without-a-human) CI and background agents don’t have anyone to click “log in” or tap a phone for a 2FA prompt. Ranger has three login mechanisms it uses in priority order — they’re the same ones described in [Profiles → How Ranger logs into your app](/concepts/profiles/#how-ranger-logs-into-your-app); the steps below are the operational bits for getting your hosted environment set up. | Your app’s situation | Strategy | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **No login** | [Skip auth](#path-skip-auth) — point Ranger at the URL and go. | | **Enterprise customer with automated login configured** (any auth shape, set up with our team) | [Automated login](#path-automated-login) — headless, deterministic. | | **Login flow an agent can do** (short-lived tokens, debug-auth endpoint, custom form) | [Login instructions](#path-login-instructions) — natural language; the agent follows them. | Each path has the same structure: a one-time profile setup, then secrets in your hosted environment, then your normal CI/agent steps. ## Path: Skip auth [Section titled “Path: Skip auth”](#path-skip-auth) For sites without authentication, no profile setup is needed beyond pointing at the URL. ```bash ranger profile add public-site --url https://docs.example.com --skip-auth ``` Commit nothing; the profile is reachable from any environment with `RANGER_CLI_TOKEN`. Skip ahead to [environment setup](#environment-setup-steps). ## Path: Automated login [Section titled “Path: Automated login”](#path-automated-login) Enterprise customers only. Ranger logs into your app for you on every CI run and background agent; your team sets credentials as env vars. For the full picture of what we cover and how it fits into a profile, see [Automated login](/concepts/profiles/#automated-login). The steps below are the operational bits for wiring it into your hosted environment. ### 1. Pick test credentials [Section titled “1. Pick test credentials”](#1-pick-test-credentials) Pick the account the hosted agent will log in as. The username doubles as the profile name, so pick something stable. ### 2. Make secrets available to the environment [Section titled “2. Make secrets available to the environment”](#2-make-secrets-available-to-the-environment) Your environment needs these secrets: | Secret | Description | | ---------------------- | ---------------------------------------------------------------------- | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth. | | `RANGER_TEST_USERNAME` | Test account username (typically the email used to log into your app). | | `RANGER_TEST_PASSWORD` | Test account password. | You’ll also need an API key for your coding agent (e.g. `ANTHROPIC_API_KEY` for Claude Code). How you provide these depends on your platform — GitHub repo secrets, GitLab CI variables, environment variables in a VM, etc. ### 3. (Optional) Smoke-test from your laptop [Section titled “3. (Optional) Smoke-test from your laptop”](#3-optional-smoke-test-from-your-laptop) Before letting CI rip, run a one-shot locally to confirm the credentials work: ```bash RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \ ranger go --base-url https://staging.example.com \ --notes "smoke: dashboard renders" ``` If that works locally, it’ll work in CI with the same secrets. Skip ahead to [environment setup](#environment-setup-steps). ## Path: Login instructions [Section titled “Path: Login instructions”](#path-login-instructions) Use this when automated login can’t model your app’s auth — short-lived tokens, debug auth endpoints, custom bootstraps. ### 1. Create a profile [Section titled “1. Create a profile”](#1-create-a-profile) ```bash ranger profile add preview --skip-auth --url https://staging.example.com ``` `--skip-auth` skips the browser auth step. The profile exists with no session attached; the agent will run your instructions on every verification. ### 2. Write the login instructions [Section titled “2. Write the login instructions”](#2-write-the-login-instructions) ```bash ranger profile config set preview loginInstructions \ 'Navigate to ${PREVIEW_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token.' ``` Plain language; `${VAR}` references resolve at runtime, so credentials don’t have to live in the instructions text. The agent runs these before every verification. ### 3. Dynamic base URLs [Section titled “3. Dynamic base URLs”](#3-dynamic-base-urls) If your deployment URL changes per environment (Vercel preview URLs, Heroku review apps), use `${VAR}` in `baseUrl` too: ```bash ranger profile config set preview baseUrl '${PREVIEW_URL}' ``` Same trick works for headers: ```bash ranger profile config set preview headers.Authorization '${AUTH_TOKEN}' ``` ### 4. Make secrets available [Section titled “4. Make secrets available”](#4-make-secrets-available) | Secret | Description | | ------------------ | ------------------------------------------------------ | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth. | Plus any env vars your instructions reference (e.g. `TEST_USER_EMAIL`, `PREVIEW_URL`, `AUTH_TOKEN`), and your coding agent’s API key (e.g. `ANTHROPIC_API_KEY` for Claude Code). ## Environment Setup Steps [Section titled “Environment Setup Steps”](#environment-setup-steps) These are the steps your environment needs to run, in order. The commands below are plain bash — adapt them to your platform’s syntax. ### 1. Check out the repository [Section titled “1. Check out the repository”](#1-check-out-the-repository) Clone with full git history (needed if you want to generate diffs): ```bash git clone ``` ### 2. Install Node.js [Section titled “2. Install Node.js”](#2-install-nodejs) Ranger CLI requires Node.js 18+. ### 3. Install project dependencies [Section titled “3. Install project dependencies”](#3-install-project-dependencies) ```bash npm install ``` ### 4. Install a virtual display (Linux only) [Section titled “4. Install a virtual display (Linux only)”](#4-install-a-virtual-display-linux-only) Ranger runs a headless Chromium browser. On Linux environments without a display server, you need Xvfb: ```bash apt-get install -y xvfb Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 ``` Not needed on macOS or environments with a display server. ### 5. Install your coding agent and Ranger CLI [Section titled “5. Install your coding agent and Ranger CLI”](#5-install-your-coding-agent-and-ranger-cli) Install Ranger CLI globally, along with whatever coding agent you’re using: ```bash npm install -g @ranger-testing/ranger-cli # Plus your coding agent, e.g.: npm install -g @anthropic-ai/claude-code ``` ### 6. Install Chromium and authenticate [Section titled “6. Install Chromium and authenticate”](#6-install-chromium-and-authenticate) Pass your Ranger API token to the setup command. In non-interactive mode, this authenticates and installs the Playwright Chromium browser: ```bash export RANGER_CLI_TOKEN= ranger setup $RANGER_CLI_TOKEN ``` See [Authentication](/reference/cli-overview/#authenticating-the-ranger-cli-to-ranger) for all auth options. #### Separating install from auth (Docker / custom images) [Section titled “Separating install from auth (Docker / custom images)”](#separating-install-from-auth-docker--custom-images) If you’re building a container image, you can install Chromium and dependencies at **build time** (no token needed), then authenticate at **runtime**: ```dockerfile # -- Build time: bake deps into the image -- FROM node:20 RUN npm install -g @ranger-testing/ranger-cli @anthropic-ai/claude-code RUN ranger setup deps --with-deps ``` `ranger setup deps` installs Chromium without requiring authentication or a git repo. `--with-deps` tells Playwright to also install OS-level libraries (fonts, libx11, etc.) that headless Chromium needs on Debian/Ubuntu. At runtime, authenticate and set up skills: ```bash # -- Runtime: per-user or per-job auth -- export RANGER_CLI_TOKEN= ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` Each subcommand runs only its phase — `login` handles auth, `skills` installs the Claude Code plugin and skill files. You can also still use `ranger setup $RANGER_CLI_TOKEN` to run everything at once. ### 7. Run a verification [Section titled “7. Run a verification”](#7-run-a-verification) If you set up [automated login](#path-automated-login), set the credentials as env vars and call `ranger go` directly: ```bash RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \ ranger go --base-url $APP_URL --notes "" ``` If you set up [login instructions](#path-login-instructions), pin the profile and let the agent run them: ```bash ranger profile use preview ranger go --notes "" ``` If you’re [skipping auth](#path-skip-auth), just pin the profile and run: ```bash ranger profile use public-site ranger go --notes "" ``` ### 8. Install Ranger skills [Section titled “8. Install Ranger skills”](#8-install-ranger-skills) Install the Ranger skill files that teach your coding agent how to create feature reviews and run verifications: ```bash ranger skillup ``` This places skill markdown files in `.claude/skills/` (compatible with any agent that reads skill files from the project directory). ### 9. Configure your coding agent’s permissions [Section titled “9. Configure your coding agent’s permissions”](#9-configure-your-coding-agents-permissions) Your coding agent needs permission to run bash commands (for `ranger`, `gh`, `git`, etc.) and read files. How you configure this depends on your agent. **Claude Code example** — write `.claude/settings.local.json`: ```json { "permissions": { "allow": ["Bash(*)", "Read(*)", "Glob(*)", "Grep(*)"], "deny": [] } } ``` Other agents may need equivalent configuration, or may not require it at all. ### 10. Run your coding agent with Ranger [Section titled “10. Run your coding agent with Ranger”](#10-run-your-coding-agent-with-ranger) Invoke your coding agent in non-interactive mode with a prompt that tells it to use the Ranger skill. The skill files teach the agent how to create feature reviews, write scenarios, and run browser verification. Here are two possible use cases: #### CI workflow: Bug bash a PR’s changes [Section titled “CI workflow: Bug bash a PR’s changes”](#ci-workflow-bug-bash-a-prs-changes) Trigger on every pull request. The agent reads the diff, creates scenarios based on what changed, and verifies them in the browser. Results get posted as a PR comment. ```bash claude --print "Look at the git diff for this branch against main. \ Use the /ranger skill to create a feature review from the UI changes \ and verify each scenario. Post results as a PR comment using gh." ``` #### Background agent: Build and verify a feature [Section titled “Background agent: Build and verify a feature”](#background-agent-build-and-verify-a-feature) Give a coding agent a feature task and let it implement the code, then verify its own work in the browser before reporting back. ```bash claude --print "Read the task requirements and document a plan in docs/feature/{feature-name}.md. \ Implement the feature in the codebase, referencing the original task for context. \ Commit changes and push to the current branch. \ Use the Ranger skill to authenticate against the current environment and verify the feature works end-to-end in the browser." ``` ## Refreshing authentication [Section titled “Refreshing authentication”](#refreshing-authentication) Sessions refresh automatically: * **Automated login**: when a saved session expires, Ranger logs in again with the env-var credentials. No manual step. * **Login instructions**: the agent runs them on every verification, so there’s nothing to refresh. If the underlying flow changes (a new debug endpoint, a renamed env var), update the instruction text: ```bash ranger profile config set preview loginInstructions "" ``` * **Skip auth**: nothing to refresh. ## Limits [Section titled “Limits”](#limits) * **Automated login needs a one-time setup with us.** If your app isn’t set up yet, use [login instructions](#path-login-instructions) or do a one-time [headed login](/concepts/profiles/#headed-login) locally and reuse the saved session in CI. [Reach out](mailto:eng@ranger.net) and we’ll get you wired up. * **Some MFA factors require a human in the moment** — see [Multi-factor authentication](/concepts/profiles/#multi-factor-authentication) for which factors automated login can hold and which need a one-time headed login. * **One profile per account.** If you need different accounts, make different profiles. If you need the same account against different environments, override `baseUrl` per environment (see [Dynamic base URLs](#3-dynamic-base-urls)). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### “Automated login isn’t set up for this app yet” [Section titled ““Automated login isn’t set up for this app yet””](#automated-login-isnt-set-up-for-this-app-yet) The account you’re using doesn’t have automated login configured. [Reach out](mailto:eng@ranger.net) and we’ll set it up. In the meantime, use [login instructions](#path-login-instructions). ### Automated login fails with HTTP 422 (or falls back to a headed browser) [Section titled “Automated login fails with HTTP 422 (or falls back to a headed browser)”](#automated-login-fails-with-http-422-or-falls-back-to-a-headed-browser) Usually a bot challenge blocking the login page. If you have a header that bypasses it, set it on the profile — see [Bypassing bot protection during login](/concepts/profiles/#bypassing-bot-protection-during-login). If your bot protection can’t be bypassed with a header, fall back to [login instructions](#path-login-instructions) hitting a debug-auth endpoint. ### “Profile X not found” [Section titled ““Profile X not found””](#profile-x-not-found) Profile names are usually the username/email of the account. If you used automated login, the profile name is the value of `RANGER_TEST_USERNAME` — pass that as `--profile` if you need to disambiguate. Run `ranger profile ls` to see what’s available. ### Coding agent blocks commands [Section titled “Coding agent blocks commands”](#coding-agent-blocks-commands) Some agents sandbox tool calls by default. Make sure your agent has permission to run bash commands before invoking it. For Claude Code, this means writing `.claude/settings.local.json` (see step 9). ### Browser fails to launch [Section titled “Browser fails to launch”](#browser-fails-to-launch) On Linux, make sure Xvfb is running and `DISPLAY` is set before the agent starts. Chromium needs a display server even in headless mode on some configurations. ### Vercel preview environments return 401/403 [Section titled “Vercel preview environments return 401/403”](#vercel-preview-environments-return-401403) Vercel’s [Deployment Protection](https://vercel.com/docs/deployment-protection) blocks automated access to preview URLs by default. To bypass it, generate a protection bypass token in your Vercel project settings and add it as a custom header on the profile: ```bash ranger profile config set preview headers.x-vercel-protection-bypass '' ``` See [Vercel’s bypass automation docs](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) for how to generate the token. ## Example: GitHub Actions Workflow [Section titled “Example: GitHub Actions Workflow”](#example-github-actions-workflow) A complete workflow using Claude Code with [automated login](#path-automated-login). Copy to `.github/workflows/ranger-pr-verify.yaml`. **Required secrets** (Settings > Secrets and variables > Actions): * `RANGER_CLI_TOKEN` — Your Ranger API token * `RANGER_TEST_USERNAME` — Test account username for your app * `RANGER_TEST_PASSWORD` — Test account password * `ANTHROPIC_API_KEY` — Anthropic API key for Claude Code ```yaml name: Ranger PR Verification on: pull_request: types: [opened, synchronize, reopened] workflow_dispatch: inputs: pr_number: description: 'PR number to verify (optional, uses current branch if empty)' required: false type: string env: HUSKY: 0 jobs: verify: name: Ranger PR Verification runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm install - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y xvfb - name: Install Claude Code and Ranger CLI run: npm install -g @anthropic-ai/claude-code @ranger-testing/ranger-cli - name: Setup Ranger CLI env: RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} run: ranger setup ${{ secrets.RANGER_CLI_TOKEN }} - name: Configure Claude Code permissions run: | mkdir -p .claude cat > .claude/settings.local.json << 'EOF' { "permissions": { "allow": [ "Bash(*)", "Read(*)", "Glob(*)", "Grep(*)" ], "deny": [] } } EOF - name: Run Ranger verification env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} RANGER_TEST_USERNAME: ${{ secrets.RANGER_TEST_USERNAME }} RANGER_TEST_PASSWORD: ${{ secrets.RANGER_TEST_PASSWORD }} DISPLAY: ':99' GH_TOKEN: ${{ github.token }} run: | Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 sleep 2 claude --print "Look at the git diff for this branch against main. Use the /ranger skill to create a feature review from the changes and verify each scenario. Post results as a PR comment using gh." timeout-minutes: 30 ``` The agent’s `ranger go` calls pick up `RANGER_TEST_USERNAME` / `RANGER_TEST_PASSWORD` from the env automatically — no separate profile setup step is needed in the workflow. # CLI Overview > All Ranger CLI commands at a glance. The Ranger CLI (`@ranger-testing/ranger-cli`) is the primary tool for setting up, managing, and running Ranger in your project. Install it globally: ```bash npm install -g @ranger-testing/ranger-cli ``` This page covers all commands at a human-readable level. Your AI coding agent has its own detailed skill docs, so you don’t need to memorize flags. ## Setup [Section titled “Setup”](#setup) | Command | What it does | | --------------- | -------------------------------------------------------------------------------- | | `ranger setup` | Full interactive setup: auth, Chromium, plugin, profile, skills. Run this first. | | `ranger login` | Re-authenticate without running full setup again. | | `ranger status` | Show everything: version, org, plugin status, skills, profiles. | | `ranger update` | Update the CLI to the latest version and refresh installed skills. | | `ranger clean` | Remove all Ranger artifacts from the project (nuclear option). | ### `ranger setup` [Section titled “ranger setup”](#ranger-setup) The recommended way to get started. Run it in your project root (should be a git repo for feature review tracking) and it walks you through: 1. Browser-based authentication (or pass a token for CI: `ranger setup [token]`) 2. Chromium installation for browser verification 3. Claude Code plugin installation 4. Profile setup (your app’s URL + login) 5. Skill installation If you skip any step, you can run it individually later — each phase is also available as a subcommand. #### Subcommands [Section titled “Subcommands”](#subcommands) | Command | What it does | | ----------------------- | ------------------------------------------------------------------------------------------ | | `ranger setup` | Full interactive setup (default). | | `ranger setup all` | Explicit full setup — same as bare `ranger setup`. | | `ranger setup deps` | Install Chromium only. No auth, no git repo required. Use `--with-deps` for OS packages. | | `ranger setup login` | Authenticate only. Use `--token ` or `--mcp` for non-interactive auth. | | `ranger setup skills` | Install Claude Code plugin and skills only. Use `--scope user\|project`, `--opencode`. | | `ranger setup profiles` | Set up a local browser profile only. Use `--url`, `--force`, `--allow-insecure-localhost`. | #### Non-interactive mode [Section titled “Non-interactive mode”](#non-interactive-mode) Individual subcommands are the preferred way to script setup in containers and CI: ```bash # Docker build time — no auth needed ranger setup deps --with-deps # Runtime — auth and skills ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` The full `ranger setup` command also accepts flags for non-interactive use: | Flag | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `--url ` | Base URL for profile setup. A browser still opens for auth. | | `--force` | Skip URL reachability check. | | `--skip-chromium` | Skip Chromium installation. | | `--skip-auth` | Skip authentication — install deps only. Useful for container/CI image builds where auth happens at runtime. | | `--with-deps` | Install OS-level dependencies for Chromium (apt packages for Debian/Ubuntu). Pair with `--skip-auth` for container builds. | | `--allow-insecure-localhost` | Allow localhost content in deployed environments (micro frontends). | | `--mcp-bootstrap` | Bootstrap auth via an MCP auth server instead of browser login. Used by managed agent platforms and MCP-compatible tools. | ```bash ranger setup $TOKEN --url http://localhost:3000 ``` #### Headless / Scripted Setup [Section titled “Headless / Scripted Setup”](#headless--scripted-setup) For Docker containers and CI images, use subcommands to separate build-time deps from runtime auth: ```dockerfile # Dockerfile (build time) RUN npm install -g @ranger-testing/ranger-cli RUN ranger setup deps --with-deps ``` ```bash # Runtime startup script ranger setup login --token $RANGER_CLI_TOKEN # or: ranger setup login --mcp ranger setup skills --scope user ``` For a complete CI / background-agent walkthrough, see [Background Agent and CI Setup](/reference/background-agents-and-ci/). ### Authenticating the Ranger CLI to Ranger [Section titled “Authenticating the Ranger CLI to Ranger”](#authenticating-the-ranger-cli-to-ranger) **Interactive (laptops, developer machines)** `ranger setup` opens a browser for login. The CLI manages token refresh automatically. If your session expires, run `ranger login` to re-authenticate. **CI and scripted environments** Pass an API token from your [Ranger Dashboard](https://dashboard.ranger.net/cli): ```bash ranger setup ``` Or set the `RANGER_CLI_TOKEN` environment variable — the CLI reads it automatically. **MCP authentication** The CLI can authenticate via MCP, which may be useful in non-interactive environments where you would like the Ranger CLI to act on a real user’s behalf: ```bash ranger setup --mcp-bootstrap ``` Set `RANGER_MCP_AUTH_URL` to point at your platform’s MCP proxy if applicable. [Contact us](mailto:support@ranger.net) for setup guidance. ### Logging the agent into your app (profiles) [Section titled “Logging the agent into your app (profiles)”](#logging-the-agent-into-your-app-profiles) CLI auth (above) identifies *you* to the Ranger API. Separately, the verification agent needs to log in to *your app*. That’s what [profiles](/concepts/profiles) handle — see that page for setup details. ## Profiles [Section titled “Profiles”](#profiles) Profiles tell Ranger where your app runs and how the agent gets in. | Command | What it does | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ranger profile add ` | Add a profile. Opens a browser for you to log in (or use `--skip-auth` for apps without login). Supports `--url`, `--force`, `--skip-auth`, `--cdp-endpoint`, `--allow-insecure-localhost`, `--safe-mode`, `--setup-header`. | | `ranger profile update ` | Refresh authentication for an existing profile. Runs server-side login when configured; otherwise opens a browser. | | `ranger profile use ` | Switch which profile is active. | | `ranger profile ls` | List all profiles with their URLs and status. | | `ranger profile delete ` | Delete a cloud profile. Asks you to type the name to confirm; pass `--yes` to skip. | Profiles are shared with everyone in your organization by default — name them by the account they represent. Use `--cdp-endpoint` on `profile add` to connect to an Electron app or existing browser via Chrome DevTools Protocol instead of a URL. ## Profile Config [Section titled “Profile Config”](#profile-config) Fine-tune browser behavior per profile. | Command | What it does | | --------------------------------------------------- | ---------------------------------- | | `ranger profile config set ` | Set a config value. | | `ranger profile config get ` | Read a config value. | | `ranger profile config list ` | Show all config for a profile. | | `ranger profile config unset ` | Remove a config value. | | `ranger profile config reset ` | Clear all per-directory overrides. | Supported keys: `baseUrl`, `headless` (true/false), `allowInsecureLocalhost` (true/false), `safeMode` (true/false, disables browser features like Bluetooth that can cause crashes on some systems), `userAgent`, `storageState`, `cdpEndpoint`, `loginInstructions`, `headers.` (custom HTTP headers sent with every request), `setupHeaders.` (HTTP headers sent only during profile setup auth — see below). ```bash ranger profile config set local headless true ranger profile config set local allowInsecureLocalhost true ranger profile config set ci header.Authorization '${AUTH_TOKEN}' ranger profile config set my-electron-app cdpEndpoint http://localhost:9222 ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' ``` Environment variables like `${AUTH_TOKEN}` are resolved at runtime. ### Setup-Only Headers [Section titled “Setup-Only Headers”](#setup-only-headers) Some apps require a custom HTTP header to bypass login protection (e.g. Cloudflare Turnstile) during initial setup, but that header causes problems if sent on every request during test runs (e.g. CORS failures with third-party services). Use `setupHeader.` to set headers that are only sent during the `ranger profile add` auth browser session: ```bash # Via config (applied on next profile add) ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' # Or inline during profile creation ranger profile add local --url https://app.example.com --setup-header "x-bypass-turnstile: a1b2c3d4..." ``` These headers are persisted in the profile and reused when you re-add or overwrite the profile. They are **not** sent during `ranger go` verification runs. ### Custom Login Instructions [Section titled “Custom Login Instructions”](#custom-login-instructions) If your app uses short-lived cookies or tokens that expire before Ranger can use them, you can provide custom login instructions instead of relying on saved auth state. Set `loginInstructions` to tell the Ranger agent how to authenticate before each verification run: ```bash ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', ''). Refresh the page." ``` The agent will follow these instructions as a mandatory first step before every verification. This works with any auth mechanism — local debug endpoints, API keys, token injection, etc. Environment variables are supported: ```bash ranger profile config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token." ``` ## Feature Reviews [Section titled “Feature Reviews”](#feature-reviews) Feature reviews are the core unit of work in Ranger. Each feature review has a name, description, and scenarios to verify in the browser. | Command | What it does | | ------------------------------ | -------------------------------------------------------------------------------------- | | `ranger create ""` | Create a new feature review. Use `-c` for scenarios, `-d` for description. | | `ranger list` | List feature reviews. Use `--current-branch` to filter by your git branch. | | `ranger show` | Show the active feature review’s status and scenarios. | | `ranger resume ` | Set a feature review as active and start its session. | | `ranger add-scenario ""` | Add a scenario to the active feature review. | | `ranger get-review` | Show unaddressed reviewer comments across all scenarios. | | `ranger report [id]` | Generate PR description markdown with screenshots. Use `--json` for structured output. | | `ranger delete` | Soft delete the active feature review. | | `ranger restore ` | Restore a soft-deleted feature review. | ### Creating a Feature Review [Section titled “Creating a Feature Review”](#creating-a-feature-review) ```bash ranger create "Dark Mode Toggle" \ -d "Add dark mode support to settings page" \ -c "User opens settings, toggles dark mode, and the page switches themes" ``` Feature reviews auto-detect your git repo and branch. The feature review becomes active immediately. ### Resuming Work [Section titled “Resuming Work”](#resuming-work) At the start of a session, check for existing feature reviews: ```bash ranger list --current-branch ranger resume feat_abc123 ``` ### Generating Reports [Section titled “Generating Reports”](#generating-reports) `ranger report` generates a PR description from the active feature review’s verified scenarios, including screenshots. ```bash ranger report ranger report feat_abc123 ``` By default, output is markdown. Use `--json` for structured output that other tools can consume: ```bash ranger report --json ``` The JSON output contains the feature review dashboard URL and an array of scenarios: ```json { "url": "https://dashboard.ranger.net/features/feat_...", "scenarios": [ { "description": "string", "result": "verified | incomplete | blocked | in_progress | pending | approved | cancelled | superseded | closed", "rationale": "string | null", "steps": [ { "description": "string", "screenshot": "string (URL) | null", "is_key_step": true } ] } ] } ``` `result` reflects the scenario’s verification status. `rationale` is the agent’s response or the reason for a blocked/incomplete/cancelled status. Each step includes a screenshot URL when available; `is_key_step` marks the most important moments. Use `--exclude` to omit specific scenarios by number (1-based): ```bash ranger report --exclude 2 4 ``` ## Verification [Section titled “Verification”](#verification) `ranger go` spawns a browser agent to test your scenarios. ```bash ranger go ``` The CLI prompts you to select which scenario to verify. The browser agent navigates your app, interacts with the UI, takes screenshots, and returns a verdict (verified, partial, blocked, or failed). Common options: * `--scenario `: skip the selection prompt, verify scenario N directly (1-based) * `--notes ""`: override what the agent does (defaults to the scenario description) * `--start-path /settings`: start the agent on a specific page instead of the base URL * `--base-url `: override the profile’s base URL for this run (also reads `RANGER_BASE_URL`) * `--profile `: use a specific profile instead of the active one (also reads `RANGER_PROFILE`) * `--headed`: force a headed browser for this run only (does not change profile config) ### One-shot verification with credentials inline [Section titled “One-shot verification with credentials inline”](#one-shot-verification-with-credentials-inline) If your team has [automated login](/concepts/profiles/#automated-login) set up with us, you can skip `profile add` entirely and pass credentials inline: ```bash RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --base-url http://localhost:3000 \ --notes "user logs in and sees the dashboard" ``` Ranger logs in for you and saves the session for next time. Automated login is set up per-app — works for any login flow we can run deterministically (username/password, SSO, OAuth, MFA, passkeys). [Reach out](mailto:eng@ranger.net) and we’ll scope your case. ## In Claude Code [Section titled “In Claude Code”](#in-claude-code) These aren’t CLI commands. They’re slash commands inside Claude Code: | Command | What it does | | ----------------- | -------------------------------------------------------------------- | | `/ranger:enable` | Enable Ranger hooks for this session and branch. | | `/ranger:disable` | Disable Ranger hooks. | | `/ranger` | Invoke the Ranger skill (create, verify, or manage feature reviews). | Ranger stays enabled on your branch across sessions (except on `main`/`master`, where it’s session-only). You only need to enable once per branch. # Hook System > How Ranger integrates with Claude Code through automatic hooks. Ranger integrates with Claude Code through hooks: automatic triggers that fire at key moments in the coding session. Hooks guide Claude through the Feature Review workflow without requiring you to remember commands or prompt for it repeatedly. The Claude Code plugin should be automatically installed when you run `ranger setup`. If you need to re-install them at any point, you can run: ```plaintext /plugin marketplace add ranger-testing/trailhead /plugin install ranger@trailhead ``` from inside Claude or: ```plaintext claude plugin marketplace add ranger-testing/trailhead claude plugin install ranger@trailhead ``` from the terminal. After installing, you may need to restart Claude Code before you can use the plugin. ## Why Hooks [Section titled “Why Hooks”](#why-hooks) We started with just the skills and discovered that Claude kept forgetting to use `ranger` and would return to us with errors that would have been caught with verification. We temporarily solved that with careful and repeated prompting, but wanted to automate it. Claude Code plugins offer “hooks” that can be used to remind Claude–if relevant–to use Ranger and check its work before returning to the user. We’ve found that enabling hooks whenever we’re working on UI-related work has dramatically improved Claude’s reliability with Feature Review. ## Opt-In Model [Section titled “Opt-In Model”](#opt-in-model) Hooks are **off by default**. Run `/ranger:enable` in Claude Code to activate them for your current session and branch. Once enabled on a branch, Ranger stays enabled across sessions. Use `/ranger:disable` to explicitly turn hooks off. On `main`/`master`, hooks only enable at the session level (not branch-persisted), since these branches are shared. ## Hook Reference [Section titled “Hook Reference”](#hook-reference) | Hook | When It Fires | What It Does | | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **session-start** | Session created | Checks if the branch is enabled; auto-enables if so. | | **session-end** | Session ended | If reason is `/clear` and session was enabled, auto-enables on next session. | | **enable** | `/ranger:enable` | Runs `ranger update`, enables session + branch, outputs the full skill content to Claude’s context. | | **disable** | `/ranger:disable` | Disables session + branch, tells Claude to stop using Ranger commands. | | **stop** | Session stopping | If the active feature review still has unfinished items, adds a non-blocking reminder to verify before replying, unless verification is already running. If items are terminal, it tries to conclude the session. Fails open on conclude errors. | | **post-edit** | After file write/edit | If Ranger is enabled but no feature review is registered, suggests using `/ranger`. If a feature review exists, hints about adding scenarios if scope expanded. | | **pre-compact** | Before context compaction | Reminds Claude to preserve the Ranger Feature Review Specification in the compacted summary. | | **plan-start** | Entering plan mode | Instructs Claude to include a Ranger Feature Review Specification in the plan. | | **exit-plan-mode** | Leaving plan mode | Reminds Claude to create the feature review with `ranger create` before starting implementation. | # Autonomous Coding Loops > How Ranger fits into agentic development As our team has experimented with agentic development, we’ve come to the same conclusion as many others: an agent needs tools to verify its own work. The more effective those tools are, the longer an agent can productively run and stay on track. An agent that can verify its own work as it goes can ask for less direction and is much more likely to return with a mostly done (and mostly correct) result. Many tools exist to help agents verify their work. The most obvious ones are exactly the same ones that humans use – compilers, type checkers, tests. But UI development is different. Human developers examine results visually, interact with them, navigate through flows. This is a harder step for an agent. Playwright (often via Playwright MCP) is a powerful tool to give an agent insight into the browser experience. But it also incredibly context-hungry and testing multiple or repeated flows very often blows through the context and leads to repeated compactions and the corresponding loss of fidelity. An agent that spends most of its context on browser navigation has little left for the actual coding. ## Separating verification from coding [Section titled “Separating verification from coding”](#separating-verification-from-coding) Ideally, verification should be a separate process that’s hands-off for the coding agent. The agent kicks off a verification task, gets structured results back, and keeps its context for the work that matters: reading code, reasoning about architecture, writing changes. That’s what Ranger Feature Review does for browser-based verification. It does this by spawning a separate browser agent for each verification. This agent has its own context window and its own Playwright session, meaning that it doesn’t distract from coding and many can be run in parallel. The only job of each of these agents is to navigate the app and determine whether a specific behavior works. It returns a verdict (verified, failed, partial, or blocked) along with screenshots, video, and traces. The coding agent never touches the browser directly. This has a practical consequence: the write-verify loop can run many times without degrading. A coding agent using Playwright MCP might get three or four verification cycles before context pressure forces a compaction. With verification offloaded, the coding agent can iterate dozens of times and still have full recall of the codebase, the task, and its earlier decisions. ## Running without supervision [Section titled “Running without supervision”](#running-without-supervision) This also changes what it means to supervise an agent. With inline browser testing, you’re often watching the session because the agent will go off track after a compaction or two. When verification runs separately and returns structured results, the agent can self-correct reliably. It reads the verdict, looks at the failure reason, fixes the code, and verifies again. This is a loop that works while you’re not watching. This matters most for long-running sessions and background agents. If you kick off an agent before stepping away, you want to come back to a result, not a question. An agent with reliable UI verification can work through a feature end-to-end: implement the code, verify it in the browser, read the failure, fix the issue, verify again. Each iteration is cheap in context, and the structured feedback prevents the kind of drift that makes agents go in circles. Evidence accumulates as the agent works. Screenshots, video, and Playwright traces are uploaded to the dashboard at each verification step. When you come back, you’re not reading a conversation log trying to reconstruct what happened. You’re looking at screenshots of your app and a clear pass/fail for each behavior. ## The human review step [Section titled “The human review step”](#the-human-review-step) The agent writes and verifies in a tight inner cycle, then surfaces its work for human review.  The review happens asynchronously on the Ranger dashboard, where you can see exactly what the agent built and how it verified each behavior. If something needs to change, you leave a comment. The agent picks up that feedback, makes the fix, and re-verifies. This is a different relationship with the agent than live pair programming. You define the feature, the agent does the work and checks itself, and you review the evidence when it’s done. The agent’s ability to verify its own UI work is what makes the handoff trustworthy. # How Ranger Works > The architecture behind Ranger: CLI, plugin, browser agents, and dashboard. 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 [Section titled “Architecture”](#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 [Section titled “Components”](#components) ### Ranger CLI [Section titled “Ranger CLI”](#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 [Section titled “Skills”](#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 [Section titled “Claude Code Plugin”](#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 [Section titled “Browser Verification Agent”](#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 [Section titled “Ranger API”](#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 [Section titled “Feature Review Dashboard”](#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 [Section titled “How Verification Fits Into Development”](#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 [Section titled “Authentication”](#authentication) Ranger uses two layers of authentication. When you run `ranger setup`, you log in via browser. The CLI stores credentials locally and uses them to authenticate all CLI-to-API communication. Tokens refresh automatically. For details, see [Authentication](/reference/cli-overview/#authentication). 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 [Section titled “Data Flow”](#data-flow)  # Managing Profiles > Tell Ranger where your app runs and how to log in Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how the verification agent gets in. ## What a profile is [Section titled “What a profile is”](#what-a-profile-is) A profile bundles three things: * **An endpoint** — the URL where your app runs (e.g. `http://localhost:3000`, `https://staging.example.com`). * **An auth strategy** — how the verification agent gets logged in, if your app needs that. * **Browser settings** — headers, user agent, headless mode, and other knobs. Profiles are shared with everyone in your organization by default. That means a teammate can run `ranger go --profile alice@example.com` and reuse the session you captured — useful for sharing test accounts and for keeping CI in sync with what works on a developer’s laptop. Name profiles by the account they represent. Run `ranger profile ls` to see what’s set up. Run `ranger profile use ` to switch which profile `ranger go` uses by default. Create as many as you need — common patterns are one per environment, one per persona (free / paid / admin), or one per app you test. ## How Ranger logs into your app [Section titled “How Ranger logs into your app”](#how-ranger-logs-into-your-app) Ranger uses a profile to log into your app and capture a browser session it can use on every subsequent Feature Review. Three login mechanisms exist; Ranger uses them in this priority order: 1. **[Automated login](#automated-login)** — Ranger logs into your app for you, headless and deterministic, on every CI run, every background agent, every machine. Best for heavy usage and complex login flows involving SSO, OAuth, MFA, passkeys, custom auth, etc. If it’s configured for your app, this is the path that runs. Enterprise customers only. 2. **[Login instructions](#login-instructions)** — Ranger’s verification agent follows natural-language steps in a browser. Useful for flows an agent can complete on its own: hitting a debug-auth endpoint, setting a token in localStorage, navigating a custom form. Won’t work if a step needs a human or a second factor that Ranger can’t access. 3. **[Headed login](#headed-login)** — a browser opens, you log in once, Ranger captures the session. The universal default — works for any web app a person can sign into. Captured sessions are reused on every subsequent `ranger go` until they expire. When that happens, Ranger captures a fresh one using the same priority order. Two cases skip the login question entirely: * **[No login](#no-login)** — public sites, marketing pages, logged-out flows. Pass `--skip-auth`. * **[Electron / desktop apps](#electron-and-desktop-apps)** — speaks Chrome DevTools Protocol. Pass `--cdp-endpoint`. *** ### No login [Section titled “No login”](#no-login) For sites without authentication, just point Ranger at the URL: ```bash ranger profile add my-site --url http://localhost:3000 --skip-auth ``` `--skip-auth` skips the browser auth step. The profile is ready immediately. You can also use this for testing logged-out flows of an app that *does* have auth (e.g. the public landing page) — just don’t log in. *** ### Headed login [Section titled “Headed login”](#headed-login) The default for local development. Works with anything: username + password, SSO (Google, Okta, GitHub, WorkOS, etc.), OAuth, MFA at login. If a real user can log in, headed login captures the session. ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` A browser opens. Log in once with the account you want the agent to use. Close the browser when you’re done — Ranger saves the session. After that, every `ranger go` reuses the saved session until it expires. When it expires, run `ranger profile add` again to refresh. > **Naming tip.** Use a name that’s stable for the account you’re logging in as. An email works well; for accounts identified by username, phone, or anything else, use whatever’s stable. The name is just a label you’ll type when switching between profiles. #### Limits of headed login [Section titled “Limits of headed login”](#limits-of-headed-login) * A real human has to be at a keyboard to complete the initial login. For CI and background agents, see [automated login](#automated-login) or [login instructions](#login-instructions). * Magic-link, SMS-MFA, and hardware-key flows work if you can complete them in your browser, but the captured session is only as long-lived as the cookies your app issues. *** ### Automated login [Section titled “Automated login”](#automated-login) Enterprise customers only. Ranger logs into your app for you — no browser, no human in the loop — and captures a session that’s reused across every machine, CI run, and background agent. Set credentials as env vars and run `ranger go`: ```bash RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --base-url http://localhost:3000 \ --notes "user logs in and sees the dashboard" ``` When the session expires, Ranger logs in again automatically. #### Does this fit my app? [Section titled “Does this fit my app?”](#does-this-fit-my-app) Works for any login flow — SSO (Google, Okta, GitHub, WorkOS, etc.), OAuth, MFA, passkeys, magic links, custom forms, corporate auth. Bot protection, SSO routing, expiry rules, anything quirky about your app — we tune for it during onboarding. Setup is a call with our team. [Reach out](mailto:eng@ranger.net) and we’ll scope your case. While automated login is being configured: * For local dev, [headed login](#headed-login) works for any web app you can log into in a browser. * For CI, [login instructions](#login-instructions) is a fast bridge if your app has a debug-auth endpoint or short-lived tokens. #### What `--base-url` does and doesn’t change [Section titled “What --base-url does and doesn’t change”](#what---base-url-does-and-doesnt-change) `--base-url` controls **where the verification runs** — the URL the agent navigates to and interacts with. It does *not* control where login happens. Login runs against a stable URL we configure with you; the captured session is then reused against whatever `--base-url` you pass. This is by design: one profile, many environments. Your local dev instance, a Vercel preview, staging, prod — same session across all of them. If you find a case where a session doesn’t carry over between two of your domains, [let us know](mailto:eng@ranger.net) and we’ll tune the profile so it does. #### Multi-factor authentication [Section titled “Multi-factor authentication”](#multi-factor-authentication) Automated login handles MFA for any factor we can hold for your test account. Anything that needs a human in the moment with a personal device — push notifications to your phone, SMS or email codes Ranger can’t reach, a passkey registered to a personal account — won’t work for automated login. Use [headed login](#headed-login) once on your own machine for those; Ranger reuses the captured session for every subsequent run, anywhere. #### Bypassing bot protection during login [Section titled “Bypassing bot protection during login”](#bypassing-bot-protection-during-login) If your login page is behind a bot challenge that can be bypassed with a custom header (Cloudflare Turnstile, Datadome, etc.), set it on your profile and Ranger will send it during login: ```bash ranger profile config set alice@example.com setupHeaders.x-skip-turnstile "" ``` `setupHeaders.` is sent only during login, not during verification runs, so it won’t leak into third-party requests during the actual test. *** ### Login instructions [Section titled “Login instructions”](#login-instructions) Natural-language steps an LLM-driven browser follows to log in. Useful when [automated login](#automated-login) isn’t set up but the login flow is something an agent can complete — hitting a debug-auth endpoint, setting a token in localStorage, navigating a custom multi-step form. Create a profile without capturing login state, then describe the login flow in plain language: ```bash ranger profile add preview --url https://staging.example.com --skip-auth ranger profile config set preview loginInstructions \ "Navigate to ${BASE_URL}/api/debug-auth?email=test@example.com. \ Copy the token from the JSON response. \ Run in the browser console: localStorage.setItem('auth_token', ''). \ Refresh the page." ``` `${VAR_NAME}` resolves environment variables at runtime, so credentials don’t have to live in the instruction text. #### Limits of login instructions [Section titled “Limits of login instructions”](#limits-of-login-instructions) * Each step must be something the agent can do in a browser. Anything requiring a human (push notifications, hardware key taps, codes from inboxes Ranger can’t read) won’t work. * For deterministic flows that you’d want to run the same way every time, [automated login](#automated-login) is more reliable — talk to us about getting it set up. *** ## Browser settings [Section titled “Browser settings”](#browser-settings) Once a profile exists, fine-tune browser behavior with `ranger profile config`: ```bash ranger profile config set ``` | Key | What it does | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseUrl` | Override the profile’s URL for this directory (useful when one profile’s session works against multiple endpoints — local + staging, etc.) | | `headless` | `true`/`false`. Run the browser without a visible window. Headed is useful when you’re watching verification firsthand. | | `headers.` | Send a custom HTTP header with every request, e.g. `headers.Authorization`. Supports `${VAR}` for env vars. | | `setupHeaders.` | Like `headers.`, but only sent during the `ranger profile add` browser session — useful for bypassing login protection (Cloudflare Turnstile, etc.) without affecting third-party requests during runs. | | `userAgent` | Override the browser user agent. Useful for bypassing bot protection. | | `loginInstructions` | Plain-language login steps. See [Login instructions](#login-instructions). | | `allowInsecureLocalhost` | `true`/`false`. Allow localhost content in deployed environments (micro frontends, single-spa). Relaxes browser security; use only in dev. | | `cdpEndpoint` | Chrome DevTools Protocol endpoint for [Electron / desktop apps](#electron-and-desktop-apps). | ```bash ranger profile config list # show what's set ranger profile config unset # remove one key ranger profile config reset # clear all overrides ``` *** ## Picking which profile a run uses [Section titled “Picking which profile a run uses”](#picking-which-profile-a-run-uses) `ranger go` uses the active profile by default. Switch with: ```bash ranger profile use ``` Override per run with `--profile ` (or `RANGER_PROFILE=`). The flag wins. If you pass `--profile` for a name that doesn’t exist, the run fails immediately rather than falling back silently. The active profile is tracked per directory. Two checkouts of the same repo, in different directories, can each have their own active profile — useful when you’re running parallel agents against different environments. *** ## Multiple profiles [Section titled “Multiple profiles”](#multiple-profiles) You’ll want more than one profile when: ### Different environments for the same app [Section titled “Different environments for the same app”](#different-environments-for-the-same-app) Local dev, staging, preview deploys — each with its own URL but possibly the same login. ```bash ranger profile add alice@example.com --url http://localhost:3000 # initial setup ranger profile config set alice@example.com baseUrl '${PREVIEW_URL}' # in CI: PREVIEW_URL is set per-deploy ``` `${VAR}` references resolve at runtime, so one profile can target many deploys. ### Different accounts on the same app [Section titled “Different accounts on the same app”](#different-accounts-on-the-same-app) Free, paid, and enterprise users; admin vs. member; tenant A vs. tenant B. Add a profile per account; tell your coding agent which one to use for each scenario. ```bash ranger profile add free@example.com --url http://localhost:3000 ranger profile add admin@example.com --url http://localhost:3000 ``` Then in your prompt: *“Verify scenario 1 with `--profile free@example.com` and scenario 2 with `--profile admin@example.com`.”* ### Multiple apps that talk to each other [Section titled “Multiple apps that talk to each other”](#multiple-apps-that-talk-to-each-other) Customer-facing app on `localhost:3000`, internal admin tool on `localhost:3001`. One profile per app; the coding agent uses the right one per scenario. *** ## Electron and desktop apps [Section titled “Electron and desktop apps”](#electron-and-desktop-apps) Ranger can test Electron apps and other desktop applications that expose a Chrome DevTools Protocol (CDP) endpoint. There’s no URL to navigate to and no browser auth — Ranger attaches to the running app over CDP and starts interacting with the UI directly. **1. Start your app with remote debugging enabled:** ```bash your-electron-app --remote-debugging-port=9222 ``` Any port works. The app must be running before Ranger connects. **2. Add a profile pointing at the CDP endpoint:** ```bash ranger profile add my-electron-app --cdp-endpoint http://localhost:9222 ``` `--cdp-endpoint` skips URL reachability checks and browser auth — there’s no URL or browser to set up. **3. Run verifications normally:** ```bash ranger go --scenario 1 ``` The agent connects to your running app, takes a snapshot, and starts interacting. ### Limits of CDP profiles [Section titled “Limits of CDP profiles”](#limits-of-cdp-profiles) **Saved login sessions don’t work in CDP mode.** With web profiles, Ranger replays saved cookies into a fresh browser on every run. With Electron, Ranger attaches to a process that’s already running, so there’s no place to inject auth. If your Electron app needs a logged-in user, handle that at the app level — persist credentials, use env vars at launch, or skip login in development mode. *** ## Refreshing authentication [Section titled “Refreshing authentication”](#refreshing-authentication) When a saved session expires, the next `ranger go` will fail to authenticate. Refresh the session with: ```bash ranger profile update ``` `profile update` picks the right path based on how the profile is set up: * **Automated login configured**: re-runs server-side login (no browser, no human in the loop). * **Headed login**: opens a browser so you can log in again, then captures the session back to the cloud profile. * **Login instructions**: nothing to refresh — the verification agent re-runs them on every `ranger go`. You can also just re-run `ranger go` with `RANGER_TEST_USERNAME` / `RANGER_TEST_PASSWORD` set when automated login is configured — Ranger detects the stale session and logs in again automatically. ## Deleting a profile [Section titled “Deleting a profile”](#deleting-a-profile) ```bash ranger profile delete ``` This deletes the shared profile for everyone in your organization. You’ll be asked to type the name to confirm; pass `--yes` in scripted contexts. # Using Scenarios > Describe what to verify Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how to access it. Unlike profiles, scenarios are generally written by the coding agent. If you enable Ranger while in Plan Mode, the coding agent should include the scenarios it believes are necessary in the plan for implementation. These can be iterated on until you think they capture the flows correctly. The scenarios are also visible and editable on the Feature Review dashboard. ## Scenarios Basics [Section titled “Scenarios Basics”](#scenarios-basics) A scenario is a short, concrete user flow with an expected result. Ranger’s browser agent treats it both as a path to follow and a success condition to verify against. Scenarios are not entirely deterministic and are guidance more than a script. Like people visiting a site, each agent may take a slightly different path to accomplish the goal it’s given and the amount of variance depends on the specificity of the task. For instance, “Mark a checklist item as completed. Verify that the text is crossed out and the box is checked.” leaves agents room to choose any non-completed checklist item. They would also successfully toggle a “non-completed only” filter if they had to in order to find an appropriate example. Each scenario is verified on its own. They are not done in the same browser session (so frontend state does not carry over) or necessarily in the same order. Running a scenario can be backgrounded by the agent, so multiple may be run at once. If they are likely to interfere with each other’s background data, prompt the coding agent to run them serially. ## Writing Scenarios [Section titled “Writing Scenarios”](#writing-scenarios) A good scenario names the starting point, the action, and the expected result. Scenarios can contain complex paths through the app, but are generally easiest to verify and understand if they don’t contain multiple conditions. **Clear**: “User opens settings, toggles dark mode, page switches to dark theme.” **Vague**: “Add dark mode toggle.” **Too many conditions**: “A user should see the toggle on the top of the page if they’re logged in and at the bottom otherwise.” ## Shaping the List [Section titled “Shaping the List”](#shaping-the-list) Most feature reviews need only a few scenarios. The scenarios should focus on frontend behaviors and observable UI. A long checklist might be indicative of too many implementation details. The most effective scenarios are focused on what a person would do and see. # Supported Coding Agents > Ranger works with Claude Code, OpenCode, Cursor, Codex, and any agent with shell access. Here's how to set up each one. Ranger Feature Review works with any coding agent that can run bash commands. The table below shows what’s supported out of the box and links to the setup instructions for each agent. | Agent | Plugin | Skills | Setup Command | | ----------------------------- | --------------------------------------- | ---------------------------------- | ------------------------- | | [Claude Code](#claude-code) | Yes (`ranger@trailhead`) | `.claude/skills/` | `ranger setup` | | [OpenCode](#opencode) | Yes (`@ranger-testing/opencode-plugin`) | `.opencode/skills/` | `ranger setup --opencode` | | [Cursor](#cursor) | No | `.cursor/skills/` (via sym link) | `ranger setup` | | [Codex](#codex) | No | `.codex/skills/` (via sym link) | `ranger setup` | | [Other agents](#other-agents) | No | directory of choice (via sym link) | `ranger setup` | In the setup instructions below, we provide commands to sym link the skills into the appropriate directory. It will also work to copy or move them, but the `ranger update` command will automatically update the skills to match new CLI versions and sym linking allows those updates to be immediately picked up by your coding agent. *** ## Claude Code [Section titled “Claude Code”](#claude-code) Claude Code is Ranger’s primary integration. The `ranger setup` command installs a Claude Code plugin and skills automatically. **Quickstart:** Follow the full [Quickstart](/getting-started/quickstart/) guide. **What you get:** * **Plugin** — Connects Ranger to Claude’s hook system. Ranger can automatically activate at the right moments in your workflow. * **Skills** — Markdown files installed to `.claude/skills/` that teach Claude how to create feature reviews, run verifications, and address feedback. * **Slash commands** — `/ranger:enable`, `/ranger:disable`, and `/ranger:resume` for quick control. *** ## OpenCode [Section titled “OpenCode”](#opencode) OpenCode has its own plugin and skill paths. Use the `--opencode` flag during setup. **Quickstart:** Follow the [OpenCode Quickstart](/getting-started/quickstart-opencode/) guide. **What you get:** * **Plugin** — The `@ranger-testing/opencode-plugin` package, configured in your `opencode.json`. * **Skills** — Markdown files installed to `.opencode/skills/`. * **Natural language activation** — Tell your agent to “enable ranger” instead of slash commands. *** ## Cursor [Section titled “Cursor”](#cursor) Cursor 2.4+ reads `.claude/skills/` for compatibility, so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the `.cursor/skills` directory: ```sh ln -s ~/.claude/skills/ranger ~/.cursor/skills/ranger ``` The skills work without a plugin, but you may have to remind the agent to use it after compaction or later in the context window. Invoke the skill with `/ranger` or `@ranger` in Cursor’s Agent chat (e.g. “Use @ranger to create a feature review and verify it”). *** ## Codex [Section titled “Codex”](#codex) Codex reads `.claude/skills/` (and `.codex/skills/`), so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the Codex skills directory: ```sh ln -s ~/.claude/skills/ranger ~/.codex/skills/ranger ``` Codex’s default permissions mode blocks most network access, so Ranger will fail until permissions are adjusted. For an individual session, the slash command `/permissions` will allow you to update to Full Access. For a more enduring fix, you can add Ranger and network permissions by default: ```sh echo 'prefix_rule(pattern=["ranger"], decision="allow")' >> ~/.codex/rules/default.rules ``` and update `~/.codex/config.toml` with: ```plaintext sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true ``` *** ## Other Agents [Section titled “Other Agents”](#other-agents) Any coding agent that can execute bash commands can use Ranger. The core workflow is: 1. Install CLI and authenticate: `npm install -g @ranger-testing/ranger-cli && ranger setup` 2. Install skills: Say yes when prompted, or run `ranger skillup` separately. Skills are installed to `.claude/skills/ranger/` by default. 3. (optional) Link skills: if your agent looks for skills in a specific directory, sym link the ranger skill into that directory. 4. Use the CLI: Your agent runs `ranger create`, `ranger go`, `ranger show`, etc. The skill files are plain markdown — they work as instructions for any LLM-based agent. Want a dedicated integration? If you’re using an agent or harness that would benefit from an integration, [let us know](mailto:eng@ranger.net)! # Ranger Feature Review > Automated browser verification and feature review for agentic development. [Ranger](https://www.ranger.net) is the always-on AI QA platform for teams that gives you higher signal, less noise, and faster launches. Ranger Feature Review brings that QA expertise to agentic development. When you ask an AI coding agent to build a feature, Ranger verifies it actually works in a real browser, with real evidence, and gives your team a way to review it collaboratively. ## Demo [Section titled “Demo”](#demo) Want to see it in action? Here’s a quick demo. [Ranger Feature Review Demo](https://www.youtube.com/embed/TB6eHLGtaD4) ## The Problem [Section titled “The Problem”](#the-problem) When you ask Claude to build a feature, it might come back to you with a fully working feature, but you can’t tell until you open your app and click through the full workflow involved. And half the time, it writes code that can’t even be built or fails as soon as the page is loaded. ## How Ranger Feature Review Fixes This [Section titled “How Ranger Feature Review Fixes This”](#how-ranger-feature-review-fixes-this) Ranger acts as your AI agent’s QA team. When your coding agent says it’s done, Ranger runs local browser agents that step through your user flows and verify your features truly look and work the way they’re supposed to. ### 1. Automated Browser Verification [Section titled “1. Automated Browser Verification”](#1-automated-browser-verification) Before your agent says “done,” Ranger tests the feature in a real browser. If something’s broken, Ranger tells the agent to fix it automatically. The agent keeps iterating until Ranger confirms everything works. ### 2. Feature Review Dashboard [Section titled “2. Feature Review Dashboard”](#2-feature-review-dashboard) Every verification produces evidence: screenshots, video recordings, and Playwright traces. Ranger presents this in a review interface (think GitHub PR review, but for UI features). You and your team can browse the evidence, leave comments, approve, or request changes. ### 3. One-Click E2E Tests [Section titled “3. One-Click E2E Tests”](#3-one-click-e2e-tests) Once a feature is verified and approved, you’re one click away from turning it into a permanent end-to-end test in your Ranger test suite. ## The Development Cycle [Section titled “The Development Cycle”](#the-development-cycle) When you start working on something new, create a `feature review` with the Ranger CLI that describes what should be verified (this is a natural extension of an agent’s Plan mode). After your agent writes code, it should automatically run `ranger go` to walk through the flows, capturing evidence of everything it encounters. If everything works, great! Your agent can wrap up, let you know it’s done, and you can take a look at the Ranger Feature Review link to get a walkthrough and ask for changes. If the browser agent finds an issue, it’ll describe it to your coding agent and they’ll iterate until it works or your coding agent decides the work is fully blocked and it needs a human in the loop.  Hey Agents Sound interesting? We’ve got docs just for you. Take a look at [llms.txt](llms.txt). ## Get Started [Section titled “Get Started”](#get-started) * [Quickstart](/getting-started/quickstart). Set up Ranger in 5 minutes and verify your first feature review. * [OpenCode Quickstart](/getting-started/quickstart-opencode). Use OpenCode instead? We can work with that. * [Supported Coding Agents](/getting-started/supported-agents). Using Cursor, Codex, or another agent? Find setup instructions here. * [How It Works](/concepts/how-it-works). The architecture: CLI, plugin, browser agents, and dashboard. * [Ranger In Autonomous Loops](/concepts/autonomous-loop). How Ranger Feature Review supports more autonomous agentic coding. # Autonomous Coding Loops > How Ranger fits into agentic development As our team has experimented with agentic development, we’ve come to the same conclusion as many others: an agent needs tools to verify its own work. The more effective those tools are, the longer an agent can productively run and stay on track. An agent that can verify its own work as it goes can ask for less direction and is much more likely to return with a mostly done (and mostly correct) result. Many tools exist to help agents verify their work. The most obvious ones are exactly the same ones that humans use – compilers, type checkers, tests. But UI development is different. Human developers examine results visually, interact with them, navigate through flows. This is a harder step for an agent. Playwright (often via Playwright MCP) is a powerful tool to give an agent insight into the browser experience. But it also incredibly context-hungry and testing multiple or repeated flows very often blows through the context and leads to repeated compactions and the corresponding loss of fidelity. An agent that spends most of its context on browser navigation has little left for the actual coding. ## Separating verification from coding [Section titled “Separating verification from coding”](#separating-verification-from-coding) Ideally, verification should be a separate process that’s hands-off for the coding agent. The agent kicks off a verification task, gets structured results back, and keeps its context for the work that matters: reading code, reasoning about architecture, writing changes. That’s what Ranger Feature Review does for browser-based verification. It does this by spawning a separate browser agent for each verification. This agent has its own context window and its own Playwright session, meaning that it doesn’t distract from coding and many can be run in parallel. The only job of each of these agents is to navigate the app and determine whether a specific behavior works. It returns a verdict (verified, failed, partial, or blocked) along with screenshots, video, and traces. The coding agent never touches the browser directly. This has a practical consequence: the write-verify loop can run many times without degrading. A coding agent using Playwright MCP might get three or four verification cycles before context pressure forces a compaction. With verification offloaded, the coding agent can iterate dozens of times and still have full recall of the codebase, the task, and its earlier decisions. ## Running without supervision [Section titled “Running without supervision”](#running-without-supervision) This also changes what it means to supervise an agent. With inline browser testing, you’re often watching the session because the agent will go off track after a compaction or two. When verification runs separately and returns structured results, the agent can self-correct reliably. It reads the verdict, looks at the failure reason, fixes the code, and verifies again. This is a loop that works while you’re not watching. This matters most for long-running sessions and background agents. If you kick off an agent before stepping away, you want to come back to a result, not a question. An agent with reliable UI verification can work through a feature end-to-end: implement the code, verify it in the browser, read the failure, fix the issue, verify again. Each iteration is cheap in context, and the structured feedback prevents the kind of drift that makes agents go in circles. Evidence accumulates as the agent works. Screenshots, video, and Playwright traces are uploaded to the dashboard at each verification step. When you come back, you’re not reading a conversation log trying to reconstruct what happened. You’re looking at screenshots of your app and a clear pass/fail for each behavior. ## The human review step [Section titled “The human review step”](#the-human-review-step) The agent writes and verifies in a tight inner cycle, then surfaces its work for human review.  The review happens asynchronously on the Ranger dashboard, where you can see exactly what the agent built and how it verified each behavior. If something needs to change, you leave a comment. The agent picks up that feedback, makes the fix, and re-verifies. This is a different relationship with the agent than live pair programming. You define the feature, the agent does the work and checks itself, and you review the evidence when it’s done. The agent’s ability to verify its own UI work is what makes the handoff trustworthy. # How Ranger Works > The architecture behind Ranger: CLI, plugin, browser agents, and dashboard. 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 [Section titled “Architecture”](#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 [Section titled “Components”](#components) ### Ranger CLI [Section titled “Ranger CLI”](#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 [Section titled “Skills”](#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 [Section titled “Claude Code Plugin”](#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 [Section titled “Browser Verification Agent”](#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 [Section titled “Ranger API”](#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 [Section titled “Feature Review Dashboard”](#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 [Section titled “How Verification Fits Into Development”](#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 [Section titled “Authentication”](#authentication) Ranger uses two layers of authentication. When you run `ranger setup`, you log in via browser. The CLI stores credentials locally and uses them to authenticate all CLI-to-API communication. Tokens refresh automatically. For details, see [Authentication](/reference/cli-overview/#authentication). 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 [Section titled “Data Flow”](#data-flow)  # Managing Profiles > Tell Ranger where your app runs and how to log in Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how the verification agent gets in. ## What a profile is [Section titled “What a profile is”](#what-a-profile-is) A profile bundles three things: * **An endpoint** — the URL where your app runs (e.g. `http://localhost:3000`, `https://staging.example.com`). * **An auth strategy** — how the verification agent gets logged in, if your app needs that. * **Browser settings** — headers, user agent, headless mode, and other knobs. Profiles are shared with everyone in your organization by default. That means a teammate can run `ranger go --profile alice@example.com` and reuse the session you captured — useful for sharing test accounts and for keeping CI in sync with what works on a developer’s laptop. Name profiles by the account they represent. Run `ranger profile ls` to see what’s set up. Run `ranger profile use ` to switch which profile `ranger go` uses by default. Create as many as you need — common patterns are one per environment, one per persona (free / paid / admin), or one per app you test. ### Profiles for multi-actor scenarios [Section titled “Profiles for multi-actor scenarios”](#profiles-for-multi-actor-scenarios) For a flow involving two actors, for example a buyer and seller conducting a marketplace transaction, create a profile for each account before verification. Then bind those profiles to the scenario’s role labels with `ranger go --actor =`. The [multi-actor scenario guide](../scenarios/#multi-actor-scenarios) shows the complete workflow and its two-actor limit. ## How Ranger logs into your app [Section titled “How Ranger logs into your app”](#how-ranger-logs-into-your-app) Ranger uses a profile to log into your app and capture a browser session it can use on every subsequent Feature Review. Three login mechanisms exist; Ranger uses them in this priority order: 1. **[Automated login](#automated-login)** — Ranger logs into your app for you, headless and deterministic, on every CI run, every background agent, every machine. Best for heavy usage and complex login flows involving SSO, OAuth, MFA, passkeys, custom auth, etc. If it’s configured for your app, this is the path that runs. Enterprise customers only. 2. **[Login instructions](#login-instructions)** — Ranger’s verification agent follows natural-language steps in a browser. Useful for flows an agent can complete on its own: hitting a debug-auth endpoint, setting a token in localStorage, navigating a custom form. Won’t work if a step needs a human or a second factor that Ranger can’t access. 3. **[Headed login](#headed-login)** — a browser opens, you log in once, Ranger captures the session. The universal default — works for any web app a person can sign into. Captured sessions are reused on every subsequent `ranger go` until they expire. When that happens, Ranger captures a fresh one using the same priority order. Two cases skip the login question entirely: * **[No login](#no-login)** — public sites, marketing pages, logged-out flows. Pass `--skip-auth`. * **[Electron / desktop apps](#electron-and-desktop-apps)** — speaks Chrome DevTools Protocol. Pass `--cdp-endpoint`. *** ### No login [Section titled “No login”](#no-login) For sites without authentication, just point Ranger at the URL: ```bash ranger profile add my-site --url http://localhost:3000 --skip-auth ``` `--skip-auth` skips the browser auth step. The profile is ready immediately. You can also use this for testing logged-out flows of an app that *does* have auth (e.g. the public landing page) — just don’t log in. *** ### Headed login [Section titled “Headed login”](#headed-login) The default for local development. Works with anything: username + password, SSO (Google, Okta, GitHub, WorkOS, etc.), OAuth, MFA at login. If a real user can log in, headed login captures the session. ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` A browser opens. Log in once with the account you want the agent to use. Close the browser when you’re done — Ranger saves the session. After that, every `ranger go` reuses the saved session until it expires. When it expires, run `ranger profile add` again to refresh. > **Naming tip.** Use a name that’s stable for the account you’re logging in as. An email works well; for accounts identified by username, phone, or anything else, use whatever’s stable. The name is just a label you’ll type when switching between profiles. #### Limits of headed login [Section titled “Limits of headed login”](#limits-of-headed-login) * A real human has to be at a keyboard to complete the initial login. For CI and background agents, see [automated login](#automated-login) or [login instructions](#login-instructions). * Magic-link, SMS-MFA, and hardware-key flows work if you can complete them in your browser, but the captured session is only as long-lived as the cookies your app issues. *** ### Automated login [Section titled “Automated login”](#automated-login) Enterprise customers only. Ranger logs into your app for you — no browser, no human in the loop — and captures a session that’s reused across every machine, CI run, and background agent. Set credentials as env vars and run `ranger go`: ```bash RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --env --base-url http://localhost:3000 \ --notes "user logs in and sees the dashboard" ``` When the session expires, Ranger logs in again automatically. #### Does this fit my app? [Section titled “Does this fit my app?”](#does-this-fit-my-app) Works for any login flow — SSO (Google, Okta, GitHub, WorkOS, etc.), OAuth, MFA, passkeys, magic links, custom forms, corporate auth. Bot protection, SSO routing, expiry rules, anything quirky about your app — we tune for it during onboarding. Setup is a call with our team. [Reach out](mailto:eng@ranger.net) and we’ll scope your case. While automated login is being configured: * For local dev, [headed login](#headed-login) works for any web app you can log into in a browser. * For CI, [login instructions](#login-instructions) is a fast bridge if your app has a debug-auth endpoint or short-lived tokens. #### What `--base-url` does and doesn’t change [Section titled “What --base-url does and doesn’t change”](#what---base-url-does-and-doesnt-change) `--base-url` controls **where the verification runs** — the URL the agent navigates to and interacts with. It does *not* control where login happens. Login runs against a stable URL we configure with you; the captured session is then reused against whatever `--base-url` you pass. This is by design: one profile, many environments. Your local dev instance, a Vercel preview, staging, prod — same session across all of them. If you find a case where a session doesn’t carry over between two of your domains, [let us know](mailto:eng@ranger.net) and we’ll tune the profile so it does. `--header "Name: Value"` works the same way: it adds a request header for that run only (repeatable; merged over the profile’s configured `headers.`, flag wins). Login is unaffected — login-time headers stay on `setupHeaders.` — so the cached session is reused as usual. Useful when the header value differs per run, e.g. routing each PR’s verification into its own preview environment. #### Multi-factor authentication [Section titled “Multi-factor authentication”](#multi-factor-authentication) Automated login handles MFA for any factor we can hold for your test account. Anything that needs a human in the moment with a personal device — push notifications to your phone, SMS or email codes Ranger can’t reach, a passkey registered to a personal account — won’t work for automated login. Use [headed login](#headed-login) once on your own machine for those; Ranger reuses the captured session for every subsequent run, anywhere. #### Bypassing bot protection during login [Section titled “Bypassing bot protection during login”](#bypassing-bot-protection-during-login) If your login page is behind a bot challenge that can be bypassed with a custom header (Cloudflare Turnstile, Datadome, etc.), set it on your profile and Ranger will send it during login: ```bash ranger profile config set alice@example.com setupHeaders.x-skip-turnstile "" ``` `setupHeaders.` is sent only during login, not during verification runs, so it won’t leak into third-party requests during the actual test. #### Multiple environments (e.g. local backend) [Section titled “Multiple environments (e.g. local backend)”](#multiple-environments-eg-local-backend) If we’ve configured more than one login environment for your team — say production plus a local-backend setup — Ranger picks one by matching your target URL, and you can always name it explicitly with `--env`: ```bash # one-shot, no profile creation: pick the env, point at your local app RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --env local-backend --base-url http://localhost:3001 \ --check "dashboard loads after login" ``` How matching works for a target URL: * An exact `scheme://host:port` match for an environment always wins. * A configured hostname matches on **any port** — dev ports vary per machine, so `localhost.example.com:3003` also covers `:3004`, `:3005`, etc. * Bare `localhost` / `127.0.0.1` is the exception: that hostname is shared by every app on your machine, so a non-standard local port needs `--env` (or `RANGER_AUTH_ENV`) to say which environment it is. `--env` works the same way on `ranger profile add` if you’d rather save a reusable profile than pass it each run. It also works on `ranger go --profile `: there it asserts the env and overrides the profile’s pinned env for that run, so it’s not limited to the ad-hoc and `profile add` flows. For background agents and CI, set `RANGER_AUTH_ENV` (and `RANGER_BASE_URL`) once in the environment so individual `ranger go` calls stay clean. *** ### Login instructions [Section titled “Login instructions”](#login-instructions) Natural-language steps an LLM-driven browser follows to log in. Useful when [automated login](#automated-login) isn’t set up but the login flow is something an agent can complete — hitting a debug-auth endpoint, setting a token in localStorage, navigating a custom multi-step form. Create a profile without capturing login state, then describe the login flow in plain language: ```bash ranger profile add preview --url https://staging.example.com --skip-auth ranger profile config set preview loginInstructions \ "Navigate to ${BASE_URL}/api/debug-auth?email=test@example.com. \ Copy the token from the JSON response. \ Run in the browser console: localStorage.setItem('auth_token', ''). \ Refresh the page." ``` `${VAR_NAME}` resolves environment variables at runtime, so credentials don’t have to live in the instruction text. #### Limits of login instructions [Section titled “Limits of login instructions”](#limits-of-login-instructions) * Each step must be something the agent can do in a browser. Anything requiring a human (push notifications, hardware key taps, codes from inboxes Ranger can’t read) won’t work. * For deterministic flows that you’d want to run the same way every time, [automated login](#automated-login) is more reliable — talk to us about getting it set up. *** ## Browser settings [Section titled “Browser settings”](#browser-settings) Once a profile exists, fine-tune browser behavior with `ranger profile config`: ```bash ranger profile config set ``` | Key | What it does | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseUrl` | Override the profile’s URL for this directory (useful when one profile’s session works against multiple endpoints — local + staging, etc.) | | `headless` | `true`/`false`. Run the browser without a visible window. Headed is useful when you’re watching verification firsthand. | | `headers.` | Send a custom HTTP header with every request, e.g. `headers.Authorization`. Supports `${VAR}` for env vars. Profile config is shared org-wide — for a header scoped to one run, pass `--header "Name: Value"` to `ranger go` instead. | | `setupHeaders.` | Like `headers.`, but only sent during the `ranger profile add` browser session — useful for bypassing login protection (Cloudflare Turnstile, etc.) without affecting third-party requests during runs. | | `userAgent` | Override the browser user agent. Useful for bypassing bot protection. | | `loginInstructions` | Plain-language login steps. See [Login instructions](#login-instructions). | | `allowInsecureLocalhost` | `true`/`false`. Allow localhost content in deployed environments (micro frontends, single-spa). Relaxes browser security; use only in dev. | | `cdpEndpoint` | Chrome DevTools Protocol endpoint for [Electron / desktop apps](#electron-and-desktop-apps). | ```bash ranger profile config list # show what's set ranger profile config unset # remove one key ranger profile config reset # clear all overrides ``` *** ## Picking which profile a run uses [Section titled “Picking which profile a run uses”](#picking-which-profile-a-run-uses) `ranger go` uses the active profile by default. Switch with: ```bash ranger profile use ``` Override per run with `--profile ` (or `RANGER_PROFILE=`). The flag wins. If you pass `--profile` for a name that doesn’t exist, the run fails immediately rather than falling back silently. The active profile is tracked per directory. Two checkouts of the same repo, in different directories, can each have their own active profile — useful when you’re running parallel agents against different environments. *** ## Multiple profiles [Section titled “Multiple profiles”](#multiple-profiles) You’ll want more than one profile when: ### Different environments for the same app [Section titled “Different environments for the same app”](#different-environments-for-the-same-app) Local dev, staging, preview deploys — each with its own URL but possibly the same login. ```bash ranger profile add alice@example.com --url http://localhost:3000 # initial setup ranger profile config set alice@example.com baseUrl '${PREVIEW_URL}' # in CI: PREVIEW_URL is set per-deploy ``` `${VAR}` references resolve at runtime, so one profile can target many deploys. ### Different accounts on the same app [Section titled “Different accounts on the same app”](#different-accounts-on-the-same-app) Free, paid, and enterprise users; admin vs. member; tenant A vs. tenant B. Add a profile per account; tell your coding agent which one to use for each scenario. ```bash ranger profile add free@example.com --url http://localhost:3000 ranger profile add admin@example.com --url http://localhost:3000 ``` Then in your prompt: *“Verify scenario 1 with `--profile free@example.com` and scenario 2 with `--profile admin@example.com`.”* ### Multiple apps that talk to each other [Section titled “Multiple apps that talk to each other”](#multiple-apps-that-talk-to-each-other) Customer-facing app on `localhost:3000`, internal admin tool on `localhost:3001`. One profile per app; the coding agent uses the right one per scenario. *** ## Electron and desktop apps [Section titled “Electron and desktop apps”](#electron-and-desktop-apps) Ranger can test Electron apps and other desktop applications that expose a Chrome DevTools Protocol (CDP) endpoint. There’s no URL to navigate to and no browser auth — Ranger attaches to the running app over CDP and starts interacting with the UI directly. **1. Start your app with remote debugging enabled:** ```bash your-electron-app --remote-debugging-port=9222 ``` Any port works. The app must be running before Ranger connects. **2. Add a profile pointing at the CDP endpoint:** ```bash ranger profile add my-electron-app --cdp-endpoint http://localhost:9222 ``` `--cdp-endpoint` skips URL reachability checks and browser auth — there’s no URL or browser to set up. **3. Run verifications normally:** ```bash ranger go --scenario 1 ``` The agent connects to your running app, takes a snapshot, and starts interacting. ### Limits of CDP profiles [Section titled “Limits of CDP profiles”](#limits-of-cdp-profiles) **Saved login sessions don’t work in CDP mode.** With web profiles, Ranger replays saved cookies into a fresh browser on every run. With Electron, Ranger attaches to a process that’s already running, so there’s no place to inject auth. If your Electron app needs a logged-in user, handle that at the app level — persist credentials, use env vars at launch, or skip login in development mode. *** ## Refreshing authentication [Section titled “Refreshing authentication”](#refreshing-authentication) When a saved session expires, the next `ranger go` will fail to authenticate. Refresh the session with: ```bash ranger profile update ``` `profile update` picks the right path based on how the profile is set up: * **Automated login configured**: re-runs server-side login (no browser, no human in the loop). * **Headed login**: opens a browser so you can log in again, then captures the session back to the cloud profile. * **Login instructions**: nothing to refresh — the verification agent re-runs them on every `ranger go`. You can also just re-run `ranger go` with `RANGER_TEST_USERNAME` / `RANGER_TEST_PASSWORD` set when automated login is configured — Ranger detects the stale session and logs in again automatically. ## Deleting a profile [Section titled “Deleting a profile”](#deleting-a-profile) ```bash ranger profile delete ``` This deletes the shared profile for everyone in your organization. You’ll be asked to type the name to confirm; pass `--yes` in scripted contexts. # Using Scenarios > Describe what to verify Two concepts keep your agent focused: **scenarios** and **profiles**. Scenarios describe what to test. Profiles describe where to test and how to access it. Unlike profiles, scenarios are generally written by the coding agent. If you enable Ranger while in Plan Mode, the coding agent should include the scenarios it believes are necessary in the plan for implementation. These can be iterated on until you think they capture the flows correctly. The scenarios are also visible and editable on the Feature Review dashboard. ## Scenarios Basics [Section titled “Scenarios Basics”](#scenarios-basics) A scenario is a short, concrete user flow with an expected result. Ranger’s browser agent treats it both as a path to follow and a success condition to verify against. Scenarios are not entirely deterministic and are guidance more than a script. Like people visiting a site, each agent may take a slightly different path to accomplish the goal it’s given and the amount of variance depends on the specificity of the task. For instance, “Mark a checklist item as completed. Verify that the text is crossed out and the box is checked.” leaves agents room to choose any non-completed checklist item. They would also successfully toggle a “non-completed only” filter if they had to in order to find an appropriate example. Each scenario is verified on its own. They are not done in the same browser session (so frontend state does not carry over) or necessarily in the same order. Running a scenario can be backgrounded by the agent, so multiple may be run at once. If they are likely to interfere with each other’s background data, prompt the coding agent to run them serially. ## Multi-actor scenarios [Section titled “Multi-actor scenarios”](#multi-actor-scenarios) Use a multi-actor scenario when the behavior depends on two people acting at the same time: a buyer and seller, an admin and member, or two viewers collaborating in real time. Ranger gives one verification agent a separate live browser session for each actor, so it can switch between their independent logins while shared app state remains real. ### 1. Create the profiles first [Section titled “1. Create the profiles first”](#1-create-the-profiles-first) Each actor must be bound to an existing Ranger profile. Create a profile for every account you need, then confirm their names with `ranger profile ls`: ```bash ranger profile add buyer@acme.com --url https://app.acme.com ranger profile add seller@acme.com --url https://app.acme.com ranger profile ls ``` The initial profile setup captures each account’s login separately. Multi-actor verification cannot use the one-shot `RANGER_TEST_USERNAME` credential flow; both profiles must already exist. ### 2. Write the scenario as turns [Section titled “2. Write the scenario as turns”](#2-write-the-scenario-as-turns) Name every turn with the role that should perform it. The role labels in the scenario must match the labels passed to `--actor` when you verify it. Be explicit about the order: the agent keeps each actor’s page open and returns to it where the previous turn left off. ```text As buyer, add the last item to the cart. As seller, purchase the same item. Back as buyer, continue to checkout and verify that the item is no longer available. ``` This is useful for flows that cannot be reproduced by logging out and back in between steps. Keep the turns in one scenario so Ranger can preserve the live sessions and verify the interaction as a whole. ### 3. Verify with two actor bindings [Section titled “3. Verify with two actor bindings”](#3-verify-with-two-actor-bindings) Repeat `--actor` once for each role, using the form `=`: ```bash ranger go --scenario 1 \ --actor buyer=buyer@acme.com \ --actor seller=seller@acme.com ``` Ranger uses the profile behind each binding to open two isolated browser sessions. One verification agent follows the scenario in order, selecting the session that matches each `As buyer` or `As seller` turn. Screenshots, traces, and other evidence are captured for both sessions and attached to the feature review. For a fresh one-scenario review, combine the same bindings with `--check`: ```bash ranger go \ --actor buyer=buyer@acme.com \ --actor seller=seller@acme.com \ --check "As buyer, add the last item to the cart. As seller, buy it. Back as buyer, verify checkout shows it is unavailable." ``` ### Limits and naming rules [Section titled “Limits and naming rules”](#limits-and-naming-rules) * Multi-actor verification currently supports exactly two actor bindings per run. * Labels must be unique, begin with a letter or number, and may contain letters, numbers, hyphens, or underscores. * You may bind two labels to the same profile when you need two live sessions for the same account, such as a real-time synchronization flow. * Ranger automatically uses the Playwright CLI transport for multi-actor verification; no transport configuration is required. ## Writing Scenarios [Section titled “Writing Scenarios”](#writing-scenarios) A good scenario names the starting point, the action, and the expected result. Scenarios can contain complex paths through the app, but are generally easiest to verify and understand if they don’t contain multiple conditions. **Clear**: “User opens settings, toggles dark mode, page switches to dark theme.” **Vague**: “Add dark mode toggle.” **Too many conditions**: “A user should see the toggle on the top of the page if they’re logged in and at the bottom otherwise.” ## Shaping the List [Section titled “Shaping the List”](#shaping-the-list) Most feature reviews need only a few scenarios. The scenarios should focus on frontend behaviors and observable UI. A long checklist might be indicative of too many implementation details. The most effective scenarios are focused on what a person would do and see. # Quickstart > Get Ranger Feature Review running in your project in about 5 minutes. Already set up? Head to the [Ranger Feature Review Dashboard](https://dashboard.ranger.net) to manage your feature reviews, or check out the [CLI Overview](/reference/cli-overview) for a full list of commands. Get Ranger Feature Review running in your project in about 5 minutes. By the end, your AI coding agent will be able to verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 18 or later * **Claude Code** (or your favorite AI coding agent) * A web application running locally (e.g., on `localhost:3000`) ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project’s root directory (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh ``` This installs the CLI and walks you through interactive setup. If you prefer to install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup ``` ** *Note: If `ranger` conflicts with another program on your system (e.g. the ranger file manager), you can use `ranger-cli` instead for all commands.* This walks you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or another non-interactive setting like an agent sandbox, see the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. The short version: pass a token directly (`ranger setup [token]`) or set the `RANGER_CLI_TOKEN` env var. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). If API keys are challenging in your setup, other approaches are available for enterprise customers — [get in touch](mailto:support@ranger.net). ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### Claude Code Plugin [Section titled “Claude Code Plugin”](#claude-code-plugin) The plugin connects Ranger to Claude’s workflow so it can use the Ranger CLI intuitively. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git (requires a `.claude/` directory). Not using Claude Code? This workflow is focused on Claude Code because that’s what we used when developing and testing it. We also have an OpenCode plugin & skill installation, see [Getting Started with OpenCode](/getting-started/quickstart-opencode). And the skills and CLI work for any coding agent with shell access. See [Supported Coding Agents](/getting-started/supported-agents/) for more detail on how we recommend configuring it for Cursor, Codex and more. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. ```plaintext Would you like to install skills? (Y/n) ``` Say **yes**. Skills are markdown files that get installed into your `.claude/skills/` directory. They tell Claude when and how to create feature reviews, run verifications, and address feedback. ### Profile [Section titled “Profile”](#profile) A profile tells Ranger where your app runs and how to log in. See [Managing Profiles](/concepts/profiles) for the full picture; the quickstart covers the simplest case. After `ranger setup` finishes, create a profile for your app. Use a stable name (an email works well): ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` Ranger checks the URL is reachable, then opens Chromium so you can log in (if your app needs that). **Close the browser when you’re done.** Ranger saves the session, and the verification agent reuses it on every run. Profiles are shared with everyone in your organization by default, so name them by the account they represent. Run `ranger profile ls` to see what’s set up. Different setup for your app? * **No login at all** (logged-out flows, public pages): `ranger profile add my-site --url http://localhost:3000 --skip-auth` * **Running in CI or a background agent** (no human at a keyboard): see [Background Agent and CI Setup](/reference/background-agents-and-ci/). * **Short-lived tokens or a debug auth endpoint**: see [Login instructions](/concepts/profiles/#login-instructions). *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open Claude Code in your project. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) For deterministic setup, enable Ranger from the start of each Claude Code session by adding `RANGER_HOOKS=on` to your Claude Code settings: ```json { "env": { "RANGER_HOOKS": "on" } } ``` This activates Ranger’s hooks automatically at session start. You can still use `/ranger:enable` as a manual session override, and `/ranger:disable` to turn Ranger off for the current session and branch. ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask Claude to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, Claude will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, Claude fixes them and re-verifies automatically. 5. Once everything passes, Claude shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you run `/ranger:resume` in Claude Code.  ## What’s Next [Section titled “What’s Next”](#whats-next) * [Profiles](/concepts/profiles) define where to test and how to access it. * [Scenarios](/concepts/scenarios) are the user flows to guide the verification agent. * [CLI Overview](/reference/cli-overview) gives you (or your agent) extra info about all the available commands. * [CLI Overview](/reference/cli-overview/#authentication) covers all authentication options including CI tokens and managed platforms. # OpenCode Quickstart > Set up Ranger Feature Review with OpenCode. Get Ranger Feature Review running with OpenCode. By the end, your agent will verify UI features in a real browser. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Node.js 18 or later * OpenCode * A web application running locally ## Install & Setup [Section titled “Install & Setup”](#install--setup) From your project root (it should be a git repo): ```bash curl -LsSf https://cli.ranger.net/install.sh | sh -s -- --opencode ``` This installs the CLI and runs interactive setup with OpenCode preconfigured. Or install manually: ```bash npm install -g @ranger-testing/ranger-cli ranger setup --opencode ``` This command will walk you through the full setup interactively. Here’s what each step does: ### Authentication [Section titled “Authentication”](#authentication) Ranger opens your browser to log in. Authorize the CLI, and it stores your credentials securely. > If you’re setting up in CI or from a non-interactive agent, pass a token directly: `ranger setup --opencode [token]`. Get a token from your [Ranger Dashboard](https://dashboard.ranger.net/cli). See also the [Background Agent and CI Setup](/reference/background-agents-and-ci/) guide. ### Chromium Browser [Section titled “Chromium Browser”](#chromium-browser) Ranger uses Playwright’s Chromium to run browser verifications. We require a specific version. If that version isn’t available, you’ll see: ```plaintext The required version of the Playwright Chromium browser is not installed. Install it now? (Y/n) ``` Say **yes**. This is the browser that verification agents use to test your app. ### OpenCode Plugin [Section titled “OpenCode Plugin”](#opencode-plugin) The plugin reminds OpenCode to use Ranger at various points in the workflow. ```plaintext Where should the plugin be installed? > User (available in all your projects) Project (shared with team via git) ``` Choose **User** if you’re trying Ranger out individually. Choose **Project** to share the plugin config with your team via git. Under the hood, this adds the following block to your `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@ranger-testing/opencode-plugin"] } ``` For user scope, the config file is at `~/.config/opencode/opencode.json` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. For project scope, it’s at `.opencode/opencode.json` in your repo. ### Skills [Section titled “Skills”](#skills) Skills teach your AI coding agent how to use Ranger. Ranger installs skills automatically at the same scope you chose for the plugin. Skills are markdown files that tell your coding agent when and how to create feature reviews, run verifications, and address feedback. Project installs go to `.opencode/skills/`. User installs go to `~/.config/opencode/skills/` unless `XDG_CONFIG_HOME` or `OPENCODE_CONFIG_DIR` is set. ### Profile [Section titled “Profile”](#profile) Ranger needs to know how to access your running app and how to authenticate. We manage that information in [profiles](/concepts/profiles). After `ranger setup` finishes, create a profile for your app. Use a stable name (an email works well): ```bash ranger profile add alice@example.com --url http://localhost:3000 ``` Ranger checks the URL is reachable, then opens Chromium so you can log in to your app (if it requires authentication). **Close the browser when you’re done.** Ranger saves the session cookies so the verification agent can authenticate the same way. Profiles are shared with everyone in your organization by default, so name them by the account they represent. If your app doesn’t require login, pass `--skip-auth`. *** ## Use Ranger [Section titled “Use Ranger”](#use-ranger) Once setup is complete, open OpenCode in your project directory. ### Enable Ranger [Section titled “Enable Ranger”](#enable-ranger) At the start of your session, tell your agent to `enable ranger`. This activates Ranger’s hooks for the session. Ranger stays enabled on your branch across sessions, so you only need to enable once per branch. (On `main`/`master`, hooks enable for the current session only, since those branches are shared.) ### Build a Feature [Section titled “Build a Feature”](#build-a-feature) Ask your coding agent to build something that involves UI. For example: > “Add a dark mode toggle to the settings page.” With Ranger enabled, your coding agent will: 1. Create a feature review with scenarios describing what to verify (e.g., “User opens settings, clicks dark mode toggle, page switches to dark theme”) 2. Write the code (Ranger has nothing to do with this step and never reads or stores any of your code!) 3. Run browser verification via `ranger go`. A browser agent tests the feature review scenarios in your running app. 4. If verification finds issues, it fixes them and re-verifies automatically. 5. Once everything passes, it shares a link to the feature review page. ### Review the Feature Review [Section titled “Review the Feature Review”](#review-the-feature-review) Open the [feature review link](https://dashboard.ranger.net/features). You’ll see: * A list of the scenarios verified (which could be marked verified, blocked, or partially verified) * Screenshots and video from the browser verification for each scenario * A comments section where you can leave feedback, including on a specific point in the screenshot If you leave feedback in the screenshot, your coding agent will see and incorporate that feedback when you ask it to `resume ranger` in OpenCode.  # Supported Coding Agents > Ranger works with Claude Code, OpenCode, Cursor, Codex, and any agent with shell access. Here's how to set up each one. Ranger Feature Review works with any coding agent that can run bash commands. The table below shows what’s supported out of the box and links to the setup instructions for each agent. | Agent | Plugin | Skills | Setup Command | | ----------------------------- | --------------------------------------- | ---------------------------------- | ------------------------- | | [Claude Code](#claude-code) | Yes (`ranger@trailhead`) | `.claude/skills/` | `ranger setup` | | [OpenCode](#opencode) | Yes (`@ranger-testing/opencode-plugin`) | `.opencode/skills/` | `ranger setup --opencode` | | [Cursor](#cursor) | No | `.cursor/skills/` (via sym link) | `ranger setup` | | [Codex](#codex) | No | `.codex/skills/` (via sym link) | `ranger setup` | | [Other agents](#other-agents) | No | directory of choice (via sym link) | `ranger setup` | In the setup instructions below, we provide commands to sym link the skills into the appropriate directory. It will also work to copy or move them, but the `ranger update` command will automatically update the skills to match new CLI versions and sym linking allows those updates to be immediately picked up by your coding agent. *** ## Claude Code [Section titled “Claude Code”](#claude-code) Claude Code is Ranger’s primary integration. The `ranger setup` command installs a Claude Code plugin and skills automatically. **Quickstart:** Follow the full [Quickstart](/getting-started/quickstart/) guide. **What you get:** * **Plugin** — Connects Ranger to Claude’s hook system. Ranger can automatically activate at the right moments in your workflow. * **Skills** — Markdown files installed to `.claude/skills/` that teach Claude how to create feature reviews, run verifications, and address feedback. * **Slash commands** — `/ranger:enable`, `/ranger:disable`, and `/ranger:resume` for quick control. *** ## OpenCode [Section titled “OpenCode”](#opencode) OpenCode has its own plugin and skill paths. Use the `--opencode` flag during setup. **Quickstart:** Follow the [OpenCode Quickstart](/getting-started/quickstart-opencode/) guide. **What you get:** * **Plugin** — The `@ranger-testing/opencode-plugin` package, configured in your `opencode.json`. * **Skills** — Markdown files installed to `.opencode/skills/`. * **Natural language activation** — Tell your agent to “enable ranger” instead of slash commands. *** ## Cursor [Section titled “Cursor”](#cursor) Cursor 2.4+ reads `.claude/skills/` for compatibility, so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the `.cursor/skills` directory: ```sh ln -s ~/.claude/skills/ranger ~/.cursor/skills/ranger ``` The skills work without a plugin, but you may have to remind the agent to use it after compaction or later in the context window. Invoke the skill with `/ranger` or `@ranger` in Cursor’s Agent chat (e.g. “Use @ranger to create a feature review and verify it”). *** ## Codex [Section titled “Codex”](#codex) Codex reads `.claude/skills/` (and `.codex/skills/`), so Ranger default `setup` installation should be picked up automatically. On earlier versions, or for consistency with other skills, it can be linked into the Codex skills directory: ```sh ln -s ~/.claude/skills/ranger ~/.codex/skills/ranger ``` Codex’s default permissions mode blocks most network access, so Ranger will fail until permissions are adjusted. For an individual session, the slash command `/permissions` will allow you to update to Full Access. For a more enduring fix, you can add Ranger and network permissions by default: ```sh echo 'prefix_rule(pattern=["ranger"], decision="allow")' >> ~/.codex/rules/default.rules ``` and update `~/.codex/config.toml` with: ```plaintext sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true ``` *** ## Other Agents [Section titled “Other Agents”](#other-agents) Any coding agent that can execute bash commands can use Ranger. The core workflow is: 1. Install CLI and authenticate: `npm install -g @ranger-testing/ranger-cli && ranger setup` 2. Install skills: Say yes when prompted, or run `ranger skillup` separately. Skills are installed to `.claude/skills/ranger/` by default. 3. (optional) Link skills: if your agent looks for skills in a specific directory, sym link the ranger skill into that directory. 4. Use the CLI: Your agent runs `ranger create`, `ranger go`, `ranger show`, etc. The skill files are plain markdown — they work as instructions for any LLM-based agent. Want a dedicated integration? If you’re using an agent or harness that would benefit from an integration, [let us know](mailto:eng@ranger.net)! # Background Agent and CI Setup > Run Ranger in hosted environments — background agents running on isolated VMs, and CI pipelines. Beta   > **This feature is in beta.** We are actively developing background agent and CI support. If you’d like to get started using Ranger with a background agent, [reach out to us](mailto:eng@ranger.net) and we’ll help you set it up. This guide covers running Ranger in hosted environments, including background agents running on isolated VMs, and CI workflows (GitHub Actions, GitLab CI, etc.). The same steps apply regardless of the platform - anywhere you can run Node.js and a headless browser. Ranger works with any coding agent that can execute bash commands — Claude Code, OpenCode, Codex, or any other agent with shell access. ## How auth works without a human [Section titled “How auth works without a human”](#how-auth-works-without-a-human) CI and background agents don’t have anyone to click “log in” or tap a phone for a 2FA prompt. Ranger has three login mechanisms it uses in priority order — they’re the same ones described in [Profiles → How Ranger logs into your app](/concepts/profiles/#how-ranger-logs-into-your-app); the steps below are the operational bits for getting your hosted environment set up. | Your app’s situation | Strategy | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **No login** | [Skip auth](#path-skip-auth) — point Ranger at the URL and go. | | **Enterprise customer with automated login configured** (any auth shape, set up with our team) | [Automated login](#path-automated-login) — headless, deterministic. | | **Login flow an agent can do** (short-lived tokens, debug-auth endpoint, custom form) | [Login instructions](#path-login-instructions) — natural language; the agent follows them. | Each path has the same structure: a one-time profile setup, then secrets in your hosted environment, then your normal CI/agent steps. ## Path: Skip auth [Section titled “Path: Skip auth”](#path-skip-auth) For sites without authentication, no profile setup is needed beyond pointing at the URL. ```bash ranger profile add public-site --url https://docs.example.com --skip-auth ``` Commit nothing; the profile is reachable from any environment with `RANGER_CLI_TOKEN`. Skip ahead to [environment setup](#environment-setup-steps). ## Path: Automated login [Section titled “Path: Automated login”](#path-automated-login) Enterprise customers only. Ranger logs into your app for you on every CI run and background agent; your team sets credentials as env vars. For the full picture of what we cover and how it fits into a profile, see [Automated login](/concepts/profiles/#automated-login). The steps below are the operational bits for wiring it into your hosted environment. ### 1. Pick test credentials [Section titled “1. Pick test credentials”](#1-pick-test-credentials) Pick the account the hosted agent will log in as. The username doubles as the profile name, so pick something stable. ### 2. Make secrets available to the environment [Section titled “2. Make secrets available to the environment”](#2-make-secrets-available-to-the-environment) Your environment needs these secrets: | Secret | Description | | ---------------------- | ---------------------------------------------------------------------- | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth. | | `RANGER_TEST_USERNAME` | Test account username (typically the email used to log into your app). | | `RANGER_TEST_PASSWORD` | Test account password. | You’ll also need an API key for your coding agent (e.g. `ANTHROPIC_API_KEY` for Claude Code). How you provide these depends on your platform — GitHub repo secrets, GitLab CI variables, environment variables in a VM, etc. ### 3. (Optional) Smoke-test from your laptop [Section titled “3. (Optional) Smoke-test from your laptop”](#3-optional-smoke-test-from-your-laptop) Before letting CI rip, run a one-shot locally to confirm the credentials work: ```bash RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \ ranger go --base-url https://staging.example.com \ --notes "smoke: dashboard renders" ``` If that works locally, it’ll work in CI with the same secrets. Skip ahead to [environment setup](#environment-setup-steps). ## Path: Login instructions [Section titled “Path: Login instructions”](#path-login-instructions) Use this when automated login can’t model your app’s auth — short-lived tokens, debug auth endpoints, custom bootstraps. ### 1. Create a profile [Section titled “1. Create a profile”](#1-create-a-profile) ```bash ranger profile add preview --skip-auth --url https://staging.example.com ``` `--skip-auth` skips the browser auth step. The profile exists with no session attached; the agent will run your instructions on every verification. ### 2. Write the login instructions [Section titled “2. Write the login instructions”](#2-write-the-login-instructions) ```bash ranger profile config set preview loginInstructions \ 'Navigate to ${PREVIEW_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token.' ``` Plain language; `${VAR}` references resolve at runtime, so credentials don’t have to live in the instructions text. The agent runs these before every verification. ### 3. Dynamic base URLs [Section titled “3. Dynamic base URLs”](#3-dynamic-base-urls) If your deployment URL changes per environment (Vercel preview URLs, Heroku review apps), use `${VAR}` in `baseUrl` too: ```bash ranger profile config set preview baseUrl '${PREVIEW_URL}' ``` Same trick works for headers: ```bash ranger profile config set preview headers.Authorization '${AUTH_TOKEN}' ``` One caveat: profile config is shared org-wide, so two pipelines writing different values to the same profile key race — the second write redirects the first pipeline’s remaining `ranger go` calls, and the runs still “pass” against the wrong environment. When the value differs per run (a per-PR preview routing header, one preview pod per branch), pass it on the run instead: ```bash ranger go --header "x-preview-route: ${PREVIEW_SESSION}" --scenario 1 ``` `--header` applies to that invocation only and merges over the profile’s configured headers, so one shared profile stays safe under concurrent runs. ### 4. Make secrets available [Section titled “4. Make secrets available”](#4-make-secrets-available) | Secret | Description | | ------------------ | ------------------------------------------------------ | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth. | Plus any env vars your instructions reference (e.g. `TEST_USER_EMAIL`, `PREVIEW_URL`, `AUTH_TOKEN`), and your coding agent’s API key (e.g. `ANTHROPIC_API_KEY` for Claude Code). ## Environment Setup Steps [Section titled “Environment Setup Steps”](#environment-setup-steps) These are the steps your environment needs to run, in order. The commands below are plain bash — adapt them to your platform’s syntax. ### 1. Check out the repository [Section titled “1. Check out the repository”](#1-check-out-the-repository) Clone with full git history (needed if you want to generate diffs): ```bash git clone ``` ### 2. Install Node.js [Section titled “2. Install Node.js”](#2-install-nodejs) Ranger CLI requires Node.js 18+. ### 3. Install project dependencies [Section titled “3. Install project dependencies”](#3-install-project-dependencies) ```bash npm install ``` ### 4. Install a virtual display (Linux only) [Section titled “4. Install a virtual display (Linux only)”](#4-install-a-virtual-display-linux-only) Ranger runs a headless Chromium browser. On Linux environments without a display server, you need Xvfb: ```bash apt-get install -y xvfb Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 ``` Not needed on macOS or environments with a display server. ### 5. Install your coding agent and Ranger CLI [Section titled “5. Install your coding agent and Ranger CLI”](#5-install-your-coding-agent-and-ranger-cli) Install Ranger CLI globally, along with whatever coding agent you’re using: ```bash npm install -g @ranger-testing/ranger-cli # Plus your coding agent, e.g.: npm install -g @anthropic-ai/claude-code ``` ### 6. Install Chromium and authenticate [Section titled “6. Install Chromium and authenticate”](#6-install-chromium-and-authenticate) Pass your Ranger API token to the setup command. In non-interactive mode, this authenticates and installs the Playwright Chromium browser: ```bash export RANGER_CLI_TOKEN= ranger setup $RANGER_CLI_TOKEN ``` See [Authentication](/reference/cli-overview/#authenticating-the-ranger-cli-to-ranger) for all auth options. #### Separating install from auth (Docker / custom images) [Section titled “Separating install from auth (Docker / custom images)”](#separating-install-from-auth-docker--custom-images) If you’re building a container image, you can install Chromium and dependencies at **build time** (no token needed), then authenticate at **runtime**: ```dockerfile # -- Build time: bake deps into the image -- FROM node:20 RUN npm install -g @ranger-testing/ranger-cli @anthropic-ai/claude-code RUN ranger setup deps --with-deps ``` `ranger setup deps` installs Chromium without requiring authentication or a git repo. `--with-deps` tells Playwright to also install OS-level libraries (fonts, libx11, etc.) that headless Chromium needs on Debian/Ubuntu. At runtime, authenticate and set up skills: ```bash # -- Runtime: per-user or per-job auth -- export RANGER_CLI_TOKEN= ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` Each subcommand runs only its phase — `login` handles auth, `skills` installs the Claude Code plugin and skill files. You can also still use `ranger setup $RANGER_CLI_TOKEN` to run everything at once. ### 7. Run a verification [Section titled “7. Run a verification”](#7-run-a-verification) If you set up [automated login](#path-automated-login), set the credentials as env vars and call `ranger go` directly: ```bash RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \ ranger go --base-url $APP_URL --notes "" ``` If you set up [login instructions](#path-login-instructions), pin the profile and let the agent run them: ```bash ranger profile use preview ranger go --notes "" ``` If you’re [skipping auth](#path-skip-auth), just pin the profile and run: ```bash ranger profile use public-site ranger go --notes "" ``` ### 8. Install Ranger skills [Section titled “8. Install Ranger skills”](#8-install-ranger-skills) Install the Ranger skill files that teach your coding agent how to create feature reviews and run verifications: ```bash ranger skillup ``` This places skill markdown files in `.claude/skills/` (compatible with any agent that reads skill files from the project directory). ### 9. Configure your coding agent’s permissions [Section titled “9. Configure your coding agent’s permissions”](#9-configure-your-coding-agents-permissions) Your coding agent needs permission to run bash commands (for `ranger`, `gh`, `git`, etc.) and read files. How you configure this depends on your agent. **Claude Code example** — write `.claude/settings.local.json`: ```json { "permissions": { "allow": ["Bash(*)", "Read(*)", "Glob(*)", "Grep(*)"], "deny": [] } } ``` Other agents may need equivalent configuration, or may not require it at all. ### 10. Run your coding agent with Ranger [Section titled “10. Run your coding agent with Ranger”](#10-run-your-coding-agent-with-ranger) Invoke your coding agent in non-interactive mode with a prompt that tells it to use the Ranger skill. The skill files teach the agent how to create feature reviews, write scenarios, and run browser verification. Here are two possible use cases: #### CI workflow: Bug bash a PR’s changes [Section titled “CI workflow: Bug bash a PR’s changes”](#ci-workflow-bug-bash-a-prs-changes) Trigger on every pull request. The agent reads the diff, creates scenarios based on what changed, and verifies them in the browser. Results get posted as a PR comment. ```bash claude --print "Look at the git diff for this branch against main. \ Use the /ranger skill to create a feature review from the UI changes \ and verify each scenario. Post results as a PR comment using gh." ``` #### Background agent: Build and verify a feature [Section titled “Background agent: Build and verify a feature”](#background-agent-build-and-verify-a-feature) Give a coding agent a feature task and let it implement the code, then verify its own work in the browser before reporting back. ```bash claude --print "Read the task requirements and document a plan in docs/feature/{feature-name}.md. \ Implement the feature in the codebase, referencing the original task for context. \ Commit changes and push to the current branch. \ Use the Ranger skill to authenticate against the current environment and verify the feature works end-to-end in the browser." ``` ## Refreshing authentication [Section titled “Refreshing authentication”](#refreshing-authentication) Sessions refresh automatically: * **Automated login**: when a saved session expires, Ranger logs in again with the env-var credentials. No manual step. * **Login instructions**: the agent runs them on every verification, so there’s nothing to refresh. If the underlying flow changes (a new debug endpoint, a renamed env var), update the instruction text: ```bash ranger profile config set preview loginInstructions "" ``` * **Skip auth**: nothing to refresh. ## Limits [Section titled “Limits”](#limits) * **Automated login needs a one-time setup with us.** If your app isn’t set up yet, use [login instructions](#path-login-instructions) or do a one-time [headed login](/concepts/profiles/#headed-login) locally and reuse the saved session in CI. [Reach out](mailto:eng@ranger.net) and we’ll get you wired up. * **Some MFA factors require a human in the moment** — see [Multi-factor authentication](/concepts/profiles/#multi-factor-authentication) for which factors automated login can hold and which need a one-time headed login. * **One profile per account.** If you need different accounts, make different profiles. If you need the same account against different environments, override `baseUrl` per environment (see [Dynamic base URLs](#3-dynamic-base-urls)). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### “Automated login isn’t set up for this app yet” [Section titled ““Automated login isn’t set up for this app yet””](#automated-login-isnt-set-up-for-this-app-yet) The account you’re using doesn’t have automated login configured. [Reach out](mailto:eng@ranger.net) and we’ll set it up. In the meantime, use [login instructions](#path-login-instructions). ### Automated login fails with HTTP 422 (or falls back to a headed browser) [Section titled “Automated login fails with HTTP 422 (or falls back to a headed browser)”](#automated-login-fails-with-http-422-or-falls-back-to-a-headed-browser) Usually a bot challenge blocking the login page. If you have a header that bypasses it, set it on the profile — see [Bypassing bot protection during login](/concepts/profiles/#bypassing-bot-protection-during-login). If your bot protection can’t be bypassed with a header, fall back to [login instructions](#path-login-instructions) hitting a debug-auth endpoint. ### “Profile X not found” [Section titled ““Profile X not found””](#profile-x-not-found) Profile names are usually the username/email of the account. If you used automated login, the profile name is the value of `RANGER_TEST_USERNAME` — pass that as `--profile` if you need to disambiguate. Run `ranger profile ls` to see what’s available. ### Coding agent blocks commands [Section titled “Coding agent blocks commands”](#coding-agent-blocks-commands) Some agents sandbox tool calls by default. Make sure your agent has permission to run bash commands before invoking it. For Claude Code, this means writing `.claude/settings.local.json` (see step 9). ### Browser fails to launch [Section titled “Browser fails to launch”](#browser-fails-to-launch) On Linux, make sure Xvfb is running and `DISPLAY` is set before the agent starts. Chromium needs a display server even in headless mode on some configurations. ### Vercel preview environments return 401/403 [Section titled “Vercel preview environments return 401/403”](#vercel-preview-environments-return-401403) Vercel’s [Deployment Protection](https://vercel.com/docs/deployment-protection) blocks automated access to preview URLs by default. To bypass it, generate a protection bypass token in your Vercel project settings and add it as a custom header on the profile: ```bash ranger profile config set preview headers.x-vercel-protection-bypass '' ``` See [Vercel’s bypass automation docs](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) for how to generate the token. ## Example: GitHub Actions Workflow [Section titled “Example: GitHub Actions Workflow”](#example-github-actions-workflow) A complete workflow using Claude Code with [automated login](#path-automated-login). Copy to `.github/workflows/ranger-pr-verify.yaml`. **Required secrets** (Settings > Secrets and variables > Actions): * `RANGER_CLI_TOKEN` — Your Ranger API token * `RANGER_TEST_USERNAME` — Test account username for your app * `RANGER_TEST_PASSWORD` — Test account password * `ANTHROPIC_API_KEY` — Anthropic API key for Claude Code ```yaml name: Ranger PR Verification on: pull_request: types: [opened, synchronize, reopened] workflow_dispatch: inputs: pr_number: description: 'PR number to verify (optional, uses current branch if empty)' required: false type: string env: HUSKY: 0 jobs: verify: name: Ranger PR Verification runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm install - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y xvfb - name: Install Claude Code and Ranger CLI run: npm install -g @anthropic-ai/claude-code @ranger-testing/ranger-cli - name: Setup Ranger CLI env: RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} run: ranger setup ${{ secrets.RANGER_CLI_TOKEN }} - name: Configure Claude Code permissions run: | mkdir -p .claude cat > .claude/settings.local.json << 'EOF' { "permissions": { "allow": [ "Bash(*)", "Read(*)", "Glob(*)", "Grep(*)" ], "deny": [] } } EOF - name: Run Ranger verification env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} RANGER_TEST_USERNAME: ${{ secrets.RANGER_TEST_USERNAME }} RANGER_TEST_PASSWORD: ${{ secrets.RANGER_TEST_PASSWORD }} DISPLAY: ':99' GH_TOKEN: ${{ github.token }} run: | Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 sleep 2 claude --print "Look at the git diff for this branch against main. Use the /ranger skill to create a feature review from the changes and verify each scenario. Post results as a PR comment using gh." timeout-minutes: 30 ``` The agent’s `ranger go` calls pick up `RANGER_TEST_USERNAME` / `RANGER_TEST_PASSWORD` from the env automatically — no separate profile setup step is needed in the workflow. # CLI Overview > All Ranger CLI commands at a glance. The Ranger CLI (`@ranger-testing/ranger-cli`) is the primary tool for setting up, managing, and running Ranger in your project. Install it globally: ```bash npm install -g @ranger-testing/ranger-cli ``` This page covers all commands at a human-readable level. Your AI coding agent has its own detailed skill docs, so you don’t need to memorize flags. ## Setup [Section titled “Setup”](#setup) | Command | What it does | | --------------- | -------------------------------------------------------------------------------- | | `ranger setup` | Full interactive setup: auth, Chromium, plugin, profile, skills. Run this first. | | `ranger login` | Re-authenticate without running full setup again. | | `ranger status` | Show everything: version, org, plugin status, skills, profiles. | | `ranger update` | Update the CLI to the latest version and refresh installed skills. | | `ranger clean` | Remove all Ranger artifacts from the project (nuclear option). | ### `ranger setup` [Section titled “ranger setup”](#ranger-setup) The recommended way to get started. Run it in your project root (should be a git repo for feature review tracking) and it walks you through: 1. Browser-based authentication (or pass a token for CI: `ranger setup [token]`) 2. Chromium installation for browser verification 3. Claude Code plugin installation 4. Profile setup (your app’s URL + login) 5. Skill installation If you skip any step, you can run it individually later — each phase is also available as a subcommand. #### Subcommands [Section titled “Subcommands”](#subcommands) | Command | What it does | | ----------------------- | ------------------------------------------------------------------------------------------ | | `ranger setup` | Full interactive setup (default). | | `ranger setup all` | Explicit full setup — same as bare `ranger setup`. | | `ranger setup deps` | Install Chromium only. No auth, no git repo required. Use `--with-deps` for OS packages. | | `ranger setup login` | Authenticate only. Use `--token ` or `--mcp` for non-interactive auth. | | `ranger setup skills` | Install Claude Code plugin and skills only. Use `--scope user\|project`, `--opencode`. | | `ranger setup profiles` | Set up a local browser profile only. Use `--url`, `--force`, `--allow-insecure-localhost`. | #### Non-interactive mode [Section titled “Non-interactive mode”](#non-interactive-mode) Individual subcommands are the preferred way to script setup in containers and CI: ```bash # Docker build time — no auth needed ranger setup deps --with-deps # Runtime — auth and skills ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` The full `ranger setup` command also accepts flags for non-interactive use: | Flag | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `--url ` | Base URL for profile setup. A browser still opens for auth. | | `--force` | Skip URL reachability check. | | `--skip-chromium` | Skip Chromium installation. | | `--skip-auth` | Skip authentication — install deps only. Useful for container/CI image builds where auth happens at runtime. | | `--with-deps` | Install OS-level dependencies for Chromium (apt packages for Debian/Ubuntu). Pair with `--skip-auth` for container builds. | | `--allow-insecure-localhost` | Allow localhost content in deployed environments (micro frontends). | | `--mcp-bootstrap` | Bootstrap auth via an MCP auth server instead of browser login. Used by managed agent platforms and MCP-compatible tools. | ```bash ranger setup $TOKEN --url http://localhost:3000 ``` #### Headless / Scripted Setup [Section titled “Headless / Scripted Setup”](#headless--scripted-setup) For Docker containers and CI images, use subcommands to separate build-time deps from runtime auth: ```dockerfile # Dockerfile (build time) RUN npm install -g @ranger-testing/ranger-cli RUN ranger setup deps --with-deps ``` ```bash # Runtime startup script ranger setup login --token $RANGER_CLI_TOKEN # or: ranger setup login --mcp ranger setup skills --scope user ``` For a complete CI / background-agent walkthrough, see [Background Agent and CI Setup](/reference/background-agents-and-ci/). ### Authenticating the Ranger CLI to Ranger [Section titled “Authenticating the Ranger CLI to Ranger”](#authenticating-the-ranger-cli-to-ranger) **Interactive (laptops, developer machines)** `ranger setup` opens a browser for login. The CLI manages token refresh automatically. If your session expires, run `ranger login` to re-authenticate. **CI and scripted environments** Pass an API token from your [Ranger Dashboard](https://dashboard.ranger.net/cli): ```bash ranger setup ``` Or set the `RANGER_CLI_TOKEN` environment variable — the CLI reads it automatically. **MCP authentication** The CLI can authenticate via MCP, which may be useful in non-interactive environments where you would like the Ranger CLI to act on a real user’s behalf: ```bash ranger setup --mcp-bootstrap ``` Set `RANGER_MCP_AUTH_URL` to point at your platform’s MCP proxy if applicable. [Contact us](mailto:support@ranger.net) for setup guidance. ### Logging the agent into your app (profiles) [Section titled “Logging the agent into your app (profiles)”](#logging-the-agent-into-your-app-profiles) CLI auth (above) identifies *you* to the Ranger API. Separately, the verification agent needs to log in to *your app*. That’s what [profiles](/concepts/profiles) handle — see that page for setup details. ## Profiles [Section titled “Profiles”](#profiles) Profiles tell Ranger where your app runs and how the agent gets in. | Command | What it does | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ranger profile add ` | Add a profile. Opens a browser for you to log in (or use `--skip-auth` for apps without login). Supports `--url`, `--force`, `--skip-auth`, `--cdp-endpoint`, `--allow-insecure-localhost`, `--safe-mode`, `--setup-header`. | | `ranger profile update ` | Refresh authentication for an existing profile. Runs server-side login when configured; otherwise opens a browser. | | `ranger profile use ` | Switch which profile is active. | | `ranger profile ls` | List all profiles with their URLs and status. | | `ranger profile delete ` | Delete a cloud profile. Asks you to type the name to confirm; pass `--yes` to skip. | Profiles are shared with everyone in your organization by default — name them by the account they represent. Use `--cdp-endpoint` on `profile add` to connect to an Electron app or existing browser via Chrome DevTools Protocol instead of a URL. ## Profile Config [Section titled “Profile Config”](#profile-config) Fine-tune browser behavior per profile. | Command | What it does | | --------------------------------------------------- | ---------------------------------- | | `ranger profile config set ` | Set a config value. | | `ranger profile config get ` | Read a config value. | | `ranger profile config list ` | Show all config for a profile. | | `ranger profile config unset ` | Remove a config value. | | `ranger profile config reset ` | Clear all per-directory overrides. | Supported keys: `baseUrl`, `headless` (true/false), `allowInsecureLocalhost` (true/false), `safeMode` (true/false, disables browser features like Bluetooth that can cause crashes on some systems), `userAgent`, `storageState`, `cdpEndpoint`, `loginInstructions`, `headers.` (custom HTTP headers sent with every request), `setupHeaders.` (HTTP headers sent only during profile setup auth — see below). Profile config is shared org-wide. For a header that should apply to a single run only — a per-PR preview routing header, say — pass `--header "Name: Value"` to `ranger go` instead of writing it to the profile. ```bash ranger profile config set local headless true ranger profile config set local allowInsecureLocalhost true ranger profile config set ci header.Authorization '${AUTH_TOKEN}' ranger profile config set my-electron-app cdpEndpoint http://localhost:9222 ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' ``` Environment variables like `${AUTH_TOKEN}` are resolved at runtime. ### Setup-Only Headers [Section titled “Setup-Only Headers”](#setup-only-headers) Some apps require a custom HTTP header to bypass login protection (e.g. Cloudflare Turnstile) during initial setup, but that header causes problems if sent on every request during test runs (e.g. CORS failures with third-party services). Use `setupHeader.` to set headers that are only sent during the `ranger profile add` auth browser session: ```bash # Via config (applied on next profile add) ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...' # Or inline during profile creation ranger profile add local --url https://app.example.com --setup-header "x-bypass-turnstile: a1b2c3d4..." ``` These headers are persisted in the profile and reused when you re-add or overwrite the profile. They are **not** sent during `ranger go` verification runs. ### Custom Login Instructions [Section titled “Custom Login Instructions”](#custom-login-instructions) If your app uses short-lived cookies or tokens that expire before Ranger can use them, you can provide custom login instructions instead of relying on saved auth state. Set `loginInstructions` to tell the Ranger agent how to authenticate before each verification run: ```bash ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', ''). Refresh the page." ``` The agent will follow these instructions as a mandatory first step before every verification. This works with any auth mechanism — local debug endpoints, API keys, token injection, etc. Environment variables are supported: ```bash ranger profile config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token." ``` ## Feature Reviews [Section titled “Feature Reviews”](#feature-reviews) Feature reviews are the core unit of work in Ranger. Each feature review has a name, description, and scenarios to verify in the browser. | Command | What it does | | ------------------------------ | -------------------------------------------------------------------------------------- | | `ranger create ""` | Create a new feature review. Use `-c` for scenarios, `-d` for description. | | `ranger list` | List feature reviews. Use `--current-branch` to filter by your git branch. | | `ranger show` | Show the active feature review’s status and scenarios. | | `ranger resume ` | Set a feature review as active and start its session. | | `ranger add-scenario ""` | Add a scenario to the active feature review. | | `ranger get-review` | Show unaddressed reviewer comments across all scenarios. | | `ranger report [id]` | Generate PR description markdown with screenshots. Use `--json` for structured output. | | `ranger delete` | Soft delete the active feature review. | | `ranger restore ` | Restore a soft-deleted feature review. | ### Creating a Feature Review [Section titled “Creating a Feature Review”](#creating-a-feature-review) ```bash ranger create "Dark Mode Toggle" \ -d "Add dark mode support to settings page" \ -c "User opens settings, toggles dark mode, and the page switches themes" ``` Feature reviews auto-detect your git repo and branch. The feature review becomes active immediately. ### Resuming Work [Section titled “Resuming Work”](#resuming-work) At the start of a session, check for existing feature reviews: ```bash ranger list --current-branch ranger resume feat_abc123 ``` ### Generating Reports [Section titled “Generating Reports”](#generating-reports) `ranger report` generates a PR description from the active feature review’s verified scenarios, including screenshots. ```bash ranger report ranger report feat_abc123 ``` By default, output is markdown. Use `--json` for structured output that other tools can consume: ```bash ranger report --json ``` The JSON output contains the feature review dashboard URL and an array of scenarios: ```json { "url": "https://dashboard.ranger.net/features/feat_...", "scenarios": [ { "description": "string", "result": "verified | incomplete | blocked | in_progress | pending | approved | cancelled | superseded | closed", "rationale": "string | null", "steps": [ { "description": "string", "screenshot": "string (URL) | null", "is_key_step": true } ] } ] } ``` `result` reflects the scenario’s verification status. `rationale` is the agent’s response or the reason for a blocked/incomplete/cancelled status. Each step includes a screenshot URL when available; `is_key_step` marks the most important moments. Use `--exclude` to omit specific scenarios by number (1-based): ```bash ranger report --exclude 2 4 ``` ## Verification [Section titled “Verification”](#verification) `ranger go` spawns a browser agent to test your scenarios. ```bash ranger go ``` The CLI prompts you to select which scenario to verify. The browser agent navigates your app, interacts with the UI, takes screenshots, and returns a verdict (verified, partial, blocked, or failed). Common options: * `--scenario `: skip the selection prompt, verify scenario N directly (1-based) * `--notes ""`: override what the agent does (defaults to the scenario description) * `--start-path /settings`: start the agent on a specific page instead of the base URL * `--base-url `: override the profile’s base URL for this run (also reads `RANGER_BASE_URL`) * `--header "Name: Value"`: send an extra HTTP header with every request for this run only (repeatable). Merged over the profile’s configured `headers.` values — the flag wins per header — without touching shared profile config, so concurrent runs can each target their own preview environment * `--profile `: use a specific profile instead of the active one (also reads `RANGER_PROFILE`) * `--actor =`: bind a scenario role (for example, `buyer`) to an existing profile. Repeat twice to verify a two-actor flow. * `--env `: auth environment key; overrides the profile’s pinned env for this run; required to run an automated login against a bare-localhost target (`localhost` / `127.0.0.1`); also reads `RANGER_AUTH_ENV` * `--headed`: force a headed browser for this run only (does not change profile config) ### Multi-actor verification [Section titled “Multi-actor verification”](#multi-actor-verification) For interactions between two simultaneously logged-in users, pass `--actor =` once for each role: ```bash ranger go --scenario 1 \ --actor buyer=buyer@acme.com \ --actor seller=seller@acme.com ``` Both profiles must already exist, and the scenario should name its turns with the same labels: `As buyer, … As seller, … Back as buyer, …`. Ranger opens one isolated live session per actor and automatically selects the required Playwright transport. Version 1 supports two actors per run. See [Multi-actor scenarios](../../concepts/scenarios/#multi-actor-scenarios) for setup, scenario-writing guidance, and limits. ### One-shot verification with credentials inline [Section titled “One-shot verification with credentials inline”](#one-shot-verification-with-credentials-inline) If your team has [automated login](/concepts/profiles/#automated-login) set up with us, you can skip `profile add` entirely and pass credentials inline: ```bash RANGER_TEST_USERNAME=alice@example.com RANGER_TEST_PASSWORD=hunter2 \ ranger go --env --base-url http://localhost:3000 \ --notes "user logs in and sees the dashboard" ``` Ranger logs in for you and saves the session for next time. Automated login is set up per-app — works for any login flow we can run deterministically (username/password, SSO, OAuth, MFA, passkeys). [Reach out](mailto:eng@ranger.net) and we’ll scope your case. ## In Claude Code [Section titled “In Claude Code”](#in-claude-code) These aren’t CLI commands. They’re slash commands inside Claude Code: | Command | What it does | | ----------------- | -------------------------------------------------------------------- | | `/ranger:enable` | Enable Ranger hooks for this session and branch. | | `/ranger:disable` | Disable Ranger hooks. | | `/ranger` | Invoke the Ranger skill (create, verify, or manage feature reviews). | Ranger stays enabled on your branch across sessions (except on `main`/`master`, where it’s session-only). You only need to enable once per branch. # Hook System > How Ranger integrates with Claude Code through automatic hooks. Ranger integrates with Claude Code through hooks: automatic triggers that fire at key moments in the coding session. Hooks guide Claude through the Feature Review workflow without requiring you to remember commands or prompt for it repeatedly. The Claude Code plugin should be automatically installed when you run `ranger setup`. If you need to re-install them at any point, you can run: ```plaintext /plugin marketplace add ranger-testing/trailhead /plugin install ranger@trailhead ``` from inside Claude or: ```plaintext claude plugin marketplace add ranger-testing/trailhead claude plugin install ranger@trailhead ``` from the terminal. After installing, you may need to restart Claude Code before you can use the plugin. ## Why Hooks [Section titled “Why Hooks”](#why-hooks) We started with just the skills and discovered that Claude kept forgetting to use `ranger` and would return to us with errors that would have been caught with verification. We temporarily solved that with careful and repeated prompting, but wanted to automate it. Claude Code plugins offer “hooks” that can be used to remind Claude–if relevant–to use Ranger and check its work before returning to the user. We’ve found that enabling hooks whenever we’re working on UI-related work has dramatically improved Claude’s reliability with Feature Review. ## Default Behavior [Section titled “Default Behavior”](#default-behavior) Installing the plugin makes Ranger **available** — it does not interrupt you. On the first prompt of a session, Claude decides for itself whether the task involves frontend, UI, or browser work. If it does, Claude enables Ranger Feature Review and tells you in one line; if not, it stays out of the way. It never blocks waiting on a “do you want to enable Ranger?” question, so this is safe for interactive sessions, autonomous agents, and one-shot/CI runs alike. For deterministic setup, set `RANGER_HOOKS=on` so Ranger is active from session start. You can also toggle Ranger manually at any time: * `/ranger:enable` — enable for this session (and the branch, unless you’re on `main`/`master`) * `/ranger:disable` — disable for this session and branch On `main`/`master`, slash-command enablement only applies at the session level (not branch-persisted), since these branches are shared. ## Controlling Hooks Deterministically [Section titled “Controlling Hooks Deterministically”](#controlling-hooks-deterministically) For environments that shouldn’t rely on Claude’s per-task judgment, set the `RANGER_HOOKS` environment variable. This is the recommended setup path when you want predictable behavior across sessions: | `RANGER_HOOKS` | Behavior | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *(unset)* or `auto` | **Default.** Claude decides per task and enables Ranger itself for UI work; never asks a blocking question. | | `on` | Ranger is enabled from session start — no decision, no prompt. Good for teams/repos that always want Feature Review. | | `off` | Ranger never activates on its own — the auto-prompt is suppressed and nothing self-enables, so it can’t interrupt. A user in the loop can still turn it on for a session with `/ranger:enable`. Good for autonomous agents, Slack bots, and CI. | Set it where you launch the agent (shell env), or persist it in Claude Code’s `settings.json` `env` block so it applies per-user, per-project, or per-machine (whichever `settings.json` you put it in): ```json { "env": { "RANGER_HOOKS": "on" } } ``` A Slack bot or CI runner that should never be interrupted can set `RANGER_HOOKS=off` — it won’t auto-activate, but a user in the loop can still opt in with `/ranger:enable`. If it should sometimes use Ranger automatically, just leave the default; it no longer blocks either way. ## Hook Reference [Section titled “Hook Reference”](#hook-reference) | Hook | When It Fires | What It Does | | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **session-start** | Session created | Enables Ranger if the branch is already enabled, or unconditionally when `RANGER_HOOKS=on`. | | **auto-prompt** | First user prompt | (Default `auto` mode only) Asks Claude to judge whether the task is UI/browser work and enable Ranger itself if so — without ever asking you a blocking question. | | **session-end** | Session ended | If reason is `/clear` and session was enabled, auto-enables on next session. | | **enable** | `/ranger:enable` | Runs `ranger update`, enables session + branch, outputs the full skill content to Claude’s context. | | **disable** | `/ranger:disable` | Disables session + branch, tells Claude to stop using Ranger commands. | | **stop** | Session stopping | If the active feature review still has unfinished items, adds a non-blocking reminder to verify before replying, unless verification is already running. If items are terminal, it tries to conclude the session. Fails open on conclude errors. | | **post-edit** | After file write/edit | If Ranger is enabled but no feature review is registered, suggests using `/ranger`. If a feature review exists, hints about adding scenarios if scope expanded. | | **pre-compact** | Before context compaction | Reminds Claude to preserve the Ranger Feature Review Specification in the compacted summary. | | **plan-start** | Entering plan mode | Instructs Claude to include a Ranger Feature Review Specification in the plan. | | **exit-plan-mode** | Leaving plan mode | Reminds Claude to create the feature review with `ranger create` before starting implementation. | # Background Agent and CI Setup > Run Ranger in hosted environments — background agents running on isolated VMs, and CI pipelines. Beta   > **This feature is in beta.** We are actively developing background agent and CI support. If you’d like to get started using Ranger with a background agent, [reach out to us](mailto:eng@ranger.net) and we’ll help you set it up. This guide covers running Ranger in hosted environments, including background agents running on isolated VMs, and CI workflows (GitHub Actions, GitLab CI, etc.). The same steps apply regardless of the platform - anywhere you can run Node.js and a headless browser. Ranger works with any coding agent that can execute bash commands — Claude Code, OpenCode, Codex, or any other agent with shell access. ## How auth works without a human [Section titled “How auth works without a human”](#how-auth-works-without-a-human) CI and background agents don’t have anyone to click “log in” or tap a phone for a 2FA prompt. Ranger has three login mechanisms it uses in priority order — they’re the same ones described in [Profiles → How Ranger logs into your app](/concepts/profiles/#how-ranger-logs-into-your-app); the steps below are the operational bits for getting your hosted environment set up. | Your app’s situation | Strategy | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **No login** | [Skip auth](#path-skip-auth) — point Ranger at the URL and go. | | **Enterprise customer with automated login configured** (any auth shape, set up with our team) | [Automated login](#path-automated-login) — headless, deterministic. | | **Login flow an agent can do** (short-lived tokens, debug-auth endpoint, custom form) | [Login instructions](#path-login-instructions) — natural language; the agent follows them. | Each path has the same structure: a one-time profile setup, then secrets in your hosted environment, then your normal CI/agent steps. ## Path: Skip auth [Section titled “Path: Skip auth”](#path-skip-auth) For sites without authentication, no profile setup is needed beyond pointing at the URL. ```bash ranger profile add public-site --url https://docs.example.com --skip-auth ``` Commit nothing; the profile is reachable from any environment with `RANGER_CLI_TOKEN`. Skip ahead to [environment setup](#environment-setup-steps). ## Path: Automated login [Section titled “Path: Automated login”](#path-automated-login) Enterprise customers only. Ranger logs into your app for you on every CI run and background agent; your team sets credentials as env vars. For the full picture of what we cover and how it fits into a profile, see [Automated login](/concepts/profiles/#automated-login). The steps below are the operational bits for wiring it into your hosted environment. ### 1. Pick test credentials [Section titled “1. Pick test credentials”](#1-pick-test-credentials) Pick the account the hosted agent will log in as. The username doubles as the profile name, so pick something stable. ### 2. Make secrets available to the environment [Section titled “2. Make secrets available to the environment”](#2-make-secrets-available-to-the-environment) Your environment needs these secrets: | Secret | Description | | ---------------------- | ---------------------------------------------------------------------- | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth. | | `RANGER_TEST_USERNAME` | Test account username (typically the email used to log into your app). | | `RANGER_TEST_PASSWORD` | Test account password. | You’ll also need an API key for your coding agent (e.g. `ANTHROPIC_API_KEY` for Claude Code). How you provide these depends on your platform — GitHub repo secrets, GitLab CI variables, environment variables in a VM, etc. ### 3. (Optional) Smoke-test from your laptop [Section titled “3. (Optional) Smoke-test from your laptop”](#3-optional-smoke-test-from-your-laptop) Before letting CI rip, run a one-shot locally to confirm the credentials work: ```bash RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \ ranger go --base-url https://staging.example.com \ --notes "smoke: dashboard renders" ``` If that works locally, it’ll work in CI with the same secrets. Skip ahead to [environment setup](#environment-setup-steps). ## Path: Login instructions [Section titled “Path: Login instructions”](#path-login-instructions) Use this when automated login can’t model your app’s auth — short-lived tokens, debug auth endpoints, custom bootstraps. ### 1. Create a profile [Section titled “1. Create a profile”](#1-create-a-profile) ```bash ranger profile add preview --skip-auth --url https://staging.example.com ``` `--skip-auth` skips the browser auth step. The profile exists with no session attached; the agent will run your instructions on every verification. ### 2. Write the login instructions [Section titled “2. Write the login instructions”](#2-write-the-login-instructions) ```bash ranger profile config set preview loginInstructions \ 'Navigate to ${PREVIEW_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token.' ``` Plain language; `${VAR}` references resolve at runtime, so credentials don’t have to live in the instructions text. The agent runs these before every verification. ### 3. Dynamic base URLs [Section titled “3. Dynamic base URLs”](#3-dynamic-base-urls) If your deployment URL changes per environment (Vercel preview URLs, Heroku review apps), use `${VAR}` in `baseUrl` too: ```bash ranger profile config set preview baseUrl '${PREVIEW_URL}' ``` Same trick works for headers: ```bash ranger profile config set preview headers.Authorization '${AUTH_TOKEN}' ``` ### 4. Make secrets available [Section titled “4. Make secrets available”](#4-make-secrets-available) | Secret | Description | | ------------------ | ------------------------------------------------------ | | `RANGER_CLI_TOKEN` | Your Ranger API token (`rngr_...`). Used for CLI auth. | Plus any env vars your instructions reference (e.g. `TEST_USER_EMAIL`, `PREVIEW_URL`, `AUTH_TOKEN`), and your coding agent’s API key (e.g. `ANTHROPIC_API_KEY` for Claude Code). ## Environment Setup Steps [Section titled “Environment Setup Steps”](#environment-setup-steps) These are the steps your environment needs to run, in order. The commands below are plain bash — adapt them to your platform’s syntax. ### 1. Check out the repository [Section titled “1. Check out the repository”](#1-check-out-the-repository) Clone with full git history (needed if you want to generate diffs): ```bash git clone ``` ### 2. Install Node.js [Section titled “2. Install Node.js”](#2-install-nodejs) Ranger CLI requires Node.js 18+. ### 3. Install project dependencies [Section titled “3. Install project dependencies”](#3-install-project-dependencies) ```bash npm install ``` ### 4. Install a virtual display (Linux only) [Section titled “4. Install a virtual display (Linux only)”](#4-install-a-virtual-display-linux-only) Ranger runs a headless Chromium browser. On Linux environments without a display server, you need Xvfb: ```bash apt-get install -y xvfb Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 ``` Not needed on macOS or environments with a display server. ### 5. Install your coding agent and Ranger CLI [Section titled “5. Install your coding agent and Ranger CLI”](#5-install-your-coding-agent-and-ranger-cli) Install Ranger CLI globally, along with whatever coding agent you’re using: ```bash npm install -g @ranger-testing/ranger-cli # Plus your coding agent, e.g.: npm install -g @anthropic-ai/claude-code ``` ### 6. Install Chromium and authenticate [Section titled “6. Install Chromium and authenticate”](#6-install-chromium-and-authenticate) Pass your Ranger API token to the setup command. In non-interactive mode, this authenticates and installs the Playwright Chromium browser: ```bash export RANGER_CLI_TOKEN= ranger setup $RANGER_CLI_TOKEN ``` See [Authentication](/reference/cli-overview/#authenticating-the-ranger-cli-to-ranger) for all auth options. #### Separating install from auth (Docker / custom images) [Section titled “Separating install from auth (Docker / custom images)”](#separating-install-from-auth-docker--custom-images) If you’re building a container image, you can install Chromium and dependencies at **build time** (no token needed), then authenticate at **runtime**: ```dockerfile # -- Build time: bake deps into the image -- FROM node:20 RUN npm install -g @ranger-testing/ranger-cli @anthropic-ai/claude-code RUN ranger setup deps --with-deps ``` `ranger setup deps` installs Chromium without requiring authentication or a git repo. `--with-deps` tells Playwright to also install OS-level libraries (fonts, libx11, etc.) that headless Chromium needs on Debian/Ubuntu. At runtime, authenticate and set up skills: ```bash # -- Runtime: per-user or per-job auth -- export RANGER_CLI_TOKEN= ranger setup login --token $RANGER_CLI_TOKEN ranger setup skills --scope user ``` Each subcommand runs only its phase — `login` handles auth, `skills` installs the Claude Code plugin and skill files. You can also still use `ranger setup $RANGER_CLI_TOKEN` to run everything at once. ### 7. Run a verification [Section titled “7. Run a verification”](#7-run-a-verification) If you set up [automated login](#path-automated-login), set the credentials as env vars and call `ranger go` directly: ```bash RANGER_TEST_USERNAME=$TEST_USER RANGER_TEST_PASSWORD=$TEST_PASS \ ranger go --base-url $APP_URL --notes "" ``` If you set up [login instructions](#path-login-instructions), pin the profile and let the agent run them: ```bash ranger profile use preview ranger go --notes "" ``` If you’re [skipping auth](#path-skip-auth), just pin the profile and run: ```bash ranger profile use public-site ranger go --notes "" ``` ### 8. Install Ranger skills [Section titled “8. Install Ranger skills”](#8-install-ranger-skills) Install the Ranger skill files that teach your coding agent how to create feature reviews and run verifications: ```bash ranger skillup ``` This places skill markdown files in `.claude/skills/` (compatible with any agent that reads skill files from the project directory). ### 9. Configure your coding agent’s permissions [Section titled “9. Configure your coding agent’s permissions”](#9-configure-your-coding-agents-permissions) Your coding agent needs permission to run bash commands (for `ranger`, `gh`, `git`, etc.) and read files. How you configure this depends on your agent. **Claude Code example** — write `.claude/settings.local.json`: ```json { "permissions": { "allow": ["Bash(*)", "Read(*)", "Glob(*)", "Grep(*)"], "deny": [] } } ``` Other agents may need equivalent configuration, or may not require it at all. ### 10. Run your coding agent with Ranger [Section titled “10. Run your coding agent with Ranger”](#10-run-your-coding-agent-with-ranger) Invoke your coding agent in non-interactive mode with a prompt that tells it to use the Ranger skill. The skill files teach the agent how to create feature reviews, write scenarios, and run browser verification. Here are two possible use cases: #### CI workflow: Bug bash a PR’s changes [Section titled “CI workflow: Bug bash a PR’s changes”](#ci-workflow-bug-bash-a-prs-changes) Trigger on every pull request. The agent reads the diff, creates scenarios based on what changed, and verifies them in the browser. Results get posted as a PR comment. ```bash claude --print "Look at the git diff for this branch against main. \ Use the /ranger skill to create a feature review from the UI changes \ and verify each scenario. Post results as a PR comment using gh." ``` #### Background agent: Build and verify a feature [Section titled “Background agent: Build and verify a feature”](#background-agent-build-and-verify-a-feature) Give a coding agent a feature task and let it implement the code, then verify its own work in the browser before reporting back. ```bash claude --print "Read the task requirements and document a plan in docs/feature/{feature-name}.md. \ Implement the feature in the codebase, referencing the original task for context. \ Commit changes and push to the current branch. \ Use the Ranger skill to authenticate against the current environment and verify the feature works end-to-end in the browser." ``` ## Refreshing authentication [Section titled “Refreshing authentication”](#refreshing-authentication) Sessions refresh automatically: * **Automated login**: when a saved session expires, Ranger logs in again with the env-var credentials. No manual step. * **Login instructions**: the agent runs them on every verification, so there’s nothing to refresh. If the underlying flow changes (a new debug endpoint, a renamed env var), update the instruction text: ```bash ranger profile config set preview loginInstructions "" ``` * **Skip auth**: nothing to refresh. ## Limits [Section titled “Limits”](#limits) * **Automated login needs a one-time setup with us.** If your app isn’t set up yet, use [login instructions](#path-login-instructions) or do a one-time [headed login](/concepts/profiles/#headed-login) locally and reuse the saved session in CI. [Reach out](mailto:eng@ranger.net) and we’ll get you wired up. * **Some MFA factors require a human in the moment** — see [Multi-factor authentication](/concepts/profiles/#multi-factor-authentication) for which factors automated login can hold and which need a one-time headed login. * **One profile per account.** If you need different accounts, make different profiles. If you need the same account against different environments, override `baseUrl` per environment (see [Dynamic base URLs](#3-dynamic-base-urls)). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### “Automated login isn’t set up for this app yet” [Section titled ““Automated login isn’t set up for this app yet””](#automated-login-isnt-set-up-for-this-app-yet) The account you’re using doesn’t have automated login configured. [Reach out](mailto:eng@ranger.net) and we’ll set it up. In the meantime, use [login instructions](#path-login-instructions). ### Automated login fails with HTTP 422 (or falls back to a headed browser) [Section titled “Automated login fails with HTTP 422 (or falls back to a headed browser)”](#automated-login-fails-with-http-422-or-falls-back-to-a-headed-browser) Usually a bot challenge blocking the login page. If you have a header that bypasses it, set it on the profile — see [Bypassing bot protection during login](/concepts/profiles/#bypassing-bot-protection-during-login). If your bot protection can’t be bypassed with a header, fall back to [login instructions](#path-login-instructions) hitting a debug-auth endpoint. ### “Profile X not found” [Section titled ““Profile X not found””](#profile-x-not-found) Profile names are usually the username/email of the account. If you used automated login, the profile name is the value of `RANGER_TEST_USERNAME` — pass that as `--profile` if you need to disambiguate. Run `ranger profile ls` to see what’s available. ### Coding agent blocks commands [Section titled “Coding agent blocks commands”](#coding-agent-blocks-commands) Some agents sandbox tool calls by default. Make sure your agent has permission to run bash commands before invoking it. For Claude Code, this means writing `.claude/settings.local.json` (see step 9). ### Browser fails to launch [Section titled “Browser fails to launch”](#browser-fails-to-launch) On Linux, make sure Xvfb is running and `DISPLAY` is set before the agent starts. Chromium needs a display server even in headless mode on some configurations. ### Vercel preview environments return 401/403 [Section titled “Vercel preview environments return 401/403”](#vercel-preview-environments-return-401403) Vercel’s [Deployment Protection](https://vercel.com/docs/deployment-protection) blocks automated access to preview URLs by default. To bypass it, generate a protection bypass token in your Vercel project settings and add it as a custom header on the profile: ```bash ranger profile config set preview headers.x-vercel-protection-bypass '' ``` See [Vercel’s bypass automation docs](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) for how to generate the token. ## Example: GitHub Actions Workflow [Section titled “Example: GitHub Actions Workflow”](#example-github-actions-workflow) A complete workflow using Claude Code with [automated login](#path-automated-login). Copy to `.github/workflows/ranger-pr-verify.yaml`. **Required secrets** (Settings > Secrets and variables > Actions): * `RANGER_CLI_TOKEN` — Your Ranger API token * `RANGER_TEST_USERNAME` — Test account username for your app * `RANGER_TEST_PASSWORD` — Test account password * `ANTHROPIC_API_KEY` — Anthropic API key for Claude Code ```yaml name: Ranger PR Verification on: pull_request: types: [opened, synchronize, reopened] workflow_dispatch: inputs: pr_number: description: 'PR number to verify (optional, uses current branch if empty)' required: false type: string env: HUSKY: 0 jobs: verify: name: Ranger PR Verification runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm install - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y xvfb - name: Install Claude Code and Ranger CLI run: npm install -g @anthropic-ai/claude-code @ranger-testing/ranger-cli - name: Setup Ranger CLI env: RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} run: ranger setup ${{ secrets.RANGER_CLI_TOKEN }} - name: Configure Claude Code permissions run: | mkdir -p .claude cat > .claude/settings.local.json << 'EOF' { "permissions": { "allow": [ "Bash(*)", "Read(*)", "Glob(*)", "Grep(*)" ], "deny": [] } } EOF - name: Run Ranger verification env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} RANGER_CLI_TOKEN: ${{ secrets.RANGER_CLI_TOKEN }} RANGER_TEST_USERNAME: ${{ secrets.RANGER_TEST_USERNAME }} RANGER_TEST_PASSWORD: ${{ secrets.RANGER_TEST_PASSWORD }} DISPLAY: ':99' GH_TOKEN: ${{ github.token }} run: | Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 sleep 2 claude --print "Look at the git diff for this branch against main. Use the /ranger skill to create a feature review from the changes and verify each scenario. Post results as a PR comment using gh." timeout-minutes: 30 ``` The agent’s `ranger go` calls pick up `RANGER_TEST_USERNAME` / `RANGER_TEST_PASSWORD` from the env automatically — no separate profile setup step is needed in the workflow. # Hook System > How Ranger integrates with Claude Code through automatic hooks. Ranger integrates with Claude Code through hooks: automatic triggers that fire at key moments in the coding session. Hooks guide Claude through the Feature Review workflow without requiring you to remember commands or prompt for it repeatedly. The Claude Code plugin should be automatically installed when you run `ranger setup`. If you need to re-install them at any point, you can run: ```plaintext /plugin marketplace add ranger-testing/trailhead /plugin install ranger@trailhead ``` from inside Claude or: ```plaintext claude plugin marketplace add ranger-testing/trailhead claude plugin install ranger@trailhead ``` from the terminal. After installing, you may need to restart Claude Code before you can use the plugin. ## Why Hooks [Section titled “Why Hooks”](#why-hooks) We started with just the skills and discovered that Claude kept forgetting to use `ranger` and would return to us with errors that would have been caught with verification. We temporarily solved that with careful and repeated prompting, but wanted to automate it. Claude Code plugins offer “hooks” that can be used to remind Claude–if relevant–to use Ranger and check its work before returning to the user. We’ve found that enabling hooks whenever we’re working on UI-related work has dramatically improved Claude’s reliability with Feature Review. ## Default Behavior [Section titled “Default Behavior”](#default-behavior) Installing the plugin makes Ranger **available** — it does not interrupt you. On the first prompt of a session, Claude decides for itself whether the task involves frontend, UI, or browser work. If it does, Claude enables Ranger Feature Review and tells you in one line; if not, it stays out of the way. It never blocks waiting on a “do you want to enable Ranger?” question, so this is safe for interactive sessions, autonomous agents, and one-shot/CI runs alike. Once enabled on a branch, Ranger stays enabled across sessions. You can also toggle it yourself at any time: * `/ranger:enable` — enable for this session (and the branch, unless you’re on `main`/`master`) * `/ranger:disable` — disable for this session and branch On `main`/`master`, hooks only enable at the session level (not branch-persisted), since these branches are shared. ## Controlling Hooks Deterministically [Section titled “Controlling Hooks Deterministically”](#controlling-hooks-deterministically) For environments that shouldn’t rely on Claude’s per-task judgment, set the `RANGER_HOOKS` environment variable: | `RANGER_HOOKS` | Behavior | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *(unset)* or `auto` | **Default.** Claude decides per task and enables Ranger itself for UI work; never asks a blocking question. | | `on` | Ranger is enabled from session start — no decision, no prompt. Good for teams/repos that always want Feature Review. | | `off` | Ranger never activates on its own — the auto-prompt is suppressed and nothing self-enables, so it can’t interrupt. A user in the loop can still turn it on for a session with `/ranger:enable`. Good for autonomous agents, Slack bots, and CI. | Set it where you launch the agent (shell env), or persist it in Claude Code’s `settings.json` `env` block so it applies per-user, per-project, or per-machine (whichever `settings.json` you put it in): ```json { "env": { "RANGER_HOOKS": "off" } } ``` A Slack bot or CI runner that should never be interrupted can set `RANGER_HOOKS=off` — it won’t auto-activate, but a user in the loop can still opt in with `/ranger:enable`. If it should sometimes use Ranger automatically, just leave the default; it no longer blocks either way. ## Hook Reference [Section titled “Hook Reference”](#hook-reference) | Hook | When It Fires | What It Does | | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **session-start** | Session created | Enables Ranger if the branch is already enabled, or unconditionally when `RANGER_HOOKS=on`. | | **auto-prompt** | First user prompt | (Default `auto` mode only) Asks Claude to judge whether the task is UI/browser work and enable Ranger itself if so — without ever asking you a blocking question. | | **session-end** | Session ended | If reason is `/clear` and session was enabled, auto-enables on next session. | | **enable** | `/ranger:enable` | Runs `ranger update`, enables session + branch, outputs the full skill content to Claude’s context. | | **disable** | `/ranger:disable` | Disables session + branch, tells Claude to stop using Ranger commands. | | **stop** | Session stopping | If the active feature review still has unfinished items, adds a non-blocking reminder to verify before replying, unless verification is already running. If items are terminal, it tries to conclude the session. Fails open on conclude errors. | | **post-edit** | After file write/edit | If Ranger is enabled but no feature review is registered, suggests using `/ranger`. If a feature review exists, hints about adding scenarios if scope expanded. | | **pre-compact** | Before context compaction | Reminds Claude to preserve the Ranger Feature Review Specification in the compacted summary. | | **plan-start** | Entering plan mode | Instructs Claude to include a Ranger Feature Review Specification in the plan. | | **exit-plan-mode** | Leaving plan mode | Reminds Claude to create the feature review with `ranger create` before starting implementation. |