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`	Turn a PRD, ticket, or design into `.cofactor.md` specs that compile into flows.
`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.

03Author tests as specs

Your agent writes a .cofactor.md spec in the repo and compiles it into a flow:

bash

cofactor spec validate flows/checkout.cofactor.md   # parse and lint offline
cofactor spec diff flows/checkout.cofactor.md       # preview what compile would change
cofactor spec compile flows/checkout.cofactor.md    # create the workflow

Because specs are plain files, they live alongside your code and review like code.

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 <runId>   # overview, steps, thoughts, logs, trace
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.

06Next 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.