Sphinx: la IA te toma examen antes del push.

Qué es

Sphinx es una herramienta de código abierto (licencia MIT) que se mete en git push. Antes de subir, mira lo que cambió y te hace una pregunta sobre ese cambio. Si la contestás bien, sube. Si la contestás mal, te explica el código y te hace otra pregunta.

Sirve para cuando programás con IA y aceptás cambios porque andan, sin saber bien qué hacen.

Con qué IA funciona

Funciona con Codex, Claude Code, Cursor, OpenCode y Pi, o solo con git. Las preguntas las corrige un modelo económico:

Por defecto (--cli-billing plan) usa el plan con el que ya iniciaste sesión en tu IA, no una API key. También acepta OpenRouter o un endpoint compatible con OpenAI.

La herramienta no se paga, pero cada corrección gasta tokens de tu plan: en la prueba, un cambio de 6 líneas usó unos 9 400.

Instalación

1. Instalá el paquete. Corré npm install -g sphinx-understand.
2. Activalo. Corré sphinx install y elegí tu IA en el asistente.
3. Listo para todos tus proyectos. sphinx install instala hooks de git globales (core.hooksPath), así que cubre los repos que ya tenés y los nuevos. Los hooks que ya tenías corren primero.

Cómo se usa

1. Hacé el push como siempre. Corré git push.
2. Abrí el cuestionario. Sphinx levanta un cuestionario local en el navegador e imprime su URL en la terminal («Sphinx questionnaire: http://127.0.0.1:…»).
3. Contestá la pregunta. Es sobre tu propio cambio, por ejemplo qué pasa en un caso raro. La pregunta cambia en cada corrida.
4. Seguí con el push. Si contestaste bien, te pregunta si seguís con el push. Si contestaste mal, te explica y te hace otra pregunta.

En el cuestionario tenés estas opciones:

Ejemplo de la prueba

Cambio de 6 líneas en precio.js que agrega los cupones HOLA10 y VERANO25. Sphinx lo marcó como «small change» e hizo 1 pregunta:

Con tu cambio, si llamás precioFinal(1000, "HOLA10 ") (con un espacio al final), ¿qué devuelve y se lanza algún error? Decime qué pasa y por qué.

Respuesta correcta: devuelve 1000 y no da error, porque «HOLA10 » con el espacio no está en la lista de cupones.

Preguntas en español

Por defecto las preguntas salen en inglés. Para que salgan en español, agregá una línea en ~/.config/sphinx/context.md, por ejemplo:

Hacé todas las preguntas y explicaciones en español rioplatense (voseo).

La interfaz del cuestionario sigue en inglés.

Privacidad

• Tus respuestas no le llegan al agente que escribe el código: solo ve si pasaste.
• No abre los .env ni las claves.

Si algo falla

• Si no instala, revisá que tengas Node 22.19 o más nuevo y que estés en macOS, Linux o WSL.
• Si no se abre el navegador, copiá la URL que imprime la terminal («Sphinx questionnaire: http://127.0.0.1:…») y abrila a mano.
• Si las preguntas salen en inglés, agregá la línea en ~/.config/sphinx/context.md.
• Si querés sacarlo, corré sphinx uninstall: quita los hooks y restaura los que tenías antes.