AWS Builder Center

Builder Center

Corrigindo Travamentos Intermitentes no Terminal do Kiro CLI Causados por Personalizações do Shell

Corrigindo Travamentos Intermitentes no Terminal do Kiro CLI Causados por Personalizações do Shell

Entenda como os hooks do Oh-My-Zsh interferem no protocolo OSC 633 usado pelo Kiro CLI

Carlos Biagolini

AWS Solutions Architect

Introdução

Este artigo é um complemento ao meu post anterior, Depurando Travamentos do Terminal no Kiro CLI Causados por Arquivos Binários . Naquele artigo, abordei a causa mais impactante dos travamentos do terminal: arquivos binários grandes no diretório de trabalho sobrecarregando a varredura de contexto do Kiro CLI. A solução foi um arquivo .kiroignore, que resolveu a maioria dos meus problemas de travamento.
No entanto, após aplicar essa correção, ainda experimentei travamentos ocasionais — menos frequentes, menos previsíveis, mas ainda presentes. O terminal ficava sem resposta por segundos ou minutos, às vezes exigindo o encerramento forçado do processo. A taxa de erros era significativamente menor do que antes, mas era suficiente para atrapalhar meu fluxo de trabalho.
Após investigação adicional, encontrei um segundo fator contribuinte: o Oh-My-Zsh interferindo no protocolo de integração do terminal do qual as ferramentas de IA dependem. Isso também é confirmado pela documentação oficial de solução de problemas do Kiro , que afirma explicitamente que personalizações do shell como Oh My Posh, bash-it e temas como Powerlevel10k/9k são causas comuns de falhas na integração do terminal.

O Problema

O sintoma é familiar: enquanto você trabalha no Kiro CLI (ou qualquer ferramenta de IA baseada em TUI, como VS Code com Copilot ou Cursor), o terminal trava aleatoriamente. Nenhuma tecla é registrada. O cursor para de piscar. A sessão parece completamente morta.
O que diferencia isso do problema com arquivos binários é o padrão: acontece de forma intermitente e imprevisível. Às vezes o terminal funciona bem por horas; outras vezes trava em minutos. O .kiroignore não ajuda porque a causa raiz não é a varredura de arquivos — é o próprio shell.

Análise da Causa Raiz

Como as Ferramentas de IA para Terminal Funcionam

Ferramentas modernas de terminal nativas de IA operam em modo raw, assumindo controle total do terminal:
  • -echo — o que você digita não é exibido pelo sistema operacional (a ferramenta renderiza)
  • -icanon — o processamento de linha é desabilitado
  • -isig — sinais como Ctrl+C são capturados pela ferramenta, não pelo sistema operacional

O Protocolo OSC 633

Para executar comandos do shell e capturar sua saída, essas ferramentas dependem de sequências de escape OSC 633 — um protocolo invisível onde o shell emite marcadores:
  • \e]633;C\a — comando iniciado
  • \e]633;D\a — comando concluído
A ferramenta de IA envia um comando, aguarda o marcador de "concluído" e então lê a saída. Se esse marcador nunca chega, a ferramenta fica esperando indefinidamente — e como ela mantém o terminal em modo raw, você perde todo o controle.

Onde o Oh-My-Zsh Quebra as Coisas

O Oh-My-Zsh registra múltiplos hooks precmd e preexec no ciclo de vida do prompt do zsh. Esses hooks:
  1. São disparados entre cada execução de comando
  2. Modificam o pipeline de renderização do prompt
  3. Podem interferir ou engolir as sequências de escape OSC 633
Quando os hooks do Oh-My-Zsh disparam em uma ordem que quebra o rastreamento de sequência, a ferramenta de IA nunca recebe o sinal de "comando concluído". Ela espera para sempre. O terminal parece travado.
Isso não é específico de nenhum tema em particular. O framework em si injeta hooks independentemente do tema escolhido. No entanto, temas mais pesados (como Powerlevel10k) pioram o problema porque adicionam mais hooks e processos em segundo plano.

O Que a Documentação Oficial do Kiro Diz

A página de solução de problemas do Kiro  documenta isso em "Kiro Stuck in 'Working...' Status on Terminal Commands or Kiro Does Not See Terminal Output":
Isso é tipicamente causado por personalizações do shell que interferem na integração do terminal. Causas comuns incluem personalizações como bash-it no bash ou Oh My Posh no zsh, e temas como Powerlevel10k/9k.
A documentação recomenda desabilitar essas personalizações ao executar dentro do Kiro usando uma verificação condicional na variável de ambiente TERM_PROGRAM.

Opções de Correção

Opção 1: Carregamento Condicional (Abordagem Allowlist — Recomendada)

Esta é a abordagem que eu recomendo. Em vez de listar cada ferramenta de IA onde o Oh-My-Zsh deve ser desabilitado (blocklist), você lista apenas os terminais onde deseja que ele seja habilitado (allowlist). Dessa forma, qualquer nova ferramenta de IA que você instalar no futuro estará automaticamente protegida sem alterar sua configuração.
Primeiro, identifique o valor de TERM_PROGRAM do seu terminal executando isso em cada terminal que você usa:
1
echo "TERM_PROGRAM=$TERM_PROGRAM"
Valores comuns:
TerminalValor de TERM_PROGRAM
macOS Terminal.appApple_Terminal
iTerm2iTerm.app
Kiro IDEkiro
VS Codevscode
Então adicione isso ao seu ~/.zshrc:
1
2
3
4
5
6
# Carrega Oh-My-Zsh apenas nos terminais onde você quer a experiência personalizada
if [[ "$TERM_PROGRAM" == "Apple_Terminal" ]]; then
source $ZSH/oh-my-zsh.sh
else
autoload -Uz compinit && compinit
fi
Se você usa múltiplos terminais regulares (ex.: Terminal.app e iTerm2), adicione-os à condição:
1
2
3
4
5
if [[ "$TERM_PROGRAM" == "Apple_Terminal" || "$TERM_PROGRAM" == "iTerm.app" ]]; then
source $ZSH/oh-my-zsh.sh
else
autoload -Uz compinit && compinit
fi
Por que autoload -Uz compinit && compinit? Sem essa linha, você perde completamente o tab completion dentro das ferramentas de IA. Esse comando inicializa o sistema de completação nativo do zsh para que você ainda tenha autocomplete para comandos, caminhos e argumentos — sem os hooks do Oh-My-Zsh.
Por que allowlist em vez de blocklist? A documentação do Kiro sugere a abordagem blocklist (if TERM_PROGRAM == "kiro"), que funciona mas exige que você atualize a condicional toda vez que instalar uma nova ferramenta de IA. A abordagem allowlist é à prova de futuro: você lista apenas os terminais onde ativamente deseja o Oh-My-Zsh, e todo o resto recebe um shell limpo por padrão.
Dica: Adicione um alias para carregar o Oh-My-Zsh sob demanda em qualquer sessão onde você precisar:
1
alias load-omz="source $ZSH/oh-my-zsh.sh"
Então basta digitar load-omz sempre que quiser a experiência completa do framework (temas, plugins, aliases) — mesmo dentro do Kiro se necessário.
Prós e contras:
  • Você mantém o Oh-My-Zsh nos seus terminais regulares escolhidos
  • Todas as ferramentas de IA (atuais e futuras) recebem um shell limpo sem interferência de hooks
  • Você ainda pode carregar o Oh-My-Zsh manualmente em qualquer lugar com load-omz
  • Não é necessário atualizar a configuração quando novas ferramentas de IA forem lançadas

Opção 2: Desabilitar Apenas o Tema (Manter Plugins)

Se você depende muito dos plugins do Oh-My-Zsh (git, aws, docker, etc.) mas pode viver sem o tema:
1
2
3
4
5
if [[ "$TERM_PROGRAM" == "kiro" || "$TERM_PROGRAM" == "vscode" ]]; then
ZSH_THEME=""
else
ZSH_THEME="gnzh"
fi
Prós e contras:
  • Plugins ainda carregam em todos os lugares (aliases do git, autocomplete do aws)
  • Hooks do tema são removidos nos contextos de ferramentas de IA
  • A sobrecarga do framework permanece, mas os hooks mais problemáticos são eliminados
  • Pode não resolver completamente o problema se plugins também interferirem

Opção 3: Correção Específica para Powerlevel10k

Se você usa especificamente o Powerlevel10k, a documentação do Kiro fornece uma correção direcionada. Adicione isso ao seu .p10k.zsh:
1
typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true
Isso diz ao Powerlevel10k para cooperar com o protocolo de integração do terminal em vez de sobrescrevê-lo.

O Que Eu Escolhi

Eu optei pela Opção 1 (abordagem allowlist) — o Oh-My-Zsh só carrega no Terminal.app, e todo o resto recebe um shell limpo.
Meu raciocínio: a correção com .kiroignore do meu artigo anterior resolveu os travamentos de alta frequência (causados por arquivos binários). O problema do Oh-My-Zsh causava travamentos de menor frequência, mas ainda disruptivos. Ao usar a abordagem allowlist, eu só preciso especificar onde quero o Oh-My-Zsh, e qualquer nova ferramenta de IA que eu instalar no futuro estará automaticamente protegida.
Também adicionei o alias load-omz para que, na rara ocasião em que preciso de funcionalidades do Oh-My-Zsh dentro de uma ferramenta de IA (para um alias rápido do git, por exemplo), eu possa carregá-lo manualmente sem reiniciar a sessão.

Recuperação de Emergência

Se seu terminal já está travado, veja como recuperar sem fechar a janela:
A partir de outra sessão de terminal:
1
2
3
4
5
6
7
8
# Encontrar o processo travado
ps aux | grep "kiro.*tui" | grep -v grep

# Encerrar o processo
kill <PID>

# Ou restaurar o terminal diretamente
stty sane < /dev/ttysXXX
Substitua ttysXXX pelo TTY do terminal travado (encontre-o na saída do ps).

Resumo: Duas Correções para Dois Problemas

Se você está enfrentando travamentos de terminal com o Kiro CLI, provavelmente existem duas causas independentes:
ProblemaFrequênciaCorreção
Arquivos binários grandes no diretório de trabalhoAlta (trava em toda inicialização)Arquivo .kiroignore (veja o artigo anterior)
Oh-My-Zsh / personalizações do shell interferindo com OSC 633Menor (travamentos intermitentes)Carregamento condicional: pular OMZ dentro do Kiro (verificação TERM_PROGRAM)
Aplique ambas as correções para uma experiência estável.

Referências

Mantenha-se Conectado

Se este guia foi útil e você quer aprender mais sobre produtividade no terminal, ferramentas de desenvolvimento nativas de IA, configuração do zsh e otimização de fluxo de trabalho para desenvolvedores, siga o autor para conteúdos e tutoriais futuros:
Fique ligado para mais tutoriais práticos e soluções para desafios de arquitetura e segurança na nuvem.
Boas construções na nuvem!
# kiro# kiro-agent# developer-tools# ai-for-developers# ai
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