Convide um amigo e ganhe 1 mês de Pro grátisComo funciona

Como usar o Crush: guia passo a passo do agente de código da Charm

Como usar o Crush, o agente de código da Charm para o terminal: instalar, escolher provedor ou modelo local, aprovar ferramentas, crush run, sessões e crushrc.

Solviera Teknoloji 7 min de leitura

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+L troca o modelo; Ctrl+N começa uma sessão nova e Ctrl+S lista as sessões.
  • @ menciona um arquivo; Ctrl+F adiciona um arquivo ou imagem; Ctrl+V cola uma imagem.
  • Shift+Tab alterna entre os modos, incluindo o modo Plan, em que o Crush define os passos antes de editar.
  • Ctrl+O abre seu editor para uma mensagem longa; Ctrl+G mostra a ajuda; Ctrl+C sai.

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çãoPreçoObservações
CrushGrátisCom suas próprias chaves ou modelos locais
Hyper por usoA partir de US$ 5 pré-pagosModelos de pesos abertos hospedados pela Charm
Planos mensais do HyperUS$ 10 a US$ 200 por mêsCréditos semanais com uma janela móvel de 5 horas
Sua própria chaveO preço do seu provedorAnthropic, 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. --yolo agora 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-by aos commits. Mude isso com option attribution-trailer-style.
  • Área de transferência no Linux. Copiar e colar exige wl-copy ou xclip/xsel.
  • Onde ficam os logs. crush logs --tail 50 mostra o que deu errado; os logs ficam na pasta .crush do 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 --json e 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.

Perguntas frequentes

O Crush é gratuito?

Usar o Crush não custa nada: você traz suas próprias chaves de API ou um modelo local. A Charm também vende o Hyper, um provedor hospedado de modelos de pesos abertos, com planos mensais de US$ 10 a US$ 200 ou crédito pré-pago a partir de US$ 5 em novembro de 2026. O Crush usa a FSL-1.1-MIT, uma licença source-available cujas versões viram MIT mais tarde.

O Crush funciona com modelos locais?

Sim. Adicione um provedor Ollama, LM Studio, llama.cpp ou LiteLLM no crushrc, por exemplo provider add ollama --type ollama --base-url "http://localhost:11434/v1/", e o Crush descobre os modelos dele.

Como retomo uma sessão do Crush?

crush -C (ou --continue) reabre a sessão mais recente do projeto, e crush -s <id> reabre uma específica. crush session list mostra as sessões, e o Crush imprime o comando para retomar quando você sai.

O Crush lê CLAUDE.md ou AGENTS.md?

Os dois. O Crush lê AGENTS.md, CRUSH.md, CLAUDE.md, GEMINI.md, .cursorrules e .github/copilot-instructions.md, se existirem. Initialize Project, na paleta de comandos, escreve um AGENTS.md para você.

O que crush --yolo faz?

Ele pula as confirmações, mas continua bloqueando os comandos que o Crush considera perigosos. -yy (modo sysadmin) libera esses também. Use os dois só em ambientes descartáveis.

Reúna seus agentes em uma só mesa.

Baixe o AgentVera de graça; as CLIs que você já instalou estão prontas para usar.

Mais artigos