@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 --versiontells 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.
It keeps itself up to date. @latest starts the newest Flowriki each time
Claude connects, and while Claude stays connected Flowriki checks for a newer
release every half hour and switches over to it between tasks — never while a
flow is being written. The next answer says it was updated; if the new release
brings new tools and Claude does not offer them yet, start a new Claude session
(in the terminal version of Claude Code, /mcp then Reconnect also works). The agent you run with start
says when it is behind: npm install -g @flowriki/agent@latest, then restart it.
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.