janole/session-bandit

Requisitos previos

Session Bandit es una herramienta CLI que debe estar instalada en el sistema. Verifica si está disponible:

command -v session-bandit

Si no está instalada, instálala globalmente:

npm install -g session-bandit

Si el paquete aún no está en npm, instálalo desde la fuente:

git clone https://github.com/janole/session-bandit.git
cd session-bandit
pnpm install
pnpm -r build
npm install -g packages/cli

Requiere Node.js 22+ y pnpm 10+ (solo para compilar desde la fuente; la instalación con npm solo necesita Node.js).

Verifica la instalación:

session-bandit --version

Qué hace Session Bandit

Session Bandit indexa las transcripciones de sesiones que los agentes de codificación (Claude Code, Codex, BotBandit) escriben en disco como JSONL. Funciona completamente offline — sin llamadas a API, sin autenticación, sin red. Escanea ~/.claude/projects/, ~/.codex/sessions/ y ~/.botbandit/sessions/ de forma predeterminada.

Modos de salida

Prefiere la salida predeterminada legible por máquina al usar Session Bandit como herramienta de agente:

• list y search imprimen líneas JSON de forma predeterminada.
• extract, redact-check y doctor imprimen JSON de forma predeterminada.
• show imprime una transcripción legible por humanos.

Usa --pretty solo cuando una vista de terminal legible por humanos sea útil para navegar o informar al usuario. No agregues --pretty a comandos cuya salida planees analizar o usar como entrada estructurada para una transferencia o nota de memoria.

Comandos

Listar sesiones

# Listar todas las sesiones, las más recientes primero (líneas JSON)
session-bandit list

# Tabla legible por humanos con nivel de importancia
session-bandit list --pretty

# Filtrar por agente o proyecto
session-bandit list --agent codex --project botbandit

# Ordenar por sustancia/importancia (sesiones pesadas primero)
session-bandit list --sort importance

# Omitir sesiones triviales
session-bandit list --min-importance moderate

# Limitar a un período de tiempo: relativo (7d, 24h, 2w, 3m) o fecha absoluta
session-bandit list --since 7d
session-bandit list --since 2026-06-01 --until 2026-06-15

Mostrar una transcripción de sesión

# ID completo o coincidencia de prefijo
session-bandit show 342647fa-5bf
session-bandit show 342647fa --agent claude

Buscar en sesiones

session-bandit search "tool approval"
session-bandit search "apply_patch" --agent codex
session-bandit search "adapter" --since 3d --pretty

Extraer un resumen de sesión (la característica clave para transferencias/memorias)

# Resumen estructurado (JSON) — puntuación de sustancia, archivos, comandos, errores, turnos clave
session-bandit extract 342647fa-5bf

# Envolver el resumen en un aviso de síntesis listo para enviar
session-bandit extract 342647fa-5bf --prompt handoff
session-bandit extract 342647fa-5bf --prompt memory

# Incluir la transcripción completa en el resumen
session-bandit extract 342647fa-5bf --full --prompt handoff

Verificar la salud del análisis

session-bandit doctor
session-bandit doctor --agent codex
session-bandit doctor --agent botbandit

Verificar redacción antes de publicar

# Informe JSON de forma predeterminada
session-bandit redact-check 342647fa-5bf

# Informe legible por humanos para revisión con el usuario
session-bandit redact-check 342647fa-5bf --pretty

# Vista previa más conservadora
session-bandit redact-check 342647fa-5bf --redact strict

Exportar Markdown para revisión/publicación

session-bandit export-md 342647fa-5bf --out ./session.md
session-bandit export-md 342647fa-5bf --out ./session.md --report-out ./redaction-report.json
session-bandit export-md 342647fa-5bf --out ./session.md --title "Interfaz de Apple Watch"

export-md usa --redact cautious de forma predeterminada. No uses --redact none para un artefacto público a menos que el usuario lo solicite explícitamente y acepte el riesgo; la CLI requiere --yes para ese modo.

Publicar una sesión

Cuando te pidan publicar una sesión de codificación, mantén Session Bandit determinista y offline. Usa la CLI para crear el artefacto Markdown redactado y el informe de redacción; usa tu criterio de agente solo para la selección de sesión, elección de título/slug, pulido opcional de prosa e informar el riesgo al usuario.

1. Encuentra la sesión de origen. Si el usuario proporciona un ID de sesión, úsalo directamente. De lo contrario, busca o lista sesiones probables:

   session-bandit list --sort importance
   session-bandit search "el tema"
   

   Usa --agent o --project cuando el usuario acote el objetivo.

2. Elige título, slug y rutas de salida. Para un repositorio estilo GitHub Pages, prefiere una carpeta por sesión:

   sessions/<slug>/index.md
   sessions/<slug>/redaction-report.json
   

   Mantén los slugs cortos, en minúsculas y estables. Si el título es incierto, propónselo al usuario antes de exportar.

3. Vista previa de redacción antes de escribir el artefacto:

   session-bandit redact-check <sessionId> --pretty
   

   Informa los recuentos y cualquier riesgo notable. Usa --redact strict si la sesión parece contener datos privados de clientes, credenciales, resultados propietarios o contexto local inusualmente sensible.

4. Exporta Markdown y el informe:

   session-bandit export-md <sessionId> \
     --out sessions/<slug>/index.md \
     --report-out sessions/<slug>/redaction-report.json \
     --title "Título legible por humanos"
   

   No uses --redact none para publicación pública a menos que el usuario lo solicite explícitamente y acepte el riesgo.

5. Revisa antes de publicar. Inspecciona el Markdown y el informe de redacción. Asegúrate de que las secciones de resumen, sesiones relacionadas, comandos, resultados de herramientas y rutas locales sean razonables. La redacción automatizada es del mejor esfuerzo, no una prueba de seguridad.

6. Opcionalmente, pule el Markdown. Puedes agregar o editar una breve introducción, encabezados de sección o una nota de cierre fuera de la salida de la CLI. No inventes hechos; mantén intactos la transcripción, el resumen, la procedencia y el informe de redacción.

7. Pregunta antes de hacerlo público. Antes de git add, git commit, git push o cualquier acción de despliegue, resume el riesgo de redacción y pide la aprobación explícita del usuario a menos que el usuario ya la haya dado en el turno actual.

Plantilla de GitHub Pages

Esta habilidad incluye una plantilla de publicación predeterminada en templates/github-pages-default/ junto a este SKILL.md. Úsala cuando el usuario solicite un repositorio de GitHub Pages, un sitio estático pulido o una presentación pública predeterminada para las sesiones exportadas.

Comportamiento de la plantilla:

• Es un sitio Jekyll/GitHub Pages con diseños y CSS personalizados.
• Espera sesiones generadas en sessions/<slug>/index.md.
• Espera informes de redacción junto a las sesiones como sessions/<slug>/redaction-report.json.
• Usa valores predeterminados de _config.yml para que el Markdown exportado por Session Bandit obtenga automáticamente el diseño de sesión.
• Incluye un fixture local .design/session-page.html para verificar diseños sin Jekyll ni un despliegue de Pages.
• Es estático y autónomo; no agregues activos externos, rastreadores, fuentes o scripts remotos a menos que el usuario lo solicite explícitamente.

Al inicializar un repositorio de publicación vacío:

cp -R <directorio-de-habilidad>/templates/github-pages-default/. <repositorio-destino>/

Cuando el repositorio ya existe, no sobrescribas _config.yml, _layouts/, assets/session.css, index.md o README.md sin preguntar. Agrega o actualiza solo sessions/<slug>/index.md, sessions/<slug>/redaction-report.json y una entrada de índice si el usuario desea un índice manual.

Para cambios visuales en la plantilla, prefiere verificar templates/github-pages-default/.design/session-page.html localmente antes de publicar. Está construido intencionalmente a partir de HTML plano, por lo que no requiere Jekyll.

Escribir una nota de transferencia

Cuando te pidan escribir una nota de transferencia de una sesión anterior:

1. Encuentra la sesión. Si el usuario proporciona un ID de sesión, úsalo directamente. De lo contrario, lista las sesiones recientes y elige la relevante:

   session-bandit list --sort importance
   

   O busca un tema:

   session-bandit search "el tema"
   

   Agrega --pretty solo si necesitas una tabla o extracto para navegación manual.

2. Genera el resumen con un aviso de transferencia:

   session-bandit extract <sessionId> --prompt handoff
   

   Esto emite un resumen estructurado (puntuación de sustancia, archivos escritos, errores, resúmenes/recapitulaciones, objetivo, estado final) envuelto en un aviso de síntesis que te indica qué escribir.

3. Escribe la transferencia. El aviso te pide cubrir: el objetivo, lo que se hizo, el estado actual y lo que queda por hacer. Usa los datos estructurados del resumen (archivos escritos, errores, turnos clave) como base fáctica. Mantenlo conciso — un agente que retoma necesita el estado, no el historial completo.

4. Guarda la transferencia donde el usuario quiera (almacén de documentos, archivo markdown, etc.).

Escribir una nota de memoria

Cuando te pidan crear una nota de memoria de una sesión pasada:

1. Encuentra y extrae la sesión:

   session-bandit extract <sessionId> --prompt memory
   

2. Escribe la nota de memoria. El aviso pide 2–4 oraciones que cubran: de qué se trató la sesión, el resultado clave y los archivos/decisiones que vale la pena recordar. Termina con un nivel de importancia sugerido (trivial / light / moderate / substantive / heavy).

3. Guarda la nota de memoria donde el usuario quiera.

Consejos

• Las plantillas --prompt handoff y --prompt memory son borradores iniciales. Siéntete libre de adaptar el formato de salida a las necesidades del usuario — los datos del resumen son la parte valiosa, no el texto de la plantilla.
• Usa --full cuando necesites la transcripción completa para contexto (por ejemplo, trabajo complejo de varios pasos). Sin --full, el resumen es compacto y puede omitir detalles.
• Las recapitulaciones de Claude, compactaciones de Codex y eventos de memoria/compactación de BotBandit se muestran como mensajes summary y se incluyen en los extractos. Trátalos como contexto de síntesis útil, pero sigue basando las transferencias y memorias en los archivos, errores, pruebas y turnos finales del resumen.
• Antes de ayudar a publicar o exportar una sesión públicamente, ejecuta session-bandit redact-check <sessionId> --pretty e informa el riesgo restante. La redacción automatizada es del mejor esfuerzo, no una prueba de seguridad.
• Para una exportación Markdown, prefiere session-bandit export-md <sessionId> --out <ruta> --report-out <rutaInforme>, luego inspecciona el informe antes de sugerir commit/publicación.
• Markdown es el artefacto de publicación canónico. No crees una transcripción HTML básica a menos que el usuario solicite específicamente HTML; el HTML de alta calidad debe generarse a partir del Markdown revisado o del paquete redactado.
• Prefiere la plantilla incluida templates/github-pages-default/ para nuevos repositorios de publicación de GitHub Pages. Es la presentación pública predeterminada a menos que el usuario solicite otro estilo.
• La puntuación de sustancia mide actividad (llamadas a herramientas, escrituras de archivos, ejecuciones de pruebas), no importancia. Una sesión corta puede contener una decisión crítica. Lee los turnos clave, no solo la puntuación.
• Los IDs de sesión se pueden especificar como prefijos (por ejemplo, 342647fa en lugar del UUID completo).
• Ejecuta session-bandit doctor si algo parece extraño — verifica si las suposiciones de análisis coinciden con tus archivos de sesión reales, incluyendo desviaciones de formato, marcadores de inyección, tipos no reconocidos y omisiones silenciosas. Usa --agent claude, --agent codex o --agent botbandit para acotar la verificación.