OpenCode Quickstart

Get Ranger Feature Review running with OpenCode. By the end, your agent will verify UI features in a real browser.

Prerequisites

• Node.js 18 or later
• OpenCode
• A web application running locally

Install & Setup

From your project root (it should be a git repo):

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:

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

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 setup --opencode [token]. You can get one from your Ranger Dashboard.

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:

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

The plugin reminds OpenCode to use Ranger at various points in the workflow.

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:

{
  "$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

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

Ranger needs to know how to access your locally running app and how to authenticate. We manage that information in profiles.

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

Once setup is complete, open OpenCode in your project directory.

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

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

Open the feature review link. 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.