janole/session-bandit

Pré-requisitos

Session Bandit é uma ferramenta CLI que deve estar instalada no sistema. Verifique se está disponível:

command -v session-bandit

Se não estiver instalado, instale globalmente:

npm install -g session-bandit

Se o pacote ainda não estiver no npm, instale a partir da fonte:

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

Requer Node.js 22+ e pnpm 10+ (apenas para compilar a partir da fonte; a instalação via npm requer apenas Node.js).

Verifique a instalação:

session-bandit --version

O que o Session Bandit faz

O Session Bandit indexa as transcrições de sessão que agentes de codificação (Claude Code, Codex, BotBandit) escrevem no disco como JSONL. Funciona completamente offline — sem chamadas de API, sem autenticação, sem rede. Por padrão, ele escaneia ~/.claude/projects/, ~/.codex/sessions/ e ~/.botbandit/sessions/.

Modos de saída

Prefira a saída padrão legível por máquina ao usar o Session Bandit como ferramenta de agente:

• list e search imprimem linhas JSON por padrão.
• extract, redact-check e doctor imprimem JSON por padrão.
• show imprime uma transcrição legível por humanos.

Use --pretty apenas quando uma visualização em terminal legível por humanos for útil para navegação ou relato ao usuário. Não adicione --pretty a comandos cuja saída você pretende analisar ou usar como entrada estruturada para um handoff ou nota de memória.

Comandos

Listar sessões

# Lista todas as sessões, mais recentes primeiro (linhas JSON)
session-bandit list

# Tabela legível por humanos com nível de importância
session-bandit list --pretty

# Filtra por agente ou projeto
session-bandit list --agent codex --project botbandit

# Ordena por substância/importância (sessões pesadas primeiro)
session-bandit list --sort importance

# Remove sessões triviais
session-bandit list --min-importance moderate

# Limita a um período de tempo: relativo (7d, 24h, 2w, 3m) ou data absoluta
session-bandit list --since 7d
session-bandit list --since 2026-06-01 --until 2026-06-15

Exibir uma transcrição de sessão

# ID completo ou correspondência por prefixo
session-bandit show 342647fa-5bf
session-bandit show 342647fa --agent claude

Pesquisar entre sessões

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

Extrair um resumo de sessão (recurso principal para handoffs/memórias)

# Resumo estruturado (JSON) — pontuação de substância, arquivos, comandos, erros, principais trocas
session-bandit extract 342647fa-5bf

# Envolve o resumo em um prompt de síntese pronto para envio
session-bandit extract 342647fa-5bf --prompt handoff
session-bandit extract 342647fa-5bf --prompt memory

# Inclui a transcrição completa no resumo
session-bandit extract 342647fa-5bf --full --prompt handoff

Verificar saúde de parsing

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

Verificar redação antes de publicar

# Relatório JSON por padrão
session-bandit redact-check 342647fa-5bf

# Relatório legível por humanos para revisão com o usuário
session-bandit redact-check 342647fa-5bf --pretty

# Pré-visualização mais conservadora
session-bandit redact-check 342647fa-5bf --redact strict

Exportar Markdown para revisão/publicação

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 "Interface Apple Watch"

export-md usa --redact cautious por padrão. Não use --redact none para um artefato público a menos que o usuário peça explicitamente e aceite o risco; a CLI exige --yes para esse modo.

Publicando uma sessão

Ao ser solicitado a publicar uma sessão de codificação, mantenha o Session Bandit determinístico e offline. Use a CLI para criar o artefato Markdown redigido e o relatório de redação; use seu julgamento como agente apenas para seleção de sessão, escolha de título/slug, polimento opcional de prosa e relato de risco ao usuário.

1. Encontre a sessão de origem. Se o usuário fornecer um ID de sessão, use-o diretamente. Caso contrário, pesquise ou liste sessões prováveis:

   session-bandit list --sort importance
   session-bandit search "o tópico"
   

   Use --agent ou --project quando o usuário restringir o alvo.

2. Escolha título, slug e caminhos de saída. Para um repositório no estilo GitHub Pages, prefira uma pasta por sessão:

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

   Mantenha slugs curtos, em minúsculas e estáveis. Se o título for incerto, proponha-o ao usuário antes de exportar.

3. Pré-visualize a redação antes de escrever o artefato:

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

   Relate as contagens e qualquer risco notável. Use --redact strict se a sessão parecer conter dados privados de cliente, credenciais, saída proprietária ou contexto local excepcionalmente sensível.

4. Exporte Markdown e o relatório:

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

   Não use --redact none para publicação pública a menos que o usuário solicite explicitamente e aceite o risco.

5. Revise antes de publicar. Inspecione o Markdown e o relatório de redação. Certifique-se de que seções de resumo, sessões relacionadas, comandos, saída de ferramentas e caminhos locais estejam razoáveis. A redação automatizada é de melhor esforço, não é prova de segurança.

6. Opcionalmente, polir o Markdown. Você pode adicionar ou editar uma breve introdução, cabeçalhos de seção ou uma nota de encerramento fora da saída da CLI. Não invente fatos; mantenha a transcrição, o resumo, a proveniência e o relatório de redação intactos.

7. Pergunte antes de tornar público. Antes de git add, git commit, git push ou qualquer ação de deploy, resuma o risco de redação e peça aprovação explícita do usuário, a menos que o usuário já tenha dado essa aprovação na mesma rodada.

Template GitHub Pages

Esta habilidade acompanha um template de publicação padrão em templates/github-pages-default/ ao lado deste SKILL.md. Use-o quando o usuário solicitar um repositório GitHub Pages, um site estático polido ou uma apresentação pública padrão para sessões exportadas.

Comportamento do template:

• É um site Jekyll/GitHub Pages com layouts e CSS personalizados.
• Espera sessões geradas em sessions/<slug>/index.md.
• Espera relatórios de redação ao lado das sessões como sessions/<slug>/redaction-report.json.
• Usa padrões de _config.yml para que o Markdown exportado do Session Bandit receba automaticamente o layout de sessão.
• Inclui um fixture local .design/session-page.html para verificações de layout sem Jekyll ou Pages deploy.
• É estático e autocontido; não adicione ativos externos, rastreadores, fontes ou scripts remotos a menos que o usuário peça explicitamente.

Ao inicializar um repositório de publicação vazio:

cp -R <diretório-da-habilidade>/templates/github-pages-default/. <repositório-alvo>/

Quando o repositório já existir, não sobrescreva _config.yml, _layouts/, assets/session.css, index.md ou README.md sem perguntar. Adicione ou atualize apenas sessions/<slug>/index.md, sessions/<slug>/redaction-report.json e uma entrada de índice se o usuário quiser um índice manual.

Para alterações visuais no template, prefira verificar templates/github-pages-default/.design/session-page.html localmente antes de publicar. Ele é intencionalmente construído a partir de HTML simples, portanto não requer Jekyll.

Escrevendo uma nota de handoff

Ao ser solicitado a escrever uma nota de handoff a partir de uma sessão anterior:

1. Encontre a sessão. Se o usuário fornecer um ID de sessão, use-o diretamente. Caso contrário, liste sessões recentes e escolha a relevante:

   session-bandit list --sort importance
   

   Ou pesquise por um tópico:

   session-bandit search "o tópico"
   

   Adicione --pretty apenas se precisar de uma tabela/excerto para navegação manual.

2. Gere o resumo com um prompt de handoff:

   session-bandit extract <sessionId> --prompt handoff
   

   Isso emite um resumo estruturado (pontuação de substância, arquivos escritos, erros, resumos/recaps, objetivo, estado final) envolto em um prompt de síntese que instrui o que escrever.

3. Escreva o handoff. O prompt pede para cobrir: o objetivo, o que foi feito, o estado atual e o que falta fazer. Use os dados estruturados do resumo (arquivos escritos, erros, principais trocas) como base factual. Mantenha conciso — um agente que retorna precisa do estado, não do histórico completo.

4. Salve o handoff onde o usuário desejar (armazenamento de documentos, arquivo markdown, etc.).

Escrevendo uma nota de memória

Ao ser solicitado a criar uma nota de memória a partir de uma sessão passada:

1. Encontre e extraia a sessão:

   session-bandit extract <sessionId> --prompt memory
   

2. Escreva a nota de memória. O prompt pede 2–4 frases cobrindo: sobre o que era a sessão, o resultado principal e arquivos/decisões que valem lembrar. Termine com um nível de importância sugerido (trivial / light / moderate / substantive / heavy).

3. Salve a nota de memória onde o usuário desejar.

Dicas

• Os templates --prompt handoff e --prompt memory são primeiros rascunhos. Sinta-se à vontade para adaptar o formato de saída às necessidades do usuário — os dados do resumo são a parte valiosa, não o texto do template.
• Use --full quando precisar da transcrição completa para contexto (por exemplo, trabalho complexo de várias etapas). Sem --full, o resumo é compacto e pode omitir detalhes.
• Recaps do Claude, compactações do Codex e eventos de memória/compactação do BotBandit são exibidos como mensagens de summary e incluídos nas extrações. Trate-os como contexto de síntese útil, mas ainda assim baseie handoffs e memórias nos arquivos, erros, testes e trocas finais do resumo.
• Antes de ajudar a publicar ou exportar uma sessão publicamente, execute session-bandit redact-check <sessionId> --pretty e relate o risco restante. A redação automatizada é de melhor esforço, não é prova de segurança.
• Para uma exportação Markdown, prefira session-bandit export-md <sessionId> --out <caminho> --report-out <caminhoDoRelatorio>, depois inspecione o relatório antes de sugerir commit/publicação.
• Markdown é o artefato de publicação canônico. Não crie uma transcrição HTML básica a menos que o usuário peça especificamente HTML; HTML de alta qualidade deve ser gerado a partir do Markdown revisado ou do pacote redigido.
• Prefira o template templates/github-pages-default/ incluído para novos repositórios de publicação GitHub Pages. É a apresentação pública padrão, a menos que o usuário solicite outro estilo.
• A pontuação de substância mede atividade (chamadas de ferramenta, escritas de arquivos, execuções de teste), não significância. Uma sessão curta pode conter uma decisão crítica. Leia as principais trocas, não apenas a pontuação.
• IDs de sessão podem ser especificados como prefixos (por exemplo, 342647fa em vez do UUID completo).
• Execute session-bandit doctor se algo parecer estranho — ele verifica se as suposições de parsing correspondem aos seus arquivos de sessão reais, incluindo desvios de formato, marcadores de injeção, tipos não reconhecidos e pulos silenciosos. Use --agent claude, --agent codex ou --agent botbandit para restringir a verificação.