\nWhat it does •\nQuickstart •\nCLI reference •\nAgent-native usage •\nMCP server •\nHow it compares •\nFAQ\n
\n\nCatch behavioral drift when a Claude Agent Skill or a Claude Code `MEMORY.md` file edits itself, before the edit ships.\n\n\n\n```bash\n# PyPI -- Python CLI + library (genuine port, not a Node wrapper)\npip install evolveguard-cli\n```\n\n```bash\n# npm -- JavaScript/TypeScript CLI + library\nnpm install -g evolveguard-cli\n```\n\n> [!NOTE]\n> Both packages are live and named consistently: `evolveguard-cli` on PyPI and\n> `evolveguard-cli` on npm (renamed 2026-07-19 from the old plain `evolveguard`,\n> which is now deprecated on both registries). `npm install -g evolveguard-cli` and\n> `pip install evolveguard-cli` both work today; the demo GIFs below were recorded\n> against the published packages, not a local build.\n\n## What it does\n\n```bash\nevolveguard record ./SKILL.md --fixtures ./fixtures.json\n# ... skill gets edited, by a human or an agent ...\nevolveguard check ./SKILL.md\n```\n\n```\nEvolveGuard v0.1.4 -- Regression Check\nskill: monorepo-scanner baseline: 2026-07-15 fixtures: 1\n\n[DRIFT] fixture: \"scan a monorepo\" new tool call: fs.write (baseline had none)\n -> new tool call: fs.write (baseline had none) -- this edit introduces a\n capability the baseline never used\n\n0 PASS, 1 DRIFT, 0 FAIL\nexit code 1 (DRIFT blocks merge by default; override with --allow-drift)\n```\n\nThat's real output from this repo's own `fixtures/labeled-non-breaking-edits/case-03-add-write-capability/`\ntest case, wired to `filesystem: read-only` becoming `read-write` in the skill's frontmatter.\nReproduce it yourself: `evolveguard record` the `before/SKILL.md` in that folder against its\n`fixtures.json`, then `evolveguard check` the `after/SKILL.md`.\n\n\n\n## Features\n\n**Static analysis, not a live agent run.** `record` parses a skill file's YAML\nfrontmatter (declared `tools`, `network`, `filesystem`, `scope`, and any bundled\n`hooks`), scans the skill's body text and hook scripts for evidence of network calls\nor filesystem writes, and combines both into a capability surface. `check` re-parses\nthe edited file with the same logic and diffs the result. Neither command runs\n`eval`, shells out to a subprocess, or executes a skill's hook scripts, in either the\nTypeScript or the Python distribution.\n\n**Two-level diffing catches drift a single fixture can miss.** Each fixture's\n`expectedToolCalls` filters the recorded capability surface down to what that fixture\ncares about, but `check` also diffs the skill's _whole_ capability surface separately.\nA new capability that no fixture's `expectedToolCalls` happens to cover still shows\nup as a `surfaceChanges` entry instead of passing silently. Confirmed against this\nrepo's own `case-04-scope-widened` fixture, where a `fs.write` scope widens from\n`./workspace/**` to `./**`.\n\n\n\n**0% false positives on a labeled corpus, reproducibly.** `npx vitest run\nsrc/evolveguard/benchmark.test.ts` runs the record/check/diff pipeline against\n`fixtures/labeled-non-breaking-edits/`: 2 cases hand-labeled non-breaking (a wording\ntweak, a typo fix) and 3 labeled breaking (a new write capability, a widened scope, a\nhook script gaining a network call). As of this commit, both non-breaking cases stay\nclean: 0 of 2 flagged as drift. The corpus is small and grows as more real skill edits\nget reported.\n\n**A path-traversal guard on hook scripts.** A skill's declared hook paths are resolved\nand validated against that skill's own directory before being read, including a\nsymlink-escape re-check that runs after the lexical containment check passes\n(`src/evolveguard/paths.ts` and `python/src/evolveguard/paths.py`).\n\n**Every subcommand supports `--json`.** `record`, `check`, and `report` all take a\n`--json` flag and return a stable `schemaVersion`-tagged structure, so a coding agent\ncan call any of them as a subprocess and parse the result directly.\n\n**Two independently maintained, format-compatible distributions.** The npm package\n(TypeScript, repo root) and the PyPI package (Python, `python/`) parse the same\nfrontmatter schema and produce byte-compatible baseline and report JSON. A baseline\nrecorded with one CLI can be checked with the other; see\n[docs/concepts.md](./docs/concepts.md#file-formats-and-cross-distribution-compatibility)\nfor the file-format details.\n\nevolveguard detects changes in what a skill is _declared or shown_ to be capable of.\nIt does not run a live LLM agent or replay a real conversation transcript, so it\ncannot tell you whether an agent would actually behave differently on a given prompt.\nThat is an intentional scope limit, and also why it needs nothing hosted and runs\nfully offline in a pre-commit hook or CI job.\n\n## Quickstart\n\n```bash\n# 1. Record a baseline against a skill and its labeled fixtures\nevolveguard record ./skills/my-skill/SKILL.md --fixtures ./fixtures/my-skill.json\n# writes ./skills/my-skill/.evolveguard-baseline.json\n\n# 2. Edit the skill (by hand, or let an agent edit it)\n\n# 3. Check for drift\nevolveguard check ./skills/my-skill/SKILL.md\n# writes ./evolveguard-report.json, exits 1 if drift was found\n```\n\nA fixtures file is a JSON array of labeled prompts and the tool-call shapes each one is\nexpected to touch:\n\n```json\n[\n {\n \"id\": \"scan-a-monorepo\",\n \"prompt\": \"scan a monorepo\",\n \"expectedToolCalls\": [{ \"tool\": \"fs.read\" }, { \"tool\": \"fs.write\" }]\n }\n]\n```\n\n`expectedToolCalls` is optional; omit it and the fixture is treated as exercising the\nskill's entire capability surface. `scopeMatches` (a glob) narrows a tool to a specific\nfilesystem scope, e.g. `{ \"tool\": \"fs.write\", \"scopeMatches\": \"./workspace/**\" }`.\n\n## CLI command reference\n\nGenerated from the actual `--help` output of the installed CLI (verified against both\nthe npm and PyPI builds; flags and defaults are identical across distributions).\n\nevolveguard --helpevolveguard record --helpevolveguard check --helpevolveguard report --help