AWS Builder Center

Builder Center

Depurando Travamentos do Terminal no Kiro CLI Causados por Arquivos Binários

Depurando Travamentos do Terminal no Kiro CLI Causados por Arquivos Binários

Saiba como arquivos binários grandes podem congelar seu terminal ao usar o Kiro CLI fora de repositórios de código, e como um simples arquivo .kiroignore evita o esgotamento de recursos e restaura a produtividade.

Carlos Biagolini

AWS Solutions Architect

Introdução

Eu organizo meu trabalho em diretórios por cartão de atividade. Cada tarefa, apresentação, artigo ou projeto tem sua própria pasta. Algumas dessas pastas contêm código. A maioria não. Elas guardam apresentações de slides, PDFs, imagens, vídeos e materiais de referência.
Quando comecei a usar o Kiro CLI  para auxiliar em tarefas nesses diretórios, notei um padrão: certas pastas travavam o terminal imediatamente na inicialização. O CLI ficava completamente sem resposta. Nenhuma tecla era registrada. A única saída era matar o processo a partir de outra janela do terminal.
Após investigar, encontrei a causa raiz. O Kiro CLI escaneia o diretório de trabalho na inicialização para construir contexto para o agente de IA. Quando esse diretório contém arquivos binários grandes, o CLI tenta processar todos eles, consumindo quantidades massivas de CPU e memória. No meu caso, uma única pasta de 101 MB com assets de apresentação foi suficiente para levar o processo a 93% de CPU e mais de 5 GB de RAM, efetivamente travando o terminal.
A correção foi simples: um arquivo .kiroignore.

O Problema: O Kiro CLI Indexa Tudo no Seu Diretório de Trabalho

O Kiro CLI inclui automaticamente seu diretório de trabalho como contexto em toda sessão. De acordo com a documentação oficial , a ferramenta recomenda usar Knowledge Bases para conteúdo maior que 10 MB ou contendo milhares de arquivos.
Quando você abre o Kiro CLI em um diretório, ele escaneia os arquivos para entender seu projeto. Isso funciona perfeitamente para repositórios de código onde os arquivos são pequenos arquivos de texto. Mas quando seu diretório de trabalho contém assets binários, o comportamento muda drasticamente:
  • Um arquivo .pptx de 37 MB é carregado no pipeline de escaneamento
  • Dezenas de arquivos .png em alta resolução (1-15 MB cada) são processados
  • Documentos PDF, vídeos MP4 e outros formatos binários são incluídos
  • Sem um .gitignore ou .kiroignore, nada é excluído
O resultado é que o processo do Kiro CLI consome todos os recursos disponíveis tentando processar arquivos que não pode usar de forma significativa como contexto. O terminal parece travado porque a TUI (Terminal User Interface) mantém o terminal em modo raw enquanto o processo em segundo plano está sobrecarregado.

Por Que Isso Afeta Mais Diretórios Sem Código

Repositórios de código naturalmente têm um .gitignore que exclui node_modules/, dist/, .env e outros arquivos grandes ou irrelevantes. O Kiro CLI respeita o .gitignore em repositórios git, então a maioria dos projetos de código funciona bem sem configuração adicional.
Mas diretórios sem código tipicamente não têm nenhuma dessas proteções:
  • Sem .gitignore (o diretório não é um repositório git)
  • Sem .kiroignore (o usuário não sabe que ele existe)
  • Arquivos binários grandes diretamente no diretório de trabalho
  • Subdiretórios cheios de imagens, documentos e mídia
Este é exatamente o cenário que causa o travamento.

A Solução: .kiroignore

O arquivo .kiroignore usa a mesma sintaxe do .gitignore e diz ao Kiro CLI quais arquivos pular ao escanear o diretório de trabalho. Coloque-o na raiz de qualquer diretório onde você planeja usar o Kiro CLI.

Meu .kiroignore v1: Um Ponto de Partida

Depois de lidar com esse problema em múltiplos diretórios, cheguei a um .kiroignore abrangente que cobre as causas mais comuns de travamentos e também aborda preocupações de segurança. Estou compartilhando aqui como ponto de partida. Você provavelmente precisará adaptá-lo ao seu fluxo de trabalho, e eu posso refiná-lo com o tempo, mas isso cobre os padrões que mais importam:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
# Segredos e credenciais
.env
.env.*
!.env.example
*.pem
*.key
*.p12

# Imagens
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.webp
*.bmp
*.tiff
*.ico

# Documentos
*.pdf
*.doc
*.docx
*.ppt
*.pptx
*.xls
*.xlsx
*.xlsm
*.odt
*.ods
*.odp

# Mídia
*.mp4
*.mp3
*.mov
*.avi
*.wav
*.mkv
*.flv
*.wmv

# Arquivos compactados
*.zip
*.tar
*.gz
*.rar
*.7z

# Arquivos de dados
*.csv
*.parquet
*.sqlite
*.db

# Dependências
node_modules/
vendor/
.venv/

# Saídas de build
dist/
build/
.next/

# Logs
*.log

# Arquivos temporários
.temp/
tmp/

# macOS
.DS_Store
O arquivo é organizado por categoria para facilitar adicionar ou remover padrões conforme suas necessidades evoluem. O princípio chave: exclua qualquer coisa que seja binária, grande, sensível ou irrelevante para o contexto da IA.

.kiroignore Global

Se você trabalha frequentemente em diretórios sem código, crie um arquivo de ignore global em ~/.kiro/settings/kiroignore com o mesmo conteúdo acima. Isso se aplica a todos os diretórios automaticamente, sem necessidade de um .kiroignore por diretório.

Diagnosticando o Problema

Se você suspeita que o Kiro CLI está travando devido a arquivos grandes no seu diretório de trabalho, veja como confirmar:

Verificar o Tamanho do Diretório

1
du -sh /caminho/para/seu/diretorio
Se o total exceder 10 MB e contiver arquivos binários, você provavelmente precisa de um .kiroignore.

Verificar Processos em Execução

A partir de outra janela do terminal:
1
ps aux | grep kiro | grep -v grep
Procure por alto uso de CPU e memória. No meu caso, a saída mostrou:
1
92.9% CPU 27.2% MEM 5125696 KB tui.js chat --agent local-agent
Uma sessão saudável do Kiro CLI não deve exceder algumas centenas de MB de memória durante a inicialização.

Matar o Processo Travado

1
2
3
4
5
# Encontrar o processo
ps aux | grep "kiro.*tui" | grep -v grep

# Matá-lo
kill <PID>
Em seguida, adicione um .kiroignore antes de reiniciar o Kiro CLI naquele diretório.

Boas Práticas

Sempre Adicione .kiroignore em Diretórios Sem Código

Se você usa o Kiro CLI em diretórios que contêm apresentações, documentos, imagens ou qualquer asset binário, adicione um .kiroignore antes da sua primeira sessão. Prevenção é mais simples do que depurar um terminal travado.

Use o Ignore Global para Proteção Consistente

O arquivo de ignore global em ~/.kiro/settings/kiroignore protege você em todos os diretórios. Configure uma vez e esqueça.

Mantenha Arquivos de Texto Acessíveis

O .kiroignore deve excluir arquivos binários, não tudo. Arquivos Markdown, notas de texto e arquivos de configuração são exatamente o tipo de conteúdo que o Kiro CLI pode usar efetivamente como contexto. Seja seletivo no que você exclui.

Verifique o Tamanho do Diretório Antes de Abrir o Kiro CLI

Um rápido du -sh . antes de iniciar o Kiro CLI em um diretório desconhecido pode salvá-lo de um terminal travado. Se a saída mostrar dezenas ou centenas de megabytes, verifique o que está ocupando espaço e adicione regras de ignore apropriadas.

Importante: Retomar Sessões Antigas Pode Ignorar o .kiroignore

Um detalhe que me pegou de surpresa: depois de adicionar o .kiroignore, retomei uma sessão antiga usando kiro-cli chat --resume-picker e o terminal travou novamente.
O motivo é que --resume e --resume-picker recarregam o histórico completo da conversa do banco de dados local. Se a sessão original foi criada antes do .kiroignore existir, o contexto pesado daquela sessão é restaurado como estava. O .kiroignore afeta apenas o escaneamento inicial de arquivos ao iniciar uma nova sessão. Ele não limpa retroativamente sessões salvas anteriormente.
A correção é direta: depois de adicionar um .kiroignore a um diretório que anteriormente causava travamentos, inicie uma sessão nova em vez de retomar:
1
2
3
4
5
# Iniciar nova sessão (respeita o .kiroignore)
kiro-cli chat

# NÃO retome sessões antigas de antes do .kiroignore ser adicionado
# kiro-cli chat --resume-picker # pode travar
Se você quiser limpar sessões antigas de um diretório problemático:
1
2
kiro-cli chat --list-sessions
kiro-cli chat --delete-session <SESSION_ID>

Conclusão

O arquivo .kiroignore é uma pequena adição que previne um problema significativo de usabilidade. Ferramentas de terminal nativas de IA como o Kiro CLI são projetadas para repositórios de código onde os arquivos são pequenos e baseados em texto. Quando você as usa em diretórios com grandes assets binários, o processo de escaneamento pode sobrecarregar os recursos do sistema e travar o terminal.
Se você organiza seu trabalho em diretórios específicos por tarefa como eu, e esses diretórios contêm qualquer coisa além de código e markdown, um .kiroignore não é opcional. É a diferença entre um fluxo de trabalho produtivo assistido por IA e um terminal travado.

Referências

Mantenha-se Conectado

Se você achou este guia útil e quer aprender mais sobre ferramentas de desenvolvimento nativas de IA, produtividade no terminal e arquitetura em nuvem, siga o autor para conteúdos e tutoriais futuros:
Fique ligado para mais walkthroughs práticos e soluções para desafios de arquitetura e segurança em nuvem.
Boas construções na nuvem!
# kiro# kiro-agent# ai# developer-tools# ai-for-developers
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article