@flowriki/agent

Runs your Flowriki UI tests on your own computer. The browser under test and your project files stay on this machine.

Requires

• Node.js 22.13 or newer. Flowriki uses node:sqlite, which older versions do not have. node --version tells you.
• npm (ships with Node).

Use

npx @flowriki/agent@latest connect     # approve this computer in your browser
npx @flowriki/agent@latest start       # run it — stays in the foreground

start keeps running until you stop it. Closing the terminal stops the agent; nothing is installed as a background service.

npx @flowriki/agent@latest status      # connected? what is prepared?
npx @flowriki/agent@latest doctor      # diagnose setup problems
npx @flowriki/agent@latest disconnect  # forget this computer's credential

Write tests with Claude

The agent is also an MCP server, so Claude Code or Claude Desktop can write Flowriki tests for you, on your own Claude plan. Claude drives a browser on this computer, each step is performed before it is kept, and what it writes is saved to a new branch for you to review and publish in the dashboard.

Connect this computer first (connect above), then add Flowriki to Claude:

claude mcp add flowriki -- npx -y @flowriki/agent@latest mcp

For Claude Desktop, add this to its MCP settings (claude_desktop_config.json):

{ "mcpServers": { "flowriki": { "command": "npx", "args": ["-y", "@flowriki/agent@latest", "mcp"] } } }

Then ask, for example: "Write a Flowriki test that signs up and verifies the email". Claude reads your project's features, sign-in profiles and helpers, and uses them. You do not run mcp yourself — Claude starts it. It works alongside start, in a browser window of its own.

What you do not need

No checkout of Flowriki, and nothing to build. connect and start are the whole installation.

For recording, running and debugging from the dashboard you do not need a checkout of the project under test either: the service reads the flow from your connected repository and sends it with the command, so this machine can be one that has never cloned anything.

Serving a local checkout

Optional, and for one case: working against files on this machine rather than what is committed.

npx @flowriki/agent@latest start --project /path/to/checkout

Repeat --project for several. They are remembered, so later runs need no arguments. Each folder identifies itself from the .flowriki/project.json committed when its repository was connected — you never pass a project id.

One dashboard action still needs one: verifying unsaved steps from the flow editor, which reads the flow from a checkout rather than being sent it. It says so plainly when there is none. Recording, running and debugging do not.

Where things are kept

Credentials and project mappings live outside the npm cache, so upgrading or clearing the cache does not lose them:

| | | |---|---| | Windows | %APPDATA%\Flowriki | | macOS | ~/Library/Application Support/Flowriki | | Linux | $XDG_STATE_HOME/flowriki or ~/.local/state/flowriki |

FLOWRIKI_HOME overrides it.

Which Flowriki this talks to

Production, unless you say otherwise. --service <url> (or FLOWRIKI_SERVICE_URL) points at another one — our own dev and staging environments, or a self-hosted install.

Credentials are kept per service, so a production credential is never sent to a development one, and connecting to a second does not disturb the first. doctor prints which environment answered.

This is not the site your tests run against. That is a project setting in the dashboard, and changing it never requires connecting this machine again.

For a terminal where Flowriki should not open the default browser, use npx @flowriki/agent connect --no-open and open the printed approval link yourself. Approval is still required.