evolveguard

evolveguard

Qué hace • Inicio rápido • Referencia de CLI • Uso nativo para agentes • Servidor MCP • Cómo se compara • Preguntas frecuentes

Detecta la deriva de comportamiento cuando una habilidad de agente de Claude o un archivo MEMORY.md de Claude Code se edita a sí mismo, antes de que la edición se publique.

# 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] Ambos paquetes están activos y tienen nombres coherentes: evolveguard-cli en PyPI y evolveguard-cli en npm (renombrado el 2026-07-19 desde el antiguo evolveguard, que ahora está obsoleto en ambos registros). npm install -g evolveguard-cli y pip install evolveguard-cli funcionan hoy; los GIF de demostración a continuación se grabaron contra los paquetes publicados, no una compilación local.

Qué hace

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)

Esa es la salida real del caso de prueba fixtures/labeled-non-breaking-edits/case-03-add-write-capability/ de este propio repositorio, conectado a filesystem: read-only convirtiéndose en read-write en el frontmatter de la habilidad. Reprodúcelo tú mismo: evolveguard record el before/SKILL.md en esa carpeta contra su fixtures.json, luego evolveguard check el after/SKILL.md.

Características

Análisis estático, no una ejecución de agente en vivo. record analiza el frontmatter YAML de un archivo de habilidad (declarado tools, network, filesystem, scope y cualquier hooks incluido), escanea el texto del cuerpo de la habilidad y los scripts de hook en busca de evidencia de llamadas de red o escrituras en el sistema de archivos, y combina ambos en una superficie de capacidades. check vuelve a analizar el archivo editado con la misma lógica y compara los resultados. Ninguno de los comandos ejecuta eval, invoca un subproceso o ejecuta los scripts de hook de una habilidad, ni en la distribución de TypeScript ni en la de Python.

La comparación de dos niveles detecta la deriva que un solo fixture podría pasar por alto. El expectedToolCalls de cada fixture filtra la superficie de capacidades registrada a lo que ese fixture le importa, pero check también compara la superficie de capacidades completa de la habilidad por separado. Una nueva capacidad que ningún expectedToolCalls de fixture cubra aún aparece como una entrada surfaceChanges en lugar de pasar silenciosamente. Confirmado contra el fixture case-04-scope-widened de este propio repositorio, donde un alcance fs.write se amplía de ./workspace/** a ./**.

0% de falsos positivos en un corpus etiquetado, de forma reproducible. npx vitest run src/evolveguard/benchmark.test.ts ejecuta el pipeline de registro/verificación/comparación contra fixtures/labeled-non-breaking-edits/: 2 casos etiquetados como no disruptivos (un ajuste de redacción, una corrección de error tipográfico) y 3 etiquetados como disruptivos (una nueva capacidad de escritura, un alcance ampliado, un script de hook que gana una llamada de red). A partir de este commit, ambos casos no disruptivos permanecen limpios: 0 de 2 marcados como deriva. El corpus es pequeño y crece a medida que se informan más ediciones reales de habilidades.

Una protección contra el recorrido de rutas en los scripts de hook. Las rutas de hook declaradas de una habilidad se resuelven y validan contra el propio directorio de esa habilidad antes de leerse, incluida una verificación adicional de escape de enlaces simbólicos que se ejecuta después de que la verificación léxica de contención pase (src/evolveguard/paths.ts y python/src/evolveguard/paths.py).

Cada subcomando admite --json. record, check y report aceptan una bandera --json y devuelven una estructura estable etiquetada con schemaVersion, de modo que un agente de codificación puede llamar a cualquiera de ellos como subproceso y analizar el resultado directamente.

Dos distribuciones mantenidas de forma independiente y compatibles en formato. El paquete npm (TypeScript, raíz del repositorio) y el paquete PyPI (Python, python/) analizan el mismo esquema de frontmatter y producen JSON de línea base y de informe byte-compatible. Una línea base registrada con una CLI se puede verificar con la otra; consulta docs/concepts.md para los detalles del formato de archivo.

evolveguard detecta cambios en lo que una habilidad está declarada o mostrada que puede hacer. No ejecuta un agente LLM en vivo ni reproduce una transcripción de conversación real, por lo que no puede decirte si un agente se comportaría realmente de manera diferente ante un prompt determinado. Ese es un límite de alcance intencional, y también la razón por la que no necesita nada alojado y se ejecuta completamente sin conexión en un hook de pre-commit o en un trabajo de CI.

Inicio rápido

# 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

Un archivo de fixtures es una matriz JSON de prompts etiquetados y las formas de llamadas de herramienta que se espera que cada uno toque:

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

expectedToolCalls es opcional; omítelo y el fixture se trata como si ejercitara la superficie de capacidades completa de la habilidad. scopeMatches (un glob) reduce una herramienta a un alcance específico del sistema de archivos, por ejemplo, { "tool": "fs.write", "scopeMatches": "./workspace/**" }.

Referencia de comandos de CLI

Generado a partir de la salida real de --help de la CLI instalada (verificado contra las compilaciones de npm y PyPI; las banderas y los valores predeterminados son idénticos en todas las distribuciones).

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

Options:
  --baseline <path>  path to the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --report <path>    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

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

Códigos de salida: 0 todos los fixtures PASAN y no hay deriva a nivel de superficie, 1 se encontró al menos una DERIVA (pasa --allow-drift para seguir saliendo con 0 mientras se sigue informando), 2 un error de uso o un archivo que no se pudo analizar.

[!WARNING] El evolveguard --version de la compilación npm actualmente imprime 0.1.0 aunque el paquete publicado está en una versión package.json más reciente; la compilación de PyPI lee su versión de los metadatos del paquete instalado y la informa correctamente. Usa las insignias anteriores, no --version, si necesitas el número de versión publicado exacto del paquete npm.

Uso nativo para agentes

Cada subcomando admite --json para una salida estructurada que un agente puede analizar directamente:

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] La distribución de Python incluye un servidor MCP real (consulta Servidor MCP a continuación). El subcomando evolveguard mcp de la distribución npm/TypeScript sigue siendo un stub de "próximamente"; hasta que se publique, llama a record/check/report --json directamente como un subproceso desde tu agente de codificación, o usa el servidor MCP de Python incluso si el resto de tu cadena de herramientas está en el paquete npm.

Servidor MCP

La distribución de Python (evolveguard-cli en PyPI) incluye un servidor del Protocolo de Contexto de Modelo (Model Context Protocol), de modo que un agente compatible con MCP (Claude Desktop, Claude Code, etc.) puede llamar a evolveguard directamente en lugar de invocar un subproceso y analizar texto. La distribución npm/TypeScript aún no incluye uno: su subcomando evolveguard mcp sigue siendo un stub.

pip install "evolveguard-cli[mcp]"

Agrégalo a la configuración de tu cliente MCP, por ejemplo, el claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "evolveguard": {
      "command": "evolveguard-mcp"
    }
  }
}

Expone una sola herramienta, run(args: list[str]), que invoca la CLI evolveguard instalada con los argv exactos que escribirías en una terminal y devuelve {returncode, stdout, stderr, json?} (o {error: ...} si el comando falla, se agota el tiempo o sale con un código distinto de cero), de modo que una herramienta cubre record, check y report sin una herramienta MCP específica por subcomando. Ejemplo de llamada desde un agente:

{ "tool": "run", "arguments": { "args": ["check", "./SKILL.md", "--json"] } }

que devuelve el mismo informe estructurado que evolveguard check ./SKILL.md --json imprimiría, más el returncode/stdout/stderr sin procesar.

API de biblioteca

evolveguard también exporta una API programática para el mismo pipeline, para equipos que quieran integrarlo en sus propias herramientas en lugar de invocar la CLI. Ambas distribuciones exponen las mismas funciones y el mismo formato de archivo compatible con JSON; una línea base registrada con una CLI se puede verificar con la otra (consulta docs/concepts.md).

TypeScript:

import {
  recordBaseline,
  replaySkill,
  diffAll,
  writeBaseline,
  readBaseline,
} from 'evolveguard';

const baseline = recordBaseline('./SKILL.md', './fixtures.json');
writeBaseline('./.evolveguard-baseline.json', baseline);

// ... skill gets edited ...

const saved = readBaseline('./.evolveguard-baseline.json');
const replay = replaySkill('./SKILL.md', saved);
const report = diffAll(saved, replay);

Consulta src/evolveguard/index.ts para la superficie exportada completa: parseSkillFile, deriveCapabilitySurface, loadSkill, buildFixtureSnapshots, loadFixtures, recordBaseline, replaySkill, diffFixture, diffAll, diffSurface, writeBaseline, readBaseline, writeReport, readReport, más las interfaces compartidas de types.ts.

Python (pip install evolveguard-cli):

from evolveguard import record_baseline, replay_skill, diff_all, write_baseline, read_baseline

baseline = record_baseline("./SKILL.md", "./fixtures.json")
write_baseline("./.evolveguard-baseline.json", baseline)

# ... skill gets edited ...

saved = read_baseline("./.evolveguard-baseline.json")
replay = replay_skill("./SKILL.md", saved)
report = diff_all(saved, replay)

Consulta python/README.md para el recorrido específico de Python y la misma superficie exportada bajo evolveguard/__init__.py.

Cómo se compara

Braintrust es una plataforma general de evaluación y observabilidad de LLM. Es una opción sólida si ya estás registrando trazas de un agente en vivo y quieres una puntuación de evaluación estadística entre ejecuciones, pero requiere integración de SDK y un paso de definición de evaluación por aplicación. evolveguard no necesita nada de eso: apúntalo a un archivo SKILL.md y a un JSON de fixtures, y funciona.

agent-eval (el otro repositorio del mismo autor) responde una pregunta diferente: si el comportamiento de un agente cambió entre dos versiones que tú defines, para cualquier agente, independiente del framework, ejecutando ambas versiones tú mismo y calculando un valor p sobre la diferencia. evolveguard se activa directamente por una diferencia de archivo en SKILL.md/MEMORY.md y responde si esta edición específica cambió la superficie de capacidades que registró una línea base. Analiza el artefacto de la habilidad en sí y nunca te pide que definas o ejecutes nada en vivo.

Qué es evolveguard y por qué existe

evolveguard es una herramienta de línea de comandos y una biblioteca de TypeScript que detecta la deriva de capacidades en archivos de habilidades de agente de Claude (SKILL.md) y archivos de memoria automática de Claude Code (MEMORY.md) después de que se editan, por un humano o por un agente. Funciona analizando el alcance declarado del frontmatter de una habilidad y cualquier evidencia estática de comportamiento de red o escritura en el sistema de archivos en su texto del cuerpo y scripts de hook incluidos, capturando eso como una línea base y volviendo a derivar la misma instantánea después de una edición para compararla. Existe porque el ecosistema de habilidades de agente de Claude Code permite que las habilidades y los archivos de memoria cambien el comportamiento de un agente sin que un humano revise necesariamente cada edición para detectar regresiones, y ninguna herramienta existente verifica esa forma específica de artefacto sin requerir integración de SDK o una ejecución de agente en vivo.

Estado

Esta es una versión v0.1: una adición pequeña y enfocada al ecosistema existente de Claude Agent Skills. Se distribuye completamente bajo licencia MIT sin nivel propietario, como dos paquetes independientes e igualmente de primera clase:

• PyPI (evolveguard-cli, Python), disponible en pypi.org/project/evolveguard-cli. Un puerto independiente genuino, no un envoltorio alrededor del binario de Node (ver python/README.md). pip install evolveguard-cli lo instala directamente. El paquete se publicó originalmente bajo el nombre evolveguard; ese proyecto anterior de PyPI está retirado y ya no recibe actualizaciones; instala evolveguard-cli en su lugar.
• npm (evolveguard-cli, TypeScript), disponible en npmjs.com/package/evolveguard-cli. npm install -g evolveguard-cli lo instala directamente. Renombrado el 2026-07-19 desde el antiguo evolveguard simple, que ahora está obsoleto, para coincidir con la convención de nombres del paquete de PyPI.

Preguntas frecuentes

¿Qué es evolveguard, exactamente? Una herramienta de línea de comandos y biblioteca que detecta desviación de capacidades en archivos de Claude Agent Skill (SKILL.md) y archivos de auto-memoria de Claude Code (MEMORY.md) después de que se editan. No es un marco de agentes auto-evolutivos y no construye, ejecuta ni aloja agentes por sí mismo. Es una puerta de CI de pruebas de regresión que reacciona a un diff de archivo en un artefacto de skill que ya cambió, por un humano o un agente. Consulta "Qué es evolveguard y por qué existe" arriba para la definición completa.

¿Evolveguard llama a un LLM? No. Tanto record como check son completamente estáticos y deterministas; consulta "Características" arriba para ver exactamente qué analiza y escanea cada comando.

¿Cuál es el diferenciador principal frente a una herramienta general de pruebas o evaluación? No necesita nada alojado ni nada que integrar: apúntalo a un archivo SKILL.md y a un JSON de fixtures, y record/check funcionan de inmediato, con cero integración de SDK y sin ejecución de agente en vivo. Ese es el equilibrio que documenta la tabla "Cómo se compara" arriba: un alcance más limitado que una plataforma general de evaluación, a cambio de cero configuración.

¿Cómo se compara evolveguard con Braintrust? Braintrust es una plataforma general de evaluación y observabilidad de LLM que necesita integración de SDK y un paso de definición de evaluación, y puntúa trazas reales de una ejecución de agente en vivo. evolveguard no necesita nada de eso; analiza el archivo de skill en sí y nunca llama a un LLM. Usa Braintrust si ya estás registrando trazas y quieres puntuación estadística de evaluación entre ejecuciones. Usa evolveguard si quieres una verificación de pre-commit o CI de que una edición de SKILL.md/MEMORY.md no amplió silenciosamente lo que el skill puede hacer. Consulta la tabla de comparación en "Cómo se compara" arriba para el desglose completo, incluida la comparación con agent-eval del mismo autor.

¿Funciona con archivos MEMORY.md, que no tienen frontmatter? Sí. Un archivo sin frontmatter se analiza con un alcance declarado vacío, por lo que su superficie de capacidades proviene completamente de evidencia estática encontrada en el texto del cuerpo.

¿En qué plataformas se ejecuta y cómo lo instalo? El paquete npm requiere Node.js >=20.12 (cualquier sistema operativo que Node soporte) y se instala con npm install -g evolveguard-cli. El paquete PyPI requiere Python >=3.9 y se instala con pip install evolveguard-cli. Ambas distribuciones son paquetes de biblioteca/CLI puros sin enlaces nativos, por lo que no hay paso de compilación específico del sistema operativo en ninguno de los dos lados.

¿Cuál es una limitación real que debes conocer antes de confiar en esto? Solo ve la capacidad declarada o mostrada, no el comportamiento en tiempo de ejecución. Un skill podría pasar check y aun así comportarse de manera diferente en un prompt dado de formas que no tocan su superficie de capacidades. El punto de referencia de falsos positivos (consulta "Características" arriba) también es actualmente un corpus pequeño etiquetado a mano de 5 pares de antes/después, no un conjunto de datos grande, así que trata la cifra del 0% como una medición inicial, no como una garantía estadística. La distribución de Python incluye un servidor MCP real (consulta "Servidor MCP" arriba); el subcomando mcp de npm/TypeScript sigue siendo un stub de "próximamente", y la salida de evolveguard --version de la compilación npm actualmente va por detrás de la versión publicada real del paquete (consulta "Referencia de comandos CLI" arriba).

¿Es esto un marco general de evolución de agentes? No. Consulta "Cómo se compara" arriba. evolveguard deliberadamente no construye ni aloja un marco de agentes auto-evolutivos; solo prueba ediciones de skills/memoria que ya ocurrieron.

¿Evolveguard es gratuito de usar, incluso comercialmente? Sí. Está bajo licencia MIT sin nivel propietario ni versión de pago; consulta LICENSE. Puedes usarlo, modificarlo y redistribuirlo, incluso en proyectos comerciales, bajo los términos estándar de MIT.

Contribuciones

Consulta CONTRIBUTING.md. Cada cambio llega con pruebas en ambas distribuciones; un cambio en el esquema de frontmatter, la derivación de la superficie de capacidades o la lógica de veredicto de diff debe realizarse tanto en src/evolveguard/ (TypeScript) como en python/src/evolveguard/ (Python), con cobertura equivalente añadida a ambos conjuntos de pruebas.

Seguridad

Consulta SECURITY.md. evolveguard lee archivos locales a los que lo apuntas y nunca ejecuta ninguno de ellos; no realiza llamadas de red ni ejecuta un agente en vivo.

Licencia

MIT. Consulta LICENSE.