Driving Cofactor from your coding agent

Let Claude Code, Cursor, and other coding agents write, run, and diagnose Cofactor tests without leaving your editor.

Your coding agent already lives in your repository. Cofactor gives it a CLI, an MCP server, and a set of skills so it can do the whole testing loop from the editor: author a flow, run it, stream the results, and root-cause a failure.

01Install the MCP server

The MCP server gives your agent structured tools for Cofactor.

bash

cofactor install --target claude-code
# also: cursor, windsurf, opencode, claude-desktop

Run cofactor install with no target for an interactive picker, or start the server directly with cofactor mcp.

02Install skills for the task

Skills are task-specific playbooks your agent loads on demand.

bash

cofactor skill list
cofactor skill install test-cases
cofactor skill install debug-run

Skill	Use it to
`canary-basic`	Learn the CLI: commands, help, and common patterns.
`test-cases`	Plan meaningful journeys and checks from a PRD, ticket, or design.
`browser-testing`	Drive a browser to test a web app interactively.
`debug-run`	Root-cause a failed run from its materialized artifacts.
`issue-log-xref`	Cross-reference issues with server logs to find root causes.

03Explore, then author through the CLI

Ask the agent to read cofactor workflow guide, cofactor workflow guide assertions, and the cached-flow authoring guide. The guide includes a prompt you can paste as-is; the agent will ask for your spec, explore the application in a credentialed Cofactor browser session, and confirm reliable data before creating a flow.

Use cofactor workflow create to create the flow directly, cofactor workflow patch for flow properties, and workflow node commands for its steps. Keep the journey readable and assertions focused on specified user-visible behavior. DOM attributes and chosen scroll distances are verification mechanics, not new requirements.

bash

cofactor session --help
cofactor workflow guide
cofactor workflow guide assertions
cofactor workflow --help
cofactor docs get reference/cache-authoring
cofactor docs get reference/cache-optimization

04Run and stream results

bash

cofactor workflow run <workflowId> --stream

The agent watches events in real time and reacts to the outcome.

05Diagnose failures

bash

cofactor workflow debug overview <runId>
cofactor workflow debug materialize <runId>
cofactor triage get latest        # AI clustering across the latest suite

The debug-run skill wraps this into a guided root-cause flow. See Triaging a failure for how to read and route what you find.

06Prove cached replay

Follow the cache-only repair loop: run with --cache-only, inspect the first failure and every assertion verdict, repair that step's Playwright cache, and rerun. Require two fresh passes after the last change. A cache hit or successful cache write does not establish that every check passed.

07Next steps

Triaging a failure to turn a red run into a verdict.
Running your tests for the human-driven version of the same loop.
CLI command reference for every command and flag.