Glitch Toolkit

glitch

Una comprobación que ha dejado de rechazar cosas sigue pasando. Eso es el fallo que esto busca.

El 8 de septiembre de 2026, en el repositorio del que se extrajo este paquete, una prueba protegía el único capítulo de un libro de pago que se regala gratis — afirmando que la muestra se detiene en su corte y no filtra el resto. Estaba en verde. Estaba buscando en una página que no tenía ningún libro, pasajes que por tanto nunca podría encontrar, y pasaba. Nada estaba roto; la redacción funcionaba bien. La alarma había sido desconectada y seguía mostrando una luz verde.

Toda barrera de protección se degrada así eventualmente, y la degradación es silenciosa, porque una barrera que ha dejado de rechazar se ve exactamente igual que una que no tiene nada que rechazar.

glitch instala seis barreras de protección en tu repositorio y luego, cada vez que lo pidas, ejecuta cada una contra un caso que se supone que debe rechazar. Una que ya no rechaza nada falla aquí, ruidosamente, en lugar de pasar silenciosamente.

pip install glitch-toolkit

glitch install     # put the artifacts in this repository
glitch status      # what is installed, what is not
glitch check --all # verify every step

Sin dependencias, sin llamadas de red, sin telemetría. No escribe nada fuera del directorio al que lo apuntes.

Lo que realmente comprueba

Un paso no está completo porque un archivo esté presente. Cada comprobación hace tres cosas y reporta cuál de ellas falló:

1. encuentra el artefacto
2. lo ejecuta, y espera que funcione
3. lo ejecuta contra un caso deliberadamente roto, y espera que lo rechace

Sin la tercera, una comprobación pasa en el momento en que copias un archivo, ya sea que ese archivo tenga dientes o no, y estaría en verde para cada lector para siempre. tests/test_cli.py existe para demostrar que el verificador falla ese caso; su prueba SABOTAGE instala artefactos que se ejecutan, salen con 0 y no rechazan nada.

Lo que install no hará

No escribirá tu CLAUDE.md, FLEET.md, FLOOR.md o PLAN.md. Cuatro de los seis pasos se comprueban contra tu propio archivo, porque para esos cuatro el archivo es el trabajo: un archivo de reglas que se mantiene, una tabla de escritorio con un committer, un piso medido dos veces, un plan que alguien más aprobó. Un comando que los escribiera convertiría el camino en "ejecutaste un instalador". Las plantillas FLOOR.md y PLAN.md se envían deliberadamente imposibles de pasar por la misma razón.

No sobrescribirá. Un artefacto ya existente en tu repositorio se deja solo y se reporta como conservado; --force es cómo dices lo contrario.

No escribe nada fuera del directorio al que lo apuntes, no hace llamadas de red, y no tiene dependencias fuera de la biblioteca estándar.

Ejecutarlo sin instalarlo

cli.py es un archivo y sigue siendo un archivo. Cópialo en un repositorio y status y check funcionan sin nada en el PATH y sin paso de instalación — esa propiedad es deliberada y hay una prueba para las rutas de búsqueda que usa. Solo install necesita el resto del paquete, y lo dice claramente en lugar de fallar de manera extraña.

El servidor MCP (solo lectura)

uvx --from 'glitch-toolkit[mcp]' glitch-mcp --repo .

Instala el extra en un entorno aislado, no en un Python del sistema. El verificador no tiene dependencias y eso es una promesa. El extra [mcp] es lo contrario: mcp>=2.0 trae pydantic, starlette, cryptography, opentelemetry y una docena más, y pip actualizará felizmente lo que ya está ahí para satisfacerlos. Hecho contra un intérprete global el 8 de septiembre de 2026 reemplazó pydantic 1.10 con 2.13 y starlette 0.46 con 1.6, rompiendo una aplicación FastAPI no relacionada en la misma máquina. uvx construye un entorno desechable y no toca nada más, que es por lo que la entrada del registro lo lanza de esa manera.

Un virtualenv es igualmente válido:

python -m venv .venv && .venv/bin/pip install 'glitch-toolkit[mcp]'

Ofrece las comprobaciones a un agente como tres herramientas — glitch_status, glitch_check, glitch_ledger_tail — y añade cada pregunta y respuesta a .claude/toolkit/ledger/ledger.jsonl.

No bloquea nada. No puede pausar, bloquear, rechazar o interceptar ninguna acción. No tiene conexión a base de datos, ni credenciales, ni llamadas de red. Esa es toda la primera versión, a propósito: un servidor que se interpone entre un agente y una base de datos de producción es software serio, y el orden honesto es ejecutar solo lectura primero, leer el registro, y descubrir qué habría rechazado antes de darle el poder de rechazar. Una barrera construida antes de que ese registro exista es una suposición con permisos.

Las comprobaciones no escriben nada en tu repositorio. El servidor rompe eso en exactamente un lugar — añade al registro — y --no-ledger apaga incluso eso, a costa de la única cosa que vale la pena conservar.

En Claude Code, .mcp.json:

{
  "mcpServers": {
    "glitch": { "command": "glitch-mcp", "args": ["--repo", "."] }
  }
}

El registro

JSONL de solo añadir. Nada reescribe una línea que no acaba de escribir; un registro que es superado es reemplazado por uno nuevo y ambos permanecen; un campo que nadie midió es null en lugar de 0; una última línea a medio escribir se omite y se cuenta, nunca se repara, porque repararla significa reescribir el archivo.

Pruebas

python tests/run_all.py      # all three suites, 40 tests

La suite del servidor se omite limpiamente sin el extra [mcp] y el ejecutor lo reporta como OMITIDO en lugar de pasar, porque una línea verde que significa "no miramos" es exactamente el fallo que la práctica de comprobación de barreras existe para detectar.

De dónde vienen las comprobaciones

Cada comprobación aquí existe porque algo salió mal, y CORPUS.md es la lista — qué pasó, cuánto costó, y qué comprobación lo detecta ahora.

También nombra las que nada aquí detecta todavía, incluidas las dos que costaron a este paquete un número de versión cada una. Un corpus que registrara solo sus fallos resueltos estaría haciendo lo que este paquete trata.

Licencia

Apache License 2.0 — ver LICENSE y NOTICE. Elegida sobre MIT por la concesión de patentes.

Todo en este repositorio está bajo ella. Úsalo comercialmente, cámbialo, redistribúyelo.

Los enlaces anteriores son absolutos a propósito: este README es también la descripción del paquete en PyPI, donde un enlace relativo se resuelve contra pypi.org y devuelve un 404.

De dónde viene esto

Este repositorio es un espejo publicado. El paquete se desarrolla dentro de un monorepo privado junto al libro Building Your Store Or Your SaaS With Claude, cuyas prácticas instala y comprueba, y se empuja aquí como un subárbol. El libro, la tienda que lo vende y el resto de ese repositorio no son de código abierto y no están aquí. No se retiene nada de este repositorio que pertenezca al paquete.

Los problemas y solicitudes de extracción pertenecen aquí en lugar de allí, porque aquí está la parte que cualquiera puede leer.

Estado

Versión 0.1.1. Se instala, y las prácticas que comprueba son las seis que el libro defiende. 0.1.0 fue la primera versión; 0.1.1 cambia esta descripción y añade integración continua, y nada sobre lo que hace el código.

Lo que aún no es: no bloquea nada. glitch-mcp reporta y registra y no puede bloquear a un agente de hacer nada. Eso es deliberado y el razonamiento está en mcp_server.py — un servidor que se interpone entre un agente y una base de datos de producción debería ganarse su evidencia antes de ganarse el poder de rechazar.