Evolveguard

evolveguard

What it does • Quickstart • CLI reference • Agent-native usage • MCP server • How it compares • FAQ

Catch behavioral drift when a Claude Agent Skill or a Claude Code MEMORY.md file edits itself, before the edit ships.

# PyPI -- Python CLI + library (genuine port, not a Node wrapper)

pip install evolveguard-cli

# npm -- JavaScript/TypeScript CLI + library

npm install -g evolveguard-cli

[!NOTE]

Both packages are live and named consistently: evolveguard-cli on PyPI and

evolveguard-cli on npm (renamed 2026-07-19 from the old plain evolveguard,

which is now deprecated on both registries). npm install -g evolveguard-cli and

pip install evolveguard-cli both work today; the demo GIFs below were recorded

against the published packages, not a local build.

What it does

evolveguard record ./SKILL.md --fixtures ./fixtures.json

... skill gets edited, by a human or an agent ...

evolveguard check ./SKILL.md

EvolveGuard v0.2.0 -- Regression Check skill: monorepo-scanner baseline: 2026-07-15 fixtures: 1

[DRIFT] fixture: "scan a monorepo" new tool call: fs.write (baseline had none) -> new tool call: fs.write (baseline had none) -- this edit introduces a capability the baseline never used

0 PASS, 1 DRIFT, 0 FAIL exit code 1 (DRIFT blocks merge by default; override with --allow-drift)

That's real output from this repo's own fixtures/labeled-non-breaking-edits/case-03-add-write-capability/ test case, wired to filesystem: read-only becoming read-write in the skill's frontmatter. Reproduce it yourself: evolveguard record the before/SKILL.md in that folder against its fixtures.json, then evolveguard check the after/SKILL.md.

Features

Static analysis, not a live agent run. record parses a skill file's YAML frontmatter (declared tools, network, filesystem, scope, and any bundled hooks), scans the skill's body text and hook scripts for evidence of network calls or filesystem writes, and combines both into a capability surface. check re-parses the edited file with the same logic and diffs the result. Neither command runs eval, shells out to a subprocess, or executes a skill's hook scripts, in either the TypeScript or the Python distribution.

Two-level diffing catches drift a single fixture can miss. Each fixture's expectedToolCalls filters the recorded capability surface down to what that fixture cares about, but check also diffs the skill's _whole_ capability surface separately. A new capability that no fixture's expectedToolCalls happens to cover still shows up as a surfaceChanges entry instead of passing silently. Confirmed against this repo's own case-04-scope-widened fixture, where a fs.write scope widens from ./workspace/** to ./**.

0% false positives on a labeled corpus, reproducibly. npx vitest run src/evolveguard/benchmark.test.ts runs the record/check/diff pipeline against fixtures/labeled-non-breaking-edits/: 2 cases hand-labeled non-breaking (a wording tweak, a typo fix) and 3 labeled breaking (a new write capability, a widened scope, a hook script gaining a network call). As of this commit, both non-breaking cases stay clean: 0 of 2 flagged as drift. The corpus is small and grows as more real skill edits get reported.

A path-traversal guard on hook scripts. A skill's declared hook paths are resolved and validated against that skill's own directory before being read, including a symlink-escape re-check that runs after the lexical containment check passes (src/evolveguard/paths.ts and python/src/evolveguard/paths.py).

Every subcommand supports `--json`. record, check, and report all take a --json flag and return a stable schemaVersion-tagged structure, so a coding agent can call any of them as a subprocess and parse the result directly.

Two independently maintained, format-compatible distributions. The npm package (TypeScript, repo root) and the PyPI package (Python, python/) parse the same frontmatter schema and produce byte-compatible baseline and report JSON. A baseline recorded with one CLI can be checked with the other; see docs/concepts.md for the file-format details.

evolveguard detects changes in what a skill is _declared or shown_ to be capable of. It does not run a live LLM agent or replay a real conversation transcript, so it cannot tell you whether an agent would actually behave differently on a given prompt. That is an intentional scope limit, and also why it needs nothing hosted and runs fully offline in a pre-commit hook or CI job.

Quickstart

# 1. Record a baseline against a skill and its labeled fixtures

evolveguard record ./skills/my-skill/SKILL.md --fixtures ./fixtures/my-skill.json

writes ./skills/my-skill/.evolveguard-baseline.json

2. Edit the skill (by hand, or let an agent edit it)

3. Check for drift

evolveguard check ./skills/my-skill/SKILL.md

writes ./evolveguard-report.json, exits 1 if drift was found

A fixtures file is a JSON array of labeled prompts and the tool-call shapes each one is expected to touch:

[

{ "id": "scan-a-monorepo", "prompt": "scan a monorepo", "expectedToolCalls": [{ "tool": "fs.read" }, { "tool": "fs.write" }] } ]

expectedToolCalls is optional; omit it and the fixture is treated as exercising the skill's entire capability surface. scopeMatches (a glob) narrows a tool to a specific filesystem scope, e.g. { "tool": "fs.write", "scopeMatches": "./workspace/**" }.

CLI command reference

Generated from the actual --help output of the installed CLI (verified against both the npm and PyPI builds; flags and defaults are identical across distributions).

evolveguard --help

Usage: evolveguard [options] [command]

Regression-testing CLI for self-edited Claude Agent Skills (SKILL.md, MEMORY.md) -- golden-transcript record/replay against a skill's own declared and inferred capability surface, zero hosted infrastructure.

Options: -V, --version output the version number -h, --help display help for command

Commands: record [options] Record a golden-transcript baseline for a skill against a set of labeled fixtures check [options] Replay the fixtures from a baseline against the current (possibly edited) skill and report drift report [options] [reportPath] Print a previously generated evolveguard-report.json mcp [coming soon] Expose record/check/report as MCP tools for a coding agent to call mid-session help [command] display help for command

evolveguard record --help

Usage: evolveguard record [options] <skillPath>

Record a golden-transcript baseline for a skill against a set of labeled fixtures

Arguments: skillPath path to the SKILL.md or MEMORY.md file to baseline

Options: --fixtures path to a fixtures JSON file (array of {id, prompt, expectedToolCalls?}) --baseline path to write the baseline file (default: /.evolveguard-baseline.json) --json output structured JSON instead of human-readable text (default: false) -h, --help display help for command

evolveguard check --help

Usage: evolveguard check [options] <skillPath>

Replay the fixtures from a baseline against the current (possibly edited) skill and report drift

Arguments: skillPath path to the SKILL.md or MEMORY.md file to check

Options: --baseline path to the baseline file (default: /.evolveguard-baseline.json) --report path to write the report file (default: "./evolveguard-report.json") --allow-drift exit 0 even if drift is detected (drift is still reported) (default: false) --json output structured JSON instead of human-readable text (default: false) -h, --help display help for command

evolveguard report --help

Usage: evolveguard report [options] [reportPath]

Print a previously generated evolveguard-report.json

Arguments: reportPath path to the report file (default: "./evolveguard-report.json")

Options: --json output structured JSON instead of human-readable text (default: false) -h, --help display help for command

Exit codes: 0 all fixtures PASS and no surface-level drift, 1 at least one DRIFT was found (pass --allow-drift to still exit 0 while still reporting it), 2 a usage error or a file that failed to parse.

[!WARNING]

The npm build's evolveguard --version currently prints 0.1.0 even though the

published package is at a newer package.json version; the PyPI build reads its version

from installed package metadata and reports it correctly. Use the badges above, not

--version, if you need the exact currently-published version number of the npm package.

Agent-native usage

Every subcommand supports --json for structured output an agent can parse directly:

evolveguard check ./SKILL.md --json

{

"schemaVersion": 1, "skillName": "monorepo-scanner", "results": [ { "id": "scan-a-monorepo", "verdict": "DRIFT", "changes": [/* ... */] } ], "surfaceChanges": [], "summary": { "pass": 0, "drift": 1, "total": 1 }, "exitCode": 1 }

[!NOTE]

The Python distribution ships a real MCP server (see MCP server below).

The npm/TypeScript distribution's evolveguard mcp subcommand is still a

"coming soon" stub; until it ships, call record/check/report --json directly as

a subprocess from your coding agent, or use the Python MCP server even if the rest of

your toolchain is on the npm package.

MCP Server

The Python di