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

Already connected? Call get_reflow_context, resolve the intended collection and inspect existing tests. Skip the installation steps below. Load reflow through load_skill once if you have not read the current entry skill; then load only the task-specific guidance it names. Do not reload it when following a link back to this page.

Use get_product_docs with a relevant id or literal query and bounded start_line / max_lines. Follow next_line for more. Request the index only when discovering documents. These packaged product docs describe the connected release, separate from application knowledge. If the documentation tool or starter skill is absent, use this page’s references and check the installed CLI version before recommending an update; do not assume it is already 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
Choose the next test and measure useful coverage growth	Coverage-guided testing, cumulative gain
Run and inspect browser journeys	Playground, test accounts
Compare snapshots and repair failures	Snapshots and review, Repair and rerun
Demonstrate a feature works and audit screenshots	Load evidence-review with load_skill; Guiding the agent
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

Reflow currently supports macOS on Apple silicon (arm64). The public installer selects the stable release for that platform and refuses other hosts with an explanation. It includes Node and the seven 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 baseline is macOS 15 on Apple silicon; older systems are not validated. Intel Macs, Linux and Windows are not supported by current releases. 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 reuses the application’s existing plugin selection, or on first initialization selects all seven bundled plugins (Browser, PostgreSQL, LocalBash, DockerUbuntu, Mailbox, MCP and OpenAPI), and reports their runtime requirements. To change an existing selection, see one selection per application. 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 and app 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 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. When inputs changed, plan names which: provider pins, flow or step source, covered files, bindings, inputs, team configuration or baselines, grouped across steps (inputChanges and per-step changedInputs in --json). Changes it cannot attribute are listed as such. 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. If an apply’s admission was uncertain and it never started, reflow unlock --abandon-request <key> gives up that request (its queued runs stop, or it is fenced), so planning again and applying with a new key is safe. Unknown completion blocks its step, even after reflow target selects a new epoch, until you inspect the named run and taint the step. Taints survive reselecting the same group.

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.

Automatic warning and error diagnostics

The local CLI and MCP keep a bounded in-memory buffer of structured warning and error facts to help diagnose Reflow failures. Up to eight events (4 KiB) are sent with an existing authenticated request to the selected Reflow API. This does not create background requests or retry tool calls. The API validates the batch and writes accepted events to its operational logs.

Records can contain failure codes, durations and deadlines, HTTP/RPC status, CLI/plugin source revisions, and run or request identifiers. They do not contain error message text, authored scripts, snapshots, credentials, URLs, private paths, or environment dumps. This is not a copy of stdout/stderr or application logs.

The ring retains at most 32 events for 15 minutes; process exit loses unsent records. Acknowledgement removes the sent events. Delivery is best effort and may contain duplicates. Static MCP discovery does not send a request just to flush diagnostics. Set REFLOW_DIAGNOSTICS=0 in the CLI or MCP host environment before launch to disable automatic recording and upload. Detailed local debug logs and plan_timings remain available separately when investigating a failure.

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. Both CLI and MCP use the selected authenticated API; there is no separate synchronization endpoint. 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 API connection; Reflow refuses to attach MCP to a different checkout or endpoint (daemon_conflict, naming both sides and the field that differs). A service started outside any checkout is replaced by the first MCP server from a checkout once idle. reflow service status shows the service’s checkout and endpoint; reflow service stop retires it once idle (it refuses while work runs and kills nothing). See device service ownership. 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, Mailbox or MCP inspector page for the connection and command details.