For agents

A coding agent asked to strengthen a test suite needs three things from a mutation tester: the lines no test checks, what to assert about each, and a signal it can act on without parsing prose. oxmutate's CLI is declared once on burgee, and every surface below is projected from that declaration.

The survivor listCopy Anchor Link

oxmutate survivors --json reads the last report and prints one record per survivor. Here it reads the report from Getting started:

{"ok":true,"data":{"survivors":[{"id":"1","file":"src/age.ts","line":1,"column":50,"mutator":"EqualityOperator","replacement":"age > 18","status":"Survived","coveredBy":1,"flaky":false,"fix":"1 test(s) run this code, and all still pass when it becomes `age > 18` (EqualityOperator). fix: assert the behaviour this line decides."}]},"meta":{"provenance":{"report":{"source":"flag","location":"--report"}}}}

coveredBy is how many tests run the line. A survivor with coveredBy: 0 is NoCoverage: no test reaches it, and the fix is a test, not an assertion. flaky: true marks a verdict whose covering tests behaved differently across two dry runs.

On paratext, an agent read 326 bytes per survivor from this list, and 4,094 from Stryker's report for the same survivor (A5 in m1-results.md).

The MCP serverCopy Anchor Link

npx oxmutate --mcp

serves run and survivors as MCP tools over stdio, each with an input schema built from the same options the CLI takes. An MCP client config:

{
  "mcpServers": {
    "oxmutate": { "command": "npx", "args": ["oxmutate", "--mcp"] }
  }
}

The rest of the contractCopy Anchor Link

• --json on any command prints one envelope on stdout: { "ok": true, "data": … }, or { "error": { "kind", "code", "message" } }.
• --schema prints every command, option, default and exit code as one JSON document.
• --explain <option> says where an option's value came from: a flag, an environment variable, a config file or the default.
• Exit codes: 0 ok; 1 it ran and a gate failed (a score under --break, or a change that weakened its tests); 2 a usage error, so rewrite the command; 3 the config or the suite did not load, so fix the project, not the command.
• Every error carries a fix: line the agent can act on as written.

Machine-readable docsCopy Anchor Link

This site serves /llms.txt, a map of every page, and /llms-full.txt, the whole corpus in one file. Every page has a Markdown twin at its URL plus .md.