Para usar o Crush, o agente de código da Charm, você instala com brew install charmbracelet/tap/crush (ou npm, winget e outros), roda crush dentro de um projeto, aperta Ctrl+L para escolher um modelo e cola uma chave de API ou faz login, e então descreve a tarefa. O Crush pergunta antes de rodar ferramentas e, desde a versão 0.88, as configurações ficam num arquivo crushrc em vez de crush.json.
Este guia cobre o Crush em novembro de 2026 (versão 0.101): instalação, provedores e modelos locais, a interface, aprovações, crush run, sessões, configuração, arquivos de contexto, MCP e custos.
O que é o Crush
O Crush é um agente de código para o terminal feito pela Charm, a equipe por trás do Bubble Tea e de outras ferramentas de terminal, e dá para perceber: é uma das interfaces mais caprichadas da categoria. Ele funciona com quase qualquer modelo: Anthropic, OpenAI, Gemini, OpenRouter, Groq, xAI, Bedrock, Vertex, Azure, modelos locais e o próprio serviço Hyper da Charm. Dá para trocar de modelo no meio de uma sessão sem perder o contexto.
O Crush ainda não chegou à versão 1.0 e lança uma versão menor mais ou menos toda semana, com builds nightly no meio. A licença é FSL-1.1-MIT: o código-fonte é público e cada versão passa a ser MIT mais tarde, mas hoje não é uma licença open source aprovada pela OSI.
Passo 1: instale
brew install charmbracelet/tap/crush # macOS and Linux
npm install -g @charmland/crush # any platform with Node
winget install charmbracelet.crush # Windows
go install github.com/charmbracelet/crush@latest
Também há pacotes para Arch (yay -S crush), Nix, FreeBSD e Scoop, além de repositórios apt e yum em repo.charm.sh. O Crush roda em macOS, Linux, Windows (PowerShell e WSL) e nos BSDs.
Passo 2: escolha um modelo
cd my-project
crush
Aperte Ctrl+L para abrir o seletor de modelos, escolha um provedor e cole a chave dele. O Crush também lê chaves do ambiente, por exemplo ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY ou OPENROUTER_API_KEY. Para usar uma assinatura em vez de uma chave, rode crush login com copilot, openai (um plano do ChatGPT), grok ou hyper.
Para um modelo local, adicione um provedor na sua configuração (passo 6):
provider add ollama --type ollama --base-url "http://localhost:11434/v1/"
O Crush pega a lista de modelos do Catwalk, um catálogo da comunidade que se atualiza sozinho; crush models mostra o que está disponível e crush update-providers atualiza a lista.
Passo 3: trabalhe numa sessão
Descreva a tarefa com suas palavras. As teclas que valem a pena aprender primeiro:
Ctrl+P(ou/) abre a paleta de comandos: resumir a sessão, inicializar o projeto, ligar e desligar servidores MCP e skills, trocar o tema.Ctrl+Ltroca o modelo;Ctrl+Ncomeça uma sessão nova eCtrl+Slista as sessões.@menciona um arquivo;Ctrl+Fadiciona um arquivo ou imagem;Ctrl+Vcola uma imagem.Shift+Tabalterna entre os modos, incluindo o modo Plan, em que o Crush define os passos antes de editar.Ctrl+Oabre seu editor para uma mensagem longa;Ctrl+Gmostra a ajuda;Ctrl+Csai.
Passo 4: aprovações e modo yolo
O Crush pergunta antes de cada chamada de ferramenta. No diálogo, a permite uma vez, s libera aquela ferramenta pelo resto da sessão, d recusa e t mostra o diff. Comandos somente leitura como ls ou git status rodam sem perguntar.
Para parar de ser perguntado sobre ferramentas em que você confia, libere-as na configuração; para esconder uma ferramenta por completo, bloqueie-a:
permissions allow view ls grep edit
permissions deny bash
crush --yolo (ou -y, ou Ctrl+Y numa sessão) pula as confirmações, mas continua bloqueando os comandos que o Crush considera perigosos. -yy liga o modo sysadmin, que libera esses também. Deixe os dois para contêineres e máquinas descartáveis.
Passo 5: crush run para tarefas avulsas
crush run "add a unit test for the price formatter"
git diff | crush run "review this diff for bugs"
cat README.md | crush run "tighten the wording" > README.new.md
-m escolhe o modelo (provider/model), -q esconde o indicador de progresso e -s <id> ou -C continua uma sessão. crush run não tem opção de saída em JSON; para resultados estruturados, peça o formato no prompt e confira.
Passo 6: crushrc e configuração
Desde a versão 0.88, o Crush lê as configurações de um arquivo crushrc: um script Bash com comandos do Crush, executado pelo próprio interpretador do Crush para se comportar igual no Windows. Ele procura .crushrc ou crushrc no projeto e ~/.config/crush/crushrc no nível global, e junta o que encontrar, com o projeto prevalecendo. Um exemplo pequeno:
model large anthropic/claude-sonnet-5-5
model small anthropic/claude-haiku-5-5
permissions allow view ls grep
mcp add docs --type http --url https://example.com/mcp
lsp add go --command gopls
crush.json e .crush.json ainda funcionam, mas estão obsoletos e não recebem recursos novos. crush dirs mostra onde o Crush guarda a configuração e os dados.
Um aviso: um crushrc é código. Tudo dentro de $(...) roda quando o Crush inicia, então leia o arquivo antes de abrir o Crush num repositório que você não conhece.
Passo 7: AGENTS.md, MCP e LSP
Arquivos de contexto. O Crush lê AGENTS.md, CRUSH.md, CLAUDE.md, GEMINI.md, .cursorrules e .github/copilot-instructions.md sem nenhuma configuração, além de ~/.config/crush/CRUSH.md para todos os projetos. Initialize Project, na paleta de comandos, analisa o repositório e escreve um AGENTS.md. Nosso guia de CLAUDE.md e AGENTS.md explica o que colocar nele.
MCP. O Crush suporta servidores stdio, HTTP e SSE, incluindo login com OAuth. Adicione-os com mcp add no crushrc e ligue ou desligue pela paleta.
LSP. Servidores de linguagem dão ao Crush os mesmos diagnósticos que seu editor vê. Adicione um com lsp add ou deixe que option auto-lsp configure tudo.
Quanto custa o Crush (em novembro de 2026)
| Opção | Preço | Observações |
|---|---|---|
| Crush | Grátis | Com suas próprias chaves ou modelos locais |
| Hyper por uso | A partir de US$ 5 pré-pagos | Modelos de pesos abertos hospedados pela Charm |
| Planos mensais do Hyper | US$ 10 a US$ 200 por mês | Créditos semanais com uma janela móvel de 5 horas |
| Sua própria chave | O preço do seu provedor | Anthropic, OpenAI, Gemini, OpenRouter e outros |
O Crush envia métricas de uso pseudônimas por padrão; defina CRUSH_DISABLE_METRICS=1 ou DO_NOT_TRACK=1 para desligá-las.
Armadilhas comuns
- Seguir guias de crush.json. A maioria dos tutoriais de antes de agosto de 2026 mostra só JSON. Ainda funciona, mas as opções novas chegam no
crushrc. - O yolo mudou na v0.100.
--yoloagora bloqueia comandos perigosos em vez de perguntar; scripts que dependiam do comportamento antigo podem precisar de-yy. - Trailers nos commits. O Crush adiciona por padrão um trailer
Assisted-byaos commits. Mude isso comoption attribution-trailer-style. - Área de transferência no Linux. Copiar e colar exige
wl-copyouxclip/xsel. - Onde ficam os logs.
crush logs --tail 50mostra o que deu errado; os logs ficam na pasta.crushdo projeto.
Rodando o Crush ao lado de outras CLIs no AgentVera
Se o Crush é o único agente que você usa, a interface dele pode bastar. Fica mais difícil quando o Crush roda ao lado do Claude Code, do Codex ou do Gemini CLI no mesmo projeto. O AgentVera é um app desktop que roda essas CLIs lado a lado em terminais reais, com suas próprias instalações e chaves. O suporte ao Crush funciona assim:
- Uma sessão por agente. O AgentVera encontra a sessão que o Crush cria por meio de
crush session list --jsone a reabre com--session <id>nas próximas execuções, então a conversa sobrevive a um reinício do app. - Uma conta por agente. Cada conta do Crush em Configurações → Contas ganha a própria pasta de dados e o próprio
crush login, e você pode adicionar chaves da Anthropic, OpenAI, OpenRouter ou Gemini. - MCP e conflitos. Os servidores do gerenciador de MCP do AgentVera chegam ao Crush pela configuração dele, e o AgentVera adiciona um hook próprio para ver em quais arquivos cada agente mexe.
- Painéis e revisão. Rode o Crush na grade do workspace ao lado de outros agentes e confira as mudanças com a revisão de código.
O plano gratuito executa 2 agentes ao mesmo tempo e inclui MCP, Git, Docker, SSH, revisão de código e economia de tokens. O Pro custa US$ 9,99 por mês e não tem limite de agentes; se você nunca teve um teste, seu primeiro login no app ativa o Pro por 7 dias sem cartão. Para experimentar, baixe o AgentVera.
Conclusão
Começar com o Crush leva dois passos: instalar e rodar crush, depois escolher um modelo com Ctrl+L. A partir daí, as configurações que importam ficam no crushrc: quais ferramentas podem rodar sem perguntar, quais modelos usar para tarefas grandes e pequenas, e quais servidores MCP e de linguagem carregar. Mantenha um AGENTS.md no projeto e o Crush, como a maioria dos agentes, vai segui-lo.
Fontes: Crush no GitHub, documentação de configuração, releases, licença, Hyper.