Agents start here

Use this guide to connect Reflow, understand the application and choose the first useful check. Load documentation as needed rather than putting the whole manual in context.

Read Reflow documentation through MCP

Call get_product_docs with no arguments for the documentation index. Read this guide with id: "agents-start-here"; use query for literal search, and start_line / max_lines to read a focused excerpt. Follow next_line to continue a document. These are packaged product docs, separate from the user’s application knowledge.

Start with load_skill({"name":"reflow"}), then load the task-specific skills it recommends. Tool availability reflects the connected release: if the documentation tool or starter skill is absent, use this page and the linked references, then check whether the CLI needs updating. Do not assume an update has already been installed.

Documentation map

Task	Read
Connect a coding agent	MCP, client configurations
Learn and maintain application knowledge	Guiding the agent
Choose where tests are saved	Test storage
Define tests and dependencies	Flow format, RFL reference
Build an application-specific testing DSL	Writing plugins
Run and inspect browser journeys	Playground, test accounts
Compare snapshots and repair failures	Snapshots and review, Repair and rerun
Put evidence in PR review	GitHub Actions, MCP review tools
Other execution surfaces	Browser self-targets
HTTP integrations and access	API and tokens

Connection and first-run setup

Install Reflow, point it at your application and run a flow. You can inspect the results locally, then prepare changed screenshots, command output and application knowledge for your pull request.

1. Install the CLI

The public installer selects the stable release for macOS or Linux on arm64 or x64. It includes Node and the five Go plugins; installation and ordinary plugin initialization need no private source checkout, Go or separate Node installation.

curl -fsSL https://reflow.io/install.sh | sh
export PATH="$HOME/.local/share/reflow-sidecar/bin:$PATH"
reflow --version
reflow init

Add that bin directory to your shell’s PATH configuration to keep the command available in new terminals. The installer needs curl, tar and SHA-256 tools. The supported release baselines are macOS 15 and Ubuntu 24.04 with glibc 2.39; older systems are not validated. Windows and Linux musl distributions are not supported. For a custom installation, pass --prefix with a new directory; an existing prefix must be owned by you and have mode 0700. Use the default temporary directory or a short private TMPDIR.

init installs or reuses Browser, PostgreSQL, LocalBash, DockerUbuntu and Mailbox and reports their runtime requirements. Your flows supply the application, test data and any required database or existing Ubuntu container. Browser execution also needs the browser reported by init.

2. Sign in to Reflow

Sign-in is open. App access and test execution are limited to approved teams during the closed beta. Sign in to register interest if your team is not yet approved.

Connect to the hosted service:

reflow login
reflow connection

Complete consent in a browser on this device. The CLI saves your connection in its private profile. The hosted application is also available for team access. Hosted API, app and Zero endpoints are selected automatically; no connection environment variables are needed.

Your plugins run locally while results synchronize with Reflow. Shared writes and execution require a live API and Zero connection. Use --scope read for inspection only. Keep private login files and credentials on the device.

3. Select your application

In hosted onboarding, choose your application collection and confirm Where new tests are saved. New teams start with Keep tests in Reflow. Owners and admins can change the default in Team settings. Existing tests stay where they are; test storage explains how to move them.

Start your application using its usual development command. In its Git checkout, replace this example URL with your running app. Save a private Browser binding at ~/.reflow/my-app/bindings.json (create its parent directory first):

{
  "site": {
    "provider": "Browser",
    "configuration": {
      "targetUrl": "http://localhost:3000",
      "browser": "chromium"
    }
  }
}

If init reports that Chromium is missing, provide your installed browser’s absolute path as executablePath in that configuration. Then select the target:

cd /path/to/your/app
chmod 600 "$HOME/.reflow/my-app/bindings.json"
reflow target http://localhost:3000 --group my-app --collection <collection-id> \
  --bindings "$HOME/.reflow/my-app/bindings.json"

Select the target once per development session. Repeating target starts fresh execution state, so earlier completed work will not be reused. The command connects the local execution service as needed; you do not need to launch a separate sidecar manually. The CLI infers the Git root from the current directory, including when you run it from a subdirectory.

4. Connect your agent and teach it your app

Configure your MCP client to launch reflow mcp over stdio from your application checkout. Reflow infers its Git root and connects to your profile’s local service automatically. For hosts that launch outside the project, see the appendix.

If your client cannot find reflow on PATH, use the absolute path to ~/.local/share/reflow-sidecar/bin/reflow with your home directory expanded.

{
  "mcpServers": {
    "reflow": {
      "command": "reflow",
      "args": ["mcp"]
    }
  }
}

The agent page provides the same example. Client-specific copies include VS Code’s servers format and Codex’s TOML format. If you use a custom profile, select that same profile in the CLI and MCP host.

Start by teaching your agent the application:

Learn this app with Reflow. Load the application-onboarding and knowledge-corpus skills. Read the source and explore the running app. Map our terminology, business rules and important user journeys into the knowledge base. Show me what you learned and which areas you haven’t explored.

Then ask it to turn a journey into repeatable coverage:

Read get_reflow_context and create a smoke test for our checkout journey in the team’s configured storage. Load the flow-authoring and plugin-execution skills, and use the application’s knowledge base. Declare the setup dependencies, assert the business outcome and capture the screens I’ll want to review. Use the Browser connection named site. Plan it, run it and show me the results.

Replace “checkout” with a journey from your application. The agent inspects the installed plugins and includes their version pins in the generated flow. See the flow format for the resulting file.

5. Plan, apply and inspect

From the same checkout:

reflow plan smoke
reflow apply smoke
reflow status
reflow dashboard

plan explains which steps will run, reuse evidence, wait or block without executing the application steps. apply runs the selected work and reports its progress. Use reflow run smoke for the same execution in one command. The dashboard opens a private local view of the connected runs; keep the command running while using it.

With no selectors, plan and apply resolve the selected collection across both storage locations, up to 20 flows including dependencies. Select a subset by slug, test ID or registered path. Repository paths are relative to the selected Git checkout. To run independent flows concurrently, use reflow apply --parallelism 4. Only select parallelism when the flows can safely overlap; declared dependencies and device capacity limit concurrency.

6. Gather fresh evidence and prepare the review

After editing source or flows, repeat plan and apply. Completed work with matching inputs can reuse its evidence. To deliberately rerun a flow after an external change:

reflow taint smoke
reflow plan smoke
reflow apply smoke

taint takes a flow filename without .md, optionally followed by #step-name. The next plan includes affected dependents and any browser steps needed to reconstruct the session. Use reflow status to inspect interrupted work; reflow unlock only releases a verified stale owner.

Ask the agent to inspect the results, update the application’s current knowledge and prepare changed evidence for a human. A fresh agent can independently review it and add notes. PR preparation covers comparisons and export; the GitHub integration covers CI progress comments and private visual reports. You decide whether to merge.

Update the installation

Run the installer again to select the current stable release. To install a specific retained version, use curl -fsSL https://reflow.io/install.sh | sh -s -- --version VERSION with the exact published version. Updates are explicit; the installer preserves your profile and verifies downloaded content before switching releases.

Appendix: custom connections and working directories

• reflow login defaults to https://app.reflow.io for API and app, with run scope. Use --scope read for server-enforced inspection-only access.
• For another deployment, use reflow login --api https://api.example.com --app https://app.example.com and set REFLOW_SIDECAR_ZERO_URL to that deployment’s Zero URL in both CLI and MCP environments. Custom API profiles never implicitly use hosted Reflow Zero. reflow mcp --local retains the explicit local-development configuration.
• Profile mode is the default. Explicit REFLOW_SIDECAR_API_URL, REFLOW_SIDECAR_APP_URL or REFLOW_SIDECAR_TOKEN select environment mode; REFLOW_SIDECAR_CONNECTION_MODE=profile forces the saved profile instead.
• If your MCP host starts outside the application’s checkout (for example, a desktop client), set REFLOW_LOCAL_REPO=/absolute/path/to/your/app in its environment. Otherwise leave it unset. Outside Git, repository tools are unavailable; ordinary login and retained reads still work. An empty value explicitly disables repository discovery. CLI target, plan and apply also accept --repo when running outside the checkout.
• Use a separate --profile-dir consistently in CLI and MCP for concurrent checkouts. A running local service keeps its original checkout and Zero connection; Reflow refuses to attach MCP to a different checkout or endpoint. After updating an older CLI, stop its local service before reconnecting MCP.
• Installer options follow sh -s --, for example curl -fsSL https://reflow.io/install.sh | sh -s -- --prefix /absolute/private/path.

Plugin references

Read Plugin setup for bindings and exact version pins, then use the Browser, LocalBash, PostgreSQL, DockerUbuntu or Mailbox page for the connection and command details.