Agents start here

Connect Reflow, inspect the application and choose a useful first check. Load only the documentation needed for the task.

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
Check paused or unavailable targets	Target readiness
Measure Go or Swift code coverage from flows and query gaps	Code coverage
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

When run from an interactive terminal, the installer offers to connect Reflow to Codex and Claude Code if their commands are on PATH. Each connection is optional and private to your user account. It uses the installed CLI’s absolute path and picks up your application directory when you open the agent there.

Repeat installs reuse the selected release and preserve profiles, application data and existing Reflow agent configurations. Existing connections are left unchanged, including custom deployments; check them in your agent before switching services. When output is captured or redirected, or CI or NONINTERACTIVE is set, agent setup is skipped. To skip it explicitly, use curl -fsSL https://reflow.io/install.sh | sh -s -- --no-agent-setup. Install your agent first, or rerun the installer once it is available.

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.

After signing in and selecting an application, init installs or reuses its Browser, PostgreSQL, LocalBash, DockerUbuntu and Mailbox selection 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

Create or select the application directly from your agent or CLI; hosted onboarding is not required. Call get_reflow_context and follow next_action. If there are no collections, call manage_collections with action: "create" and repository set to your application’s absolute Git checkout path. The local tool infers its name and GitHub origin. For an existing collection, use action: "list", then action: "select" with its collection_id.

reflow collections list --json
reflow collections create --repo . --json
# Or select an existing application:
reflow collections select <collection-id>

Creation accepts and returns the current Where new tests are saved default. New teams start with Keep tests in Reflow; no preference change is needed. The choice is also available in hosted onboarding. Owners/admins may change the default separately in Team settings. Agent tool descriptions and loaded skills follow the current preference; refresh context before writing. Hosted MCP can also create collections using an explicit name and optional repository ID; see application collections. Existing tests stay where they are; test storage explains transfers.

Initialize the chosen application’s shared plugin selection:

reflow init --collection <collection-id>

For Git test storage, run this from the application checkout and commit the generated .reflow/plugins.lock.json. For tests kept in Reflow, init keeps the device copy outside the checkout. Normal init preserves the selection; --upgrade explicitly changes it. A missing or stale local copy prevents execution.

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 application’s selected plugins. Generated flows contain aliases and bindings; reflow init maintains the application lock. 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 reflow upgrade to select the current stable CLI in the same installation. It verifies the published release and preserves your profile, target, allowed origins, private bindings and application plugin lock. Running work continues; the older device service retires only after it confirms it is idle. The supervised MCP connection switches releases between calls without replaying an in-flight mutation. Older MCP processes need one reconnect to adopt this behavior. An unsupported protocol reports update_required instead of running against the wrong schema. Hosts that cache tool definitions may still require a reconnect for new or changed tools. Updating the supervisor itself also requires one; see MCP reconnect limits.

For older CLIs without upgrade, run the published installer again in the same prefix, then reconnect MCP. If a legacy local service cannot retire itself, follow its explicit idle/identity diagnostic before stopping it; never kill a service solely because an old run has released: false.

reflow upgrade does not change the application’s plugin selection. After it selects a new release it prints “Run reflow init —upgrade to move this application’s plugin lock to the new providers.” Use reflow init --upgrade --collection <collection-id> deliberately for that change. Only providers whose pins changed invalidate their steps and dependents; inspect reflow plan for the precise reuse decisions. Neither command requires re-targeting. Selecting a target again starts a new epoch and invalidates all prior step results.

Trusted local code execution is never carried over by an upgrade. The device service that replaces the old one starts without it, as any on-demand start does. Re-arm it for each request with REFLOW_LOCAL_ALLOW_CODE_EXECUTION=1 (or --allow-code-execution) on both reflow plan and reflow apply, or restart the device service with REFLOW_LOCAL_ALLOW_CODE_EXECUTION=1 in its own environment.

To install a specific retained version, use curl -fsSL https://reflow.io/install.sh | sh -s -- --version VERSION with the exact published version. Original evidence is retained; reproducible caches and unused installed releases are cleaned up automatically.

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. Upgrade handoff waits for an idle service; see the upgrade guidance above for legacy processes.
• 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.