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

URL: https://agentvera.dev/pt/blog/how-to-use-crush/ · Publicado: 2026-11-17

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.

**Resumo:**

- Instale com brew install charmbracelet/tap/crush, npm install -g @charmland/crush ou winget install charmbracelet.crush, rode crush num projeto, aperte Ctrl+L para escolher o modelo e cole uma chave ou faça login.
- O Crush pergunta antes de chamar ferramentas e deixa você liberar uma ferramenta para a sessão toda. crush run cuida de tarefas avulsas e entrada por pipe; crush -C ou crush -s <id> retoma uma sessão.
- Desde a v0.88 a configuração fica num arquivo crushrc (Bash com comandos do Crush); crush.json ainda funciona, mas está obsoleto. O Crush lê AGENTS.md, CRUSH.md e CLAUDE.md sozinho.

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](https://github.com/charmbracelet "Charm no GitHub"), 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

```bash
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

```bash
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):

```bash
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:

```bash
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

```bash
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:

```bash
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](/pt/blog/claude-md-agents-md/ "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.** `--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](/pt/ "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](/pt/agents/crush/ "Crush no AgentVera") 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](/pt/features/mcp-manager/ "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](/pt/features/workspace/ "Workspace") ao lado de outros agentes e confira as mudanças com a [revisão de código](/pt/features/code-review/ "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](/pt/download/ "Baixar 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](https://github.com/charmbracelet/crush "README do Crush"), [documentação de configuração](https://github.com/charmbracelet/crush/tree/main/docs/config "Configuração do Crush"), [releases](https://github.com/charmbracelet/crush/releases "Releases do Crush"), [licença](https://github.com/charmbracelet/crush/blob/main/LICENSE.md "Licença do Crush"), [Hyper](https://hyper.charm.land "Hyper da Charm").

## 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.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito roda 2 agentes ao mesmo tempo. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/
