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.1.4 -- 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).

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] <skillPath>   Record a golden-transcript baseline for a
                                 skill against a set of labeled fixtures
  check [options] <skillPath>    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

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>  path to a fixtures JSON file (array of {id, prompt,
                     expectedToolCalls?})
  --baseline <path>  path to write the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

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

Read the full README on GitHub →