Grepathy captures the agent decisions your repo forgot

La revisión de código se vuelve incómoda cuando un agente introduce decisiones de diseño que nadie aprobó explícitamente. Grepathy es una nueva CLI que intenta solucionarlo extrayendo esas decisiones de las transcripciones de sesiones de Claude Code y guardándolas como archivos Markdown en el repositorio.

La propuesta es simple: cuando un revisor pregunte por qué se hizo un cambio, la respuesta debería estar junto al código, no en un registro de chat en la máquina de un desarrollador. Eso importa porque Claude Code elimina las transcripciones después de 30 días por defecto.

What Grepathy does

Grepathy lee las transcripciones localmente, identifica las decisiones tomadas durante una sesión de agente y las escribe en un archivo específico de la rama en .ai/why/<branch>.md. Esos resúmenes están pensados para sobrevivir más allá de la sesión original y dar a revisores, compañeros de equipo y agentes futuros un registro del razonamiento detrás de un cambio.

Recomendado

El fundador de Hinge, Justin McLeod, prepara Overtone, emparejador con IA

El ejemplo del proyecto procede de un trabajo por contrato en el que un agente decidió precrear usuarios invitados en Clerk sin que eso se pidiera en el plan o en los prompts. El CTO luego preguntó por qué se había hecho. El desarrollador no lo sabía, porque la decisión la había tomado el agente.

Con Grepathy, esa decisión se habría capturado como una entrada visible en el repositorio, incluyendo:

• Estado: iniciado por el agente
• Afecta a: lib/clerk/*, db/schema/guests.ts
• razón inferida
• puntos de atención para el revisor
• notas explícitas de riesgo

También facilita buscar decisiones de agente no aprobadas con comandos como grep -rn "agent-initiated" .ai/why/.

Hooked into the workflow

Grepathy está diseñado para ejecutarse mediante hooks en lugar de como una herramienta separada que los desarrolladores tengan que recordar lanzar. El flujo pensado es:

• ejecutar Claude y trabajar con normalidad
• dejar que el agente haga commits a medida que avanza
• al hacer git push, Grepathy escribe el archivo why y lo muestra para revisión

Según el proyecto, nunca bloquea un push, nunca toca tu área de staging y nunca hace push por sí mismo. También soporta múltiples agentes y worktrees.

Hay dos maneras en que los agentes futuros obtienen este contexto. Una nota en CLAUDE.md los señala hacia los archivos why al inicio de la sesión, y un hook PreToolUse inyecta entradas relevantes justo antes de que un agente edite un archivo con historial coincidente.

Privacy and limits

El proyecto afirma que las transcripciones permanecen en la máquina local. La única salida compartida es el resumen en Markdown, y el resumidor se describe como que sigue reglas estrictas:

• nunca cita mensajes de usuario
• nunca describe confusión ni idas y venidas
• nunca incluye detalles comerciales ni financieros
• elimina secretos

La documentación también dice que hay dos comprobaciones deterministas detrás del prompt: un escáner de secretos/finanzas y una regla de que cada entrada debe apuntar a código real. Los usuarios revisan el archivo antes de hacer push, y si una entrada se edita o elimina, Grepathy respeta ese cambio para siempre.

Where it helps — and where it doesn’t

El autor dice que el equipo realizó una evaluación ciega y pre-registrada frente a una línea base y publicó los resultados en docs/REPORT.md, incluyendo casos donde la herramienta falló.

Los casos de uso más fuertes son estrechos pero concretos. Grepathy ayuda a preservar el razonamiento antes de que las transcripciones desaparezcan, y puede capturar decisiones que nunca aparecen en el código, como rechazar una CDN o anotar que un agente actuó por su cuenta. En esas pruebas, los agentes con el archivo why pudieron responder correctamente; los agentes sin él produjeron explicaciones plausibles pero erróneas.

El proyecto también es franco sobre lo que no resuelve. No impedirá que un agente refactorice y elimine código importante, y no hace a los agentes más inteligentes en general. Si la respuesta ya es obvia a partir del código, el autor dice que los agentes funcionan bien sin ello.

Commands and compatibility

Los comandos clave incluyen grepathy init, status, doctor, context <path> y sync. La herramienta también puede rellenar sesiones antiguas si las transcripciones todavía están disponibles.

Por ahora, escribir estos resúmenes requiere Claude Code, aunque cualquier herramienta puede leer los archivos Markdown una vez que existen. El autor dice que el siguiente paso es un adaptador para Codex.

Under the hood

Grepathy se publica bajo la licencia MIT y está construido con TypeScript puro sin dependencias de runtime. El proyecto dice que sus tests son herméticos, con el LLM simulado y git ejecutándose en repositorios temporales, por lo que npm test funciona en cualquier lugar con Node >= 20 y git.

Ese foco en un contexto durable a nivel de repositorio es la apuesta central: no se trata de hacer a los agentes mejores programando, sino de hacer visibles sus decisiones no solicitadas antes de que desaparezca la transcripción que las explica.