¿Qué hace introspect?
Convierte lo que sucedió en tus hilos de codificación con IA en cambios en cómo trabajan tus agentes para ti — para que tu configuración se acumule en lugar de reiniciarse cada sesión.
Es agnóstico al agente. Lee tus hilos de Claude Code, OpenAI Codex y Cursor,
encuentra las pocas cosas que vale la pena cambiar y, con tu aprobación, las escribe en
la configuración del agente que realmente dirige las sesiones futuras. Claude Code ya incluye /insights,
que lee tus últimos 30 días y te muestra un informe. Esa es la parte de lectura, solo para Claude.
Introspect es la parte de escritura en todos los agentes que uses. Youssef lo expresó bien en el hilo
del que surgió esto: arregla el sistema una vez para no tener que arreglar la salida mil veces.
La única idea que hace que esto funcione: patrones, no tácticas
El modo de fallo de "¿qué podría haber hecho mejor?" es que saca a relucir tácticas — una mejor bandera para un comando, un enfoque más inteligente para un error. Esas no se acumulan. Desaparecen mañana.
Lo que se acumula es un hábito que sigues repitiendo: la misma corrección que das en tres hilos diferentes, la misma preferencia que repites cada semana, el mismo giro equivocado que da el agente cada vez que toca tu configuración de pruebas. Por lo tanto, toda la habilidad está sesgada hacia la recurrencia:
Un cambio candidato merece su lugar solo cuando aparece más de una vez, aún no está escrito en algún lugar y plausiblemente habría cambiado el resultado. Todo lo demás es ruido — regístralo, no actúes sobre ello.
Esta también es la respuesta honesta a los dos temores que la gente planteó en ese hilo:
- "Me preocupa acumular malas decisiones / que mi flujo de trabajo se vuelva estúpido." → Nada se escribe sin que veas el diff exacto y lo apruebes. Cada cambio aplicado se registra y es reversible. En caso de duda, propón menos cosas.
- "¿Simplemente actualiza la habilidad todos los días para siempre? ¿Alguna vez converge?" → Debería converger. Si ya existe una regla, la refuerzas o fusionas; no agregas una segunda. Un día tranquilo produce un conjunto de cambios vacío, y eso es un éxito, no un fracaso.
El pipeline
Recolectar → Extraer → Comparar vs. configuración existente → Proponer conjunto de cambios → Aprobar → Aplicar + Registrar
(script) (tú) (tú, lees la configuración actual) (tú, con evidencia) (usuario) (tú, reversiblemente)
1. Recolectar — ejecuta el script, no vuelvas a analizar nada a mano
scripts/collect_threads.py lee el almacén de hilos de cada agente (JSONL de Claude, archivos
de rollout de Codex, SQLite de Cursor), filtra por ventana de tiempo, oculta secretos y emite UN
resumen común: por sesión, etiqueta qué agente fue, las indicaciones escritas por el humano, las
herramientas utilizadas, dónde fallaron las herramientas y señales ligeras de "fricción"
(indicaciones que parecen correcciones, herramientas llamadas muchas veces seguidas).
python3 scripts/collect_threads.py --days 1 # hoy, cada agente instalado (auto)
python3 scripts/collect_threads.py --agent all --days 7 # última semana, fuerza los tres
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject # un proyecto
python3 scripts/collect_threads.py --selftest # verificación de cordura de los tres analizadores
--agent por defecto es auto (detecta qué agentes están instalados). Usa --format md
cuando lo leas tú mismo; --format json para posprocesamiento. El script nunca decide nada — te da
material limpio y normalizado para que emplees tu criterio en lo que importa, no en analizar
tres formatos de transcripción diferentes.
2. Extraer — lee el resumen y extrae tres tipos de cosas
Lee el resumen como si fueras el jefe de gabinete del usuario revisando el día en todas sus herramientas. Las preferencias del usuario son lo primero — esta habilidad trata principalmente de aprender cómo ellos gustan trabajar, no de vigilar el comportamiento base de un agente. Separa:
- Preferencias duraderas (el evento principal) — el usuario corrigiendo un valor predeterminado o repitiendo cómo le gustan las cosas ("no, usa pnpm", "deja de añadir comentarios", "siempre crea una rama a partir de development primero", "no toques el árbol de trabajo"). Una preferencia que aparece en TUS hilos de Claude y Codex es una señal especialmente fuerte — se trata de ti, no de la herramienta.
- Brechas de configuración que hicieron que el agente repitiera trabajo — donde el agente redescubrió o se atascó en múltiples sesiones porque algo no estaba escrito: volver a aprender un comando de compilación, reencontrar un archivo que siempre está en el mismo lugar, faltaba un fragmento de contexto del proyecto. La solución es escribir lo que falta en la configuración del usuario — NO añadir una regla que regañe al agente. Si una repetición es simplemente un comportamiento genérico del agente sin una solución específica del usuario (por ejemplo, "leer un archivo antes de editarlo"), eso no es una regla, es ruido; déjalo fuera.
- Flujos de trabajo reutilizables — algo de varios pasos que el usuario realizó más de una vez y que merece ser una habilidad o un comando para que sea un solo paso la próxima vez.
Para cada candidato, anota la evidencia: qué agente, qué sesiones, cuántas veces, una cita corta. Sin evidencia de recurrencia → es una táctica, no un patrón → descártalo.
3. Comparar contra la configuración existente — el paso anti-inflado / convergencia
Antes de proponer nada, lee lo que ya está ahí para el/los agente(s) relevante(s), para que
refuerces el sistema en lugar de inflarlo. references/routing.md tiene las ubicaciones
exactas de lectura/escritura y formatos para cada agente; la versión corta:
| Agente | Configuración existente para leer (y luego escribir) |
|---|---|
| Claude | ~/.claude/CLAUDE.md (global), ./CLAUDE.md, memoria por proyecto ~/.claude/projects/<dir>/memory/, ~/.claude/skills/, ~/.claude/commands/ |
| Codex | ~/.codex/AGENTS.md (global), <repo>/AGENTS.md (proyecto), habilidades en ~/.agents/skills/ |
| Cursor | .cursor/rules/*.mdc (proyecto), .cursorrules heredado, AGENTS.md |
Para cada candidato pregúntate: ¿Esto ya está cubierto? Si sí → descártalo, o propón una pequeña edición que haga más precisa la regla existente. Nunca añadas una segunda regla que diga casi lo mismo. Si dos candidatos se superponen, fusiónalos. Prefiere editar sobre añadir.
Consejo multiagente: AGENTS.md es leído por Codex y Cursor, y muchas personas lo enlazan
simbólicamente a CLAUDE.md. Si una preferencia es genuinamente universal, prefiere escribirla
en un lugar donde todos los agentes la vean (un AGENTS.md, o un enlace simbólico
CLAUDE.md↔AGENTS.md) en lugar de duplicarla tres veces. Siempre resuelve los enlaces simbólicos
antes de escribir para saber qué archivo estás editando realmente.
4. Proponer un conjunto de cambios — diffs concretos con evidencia, con límite
Presenta un conjunto de cambios: una lista ordenada y escaneable donde cada elemento tiene
el agente + archivo objetivo, la edición exacta (un diff o un antes/después claramente
marcado), la evidencia y una confianza. Usa el formato en references/changeset-format.md.
Dos reglas lo mantienen sensato:
- Pon un límite. Muestra como máximo ~5 cambios por ejecución, primero los de mayor confianza. Cualquier otra cosa va a una sección de "pendientes" — anotado, no aplicado. Un aluvión de ediciones es cómo los flujos de trabajo se vuelven estúpidos.
- Clasifica por recurrencia × impacto. Una preferencia expresada tres veces que ahorrará una corrección cada sesión supera a una inteligente única cada vez.
Siempre guarda el conjunto de cambios en un informe con fecha incluso si no se aplica nada,
para que haya un registro al que volver (esto responde al "¿guardas las salidas en algún
lugar, o solo lees y sigues adelante?" del hilo). Escríbelo en ~/.introspect/reports/YYYY-MM-DD.md.
5. Aprobar — la puerta de entrada
Muestra el conjunto de cambios y deja que el usuario elija qué aplicar: todo, algunos o ninguno.
Por defecto, proponer-y-aprobar — no edites la configuración de ningún agente sin un sí
explícito. Usa AskUserQuestion (selección múltiple) para que puedan elegir elementos cuando
haya varios. Si el usuario ha solicitado explícitamente una ejecución desatendida/programada,
consulta "Ejecuciones desatendidas" más abajo.
6. Aplicar + registrar — reversiblemente
Para cada elemento aprobado, escribe en la superficie correcta (formatos completos en
references/routing.md):
- Claude — CLAUDE.md: añade bajo la sección
##correspondiente o edita la regla en su lugar; mantén el estilo de la casa (corto, imperativo, explica por qué). - Claude — memoria: crea/añade un archivo de nodo y añade una línea de índice a
MEMORY.md; sigue las convencionesfeedback_*/project_*/reference_*y los enlaces cruzados[[wikilink]]. - Claude — habilidad/comando: crea/edita
~/.claude/skills/<name>/SKILL.mdo~/.claude/commands/<name>.md. Si varias sesiones reescribieron el mismo script auxiliar, agrégalo. - Codex — AGENTS.md: añade dentro de un bloque gestionado (` …
AGENTS.md en ~32 KiB). Prefiere el
AGENTS.mden la raíz del proyecto (la aplicación de escritorio no carga de forma fiable el global). - Cursor — .cursor/rules/*.mdc: escribe un archivo de regla con frontmatter YAML (
alwaysApply: truepara preferencias siempre activas, odescription:+alwaysApply: false). NO intentes escribir las "Memorias" en la nube de Cursor; usa archivos de reglas. No escribas en elstate.vscdben vivo mientras Cursor se esté ejecutando.
Luego añade una línea al libro de registro en ~/.introspect/ledger.jsonl — un objeto JSON
por cambio aplicado: {date, agent, target_file, kind, summary, evidence, sessions, undo_hint}.
El libro de registro te permite (a) mostrar cómo se ha acumulado la configuración con el tiempo,
y (b) deshacer un cambio más adelante. Antes de editar un archivo existente, anota su estado
anterior en undo_hint (o guarda un .bak).
Modelo de seguridad (léelo — es la razón por la que esto es seguro de ejecutar a diario)
- Proponer, no imponer. Puerta de aprobación activada por defecto. El usuario ve cada diff.
- Umbral de recurrencia. No propongas a partir de una sola ocurrencia. Hábitos, no tácticas.
- Converger, no agitar. Refuerza/fusiona reglas existentes en lugar de añadir casi duplicados. Una ejecución que no cambia nada está bien y se espera en un día tranquilo.
- Limita el radio de explosión. Máximo ~5 cambios por ejecución; el resto a pendientes.
- Las reglas tratan sobre el usuario, no sobre el agente. Captura cómo quiere trabajar el usuario. No fabriques reglas que simplemente reiteren la competencia base de un agente (como "leer antes de editar") — eso es inflado. Una señal de "el agente se atascó / se repitió" merece un cambio solo cuando anotar una parte de la configuración del usuario evitaría la repetición.
- Nunca almacenes secretos. El recolector oculta formas comunes de claves/tokens, pero
mantente alerta: nunca copies una clave de API, contraseña, valor
.envo token en una regla o informe. Si ves uno, déjalo fuera y (si parece activo) avísale al usuario. - Reversible. Todo lo aplicado está en el libro de registro con una pista de deshacer.
- Superficie correcta, alcance correcto. Preferencias para todo el usuario → el archivo global de ese agente. Datos específicos del proyecto → la configuración de ese proyecto. No pongas trivialidades del proyecto en un archivo global.
Disparadores — tres formas de ejecutar
- Bajo demanda. "revisa mis hilos", "ejecuta introspect", "qué seguí repitiendo esta semana en Claude y Codex", "convierte las correcciones de hoy en reglas". Ventana por defecto: hoy.
- Diario / programado (nativo del arnés). Registra la ejecución a través del programador
nativo del arnés — la habilidad
scheduleo la herramienta de rutinaCronCreate— no un cron del SO, launchd o un bucle de shell. La programación nativa ejecuta la rutina dentro del arnés con las mismas herramientas y permisos, y el usuario la gestiona con/schedule. Un buen valor predeterminado es una vez al día por la noche durante la ventana de ese día. - Cada N sesiones / por fricción (opcional). Algunas personas (ver buildooor en el hilo
fuente) prefieren activar esto cuando algo ha ido mal o cada ~10 sesiones en lugar de por
reloj. Conéctalos como un hook
Stopque cuente las invocaciones y notifique después de N. Ofrécelo; nunca instales un hook sin aprobación.
Ejecuciones desatendidas
Si se invoca mediante una rutina programada sin presencia humana, no apliques cambios
silenciosamente a la configuración de ningún agente. En su lugar: ejecuta el pipeline, escribe el
informe con fecha que contenga el conjunto de cambios propuesto en ~/.introspect/reports/ y
muestra un breve resumen (a través de la notificación de la rutina) para que el usuario pueda
aprobar en su próxima sesión interactiva. La única categoría segura de aplicar
automáticamente sin supervisión es un nuevo nodo de memoria de Claude que no duplique nada —
e incluso entonces, regístralo. Mantén la acumulación bajo control humano; ese es el objetivo.
Referencias
references/routing.md— fuentes de lectura por agente + superficies de escritura + formatos exactos en disco (CLAUDE.md, memoria, AGENTS.md, .cursor/rules/*.mdc) y los esquemas de transcripción que utiliza el recolector.references/changeset-format.md— las plantillas de conjunto de cambios + informe + libro de registro.scripts/collect_threads.py— el recolector multiagente (ejecuta--selftestpara verificarlo).
Repitiendo el bucle central, porque es todo: recolecta los hilos de cada agente → encuentra los patrones recurrentes (no las tácticas únicas) → comprueba que no estén ya escritos → propón un conjunto de cambios pequeño, limitado y respaldado por evidencia → aplica solo lo aprobado en la configuración del agente correcto → regístralo reversiblemente.