Guia Definitivo: OpenCode

OpenCode é o agente de codificação open-source que conquistou 160K+ stars no GitHub em tempo recorde. Escrito em TypeScript e Go, roda como TUI no terminal, app desktop ou extensão de IDE — e conecta a 75+ providers de LLM, de Claude e GPT a modelos locais via Ollama. Se você quer um agente flexível, sem vendor lock-in e com controle total, este é o guia que você precisa.

Overview

O que é o OpenCode

OpenCode é um agente de codificação open-source criado pela Anomaly Innovations (o time por trás do terminal.shop e do SST). Diferente de ferramentas proprietárias como Cursor ou Claude Code, o OpenCode é 100% código aberto sob licença MIT — você pode inspecionar, modificar e hospedar como quiser.

O diferencial central: agnóstico de provider. Enquanto Claude Code só funciona com Anthropic e Codex só com OpenAI, o OpenCode conecta a qualquer LLM disponível no mercado. São 75+ providers via integração com Models.dev, incluindo:

• Anthropic (Claude Sonnet, Opus, Haiku)
• OpenAI (GPT-5, GPT-4.1)
• Google (Gemini 2.5 Pro)
• Modelos open-source (DeepSeek, Qwen, Kimi, MiniMax)
• Modelos locais via Ollama
• GitHub Copilot (login com sua conta existente)
• ChatGPT Plus/Pro (login com sua conta OpenAI)

Modelo de execução

O OpenCode opera em múltiplas interfaces:

Preço

O OpenCode em si é gratuito e open-source. O custo vem do provider de LLM que você escolher:

Números que impressionam

• 160K+ GitHub stars (maio 2026)
• 900+ contributors
• 7.5M+ desenvolvedores usando mensalmente
• 13.000+ commits
• 18 comandos CLI de primeiro nível
• 60+ atalhos de teclado na TUI

Tutorial

Instalação

O OpenCode oferece múltiplas formas de instalação. A mais rápida:

curl -fsSL https://opencode.ai/install | bash

Outras opções:

# Via npm
npm install -g opencode-ai

# Via Homebrew (macOS/Linux)
brew install anomalyco/tap/opencode

# Via Arch Linux
sudo pacman -S opencode

# Via Chocolatey (Windows)
choco install opencode

# Via Scoop (Windows)
scoop install opencode

Pré-requisitos:

• Um terminal moderno (WezTerm, Alacritty, Ghostty ou Kitty recomendados)
• Chave de API de pelo menos um provider de LLM (ou use o free tier)

Verifique a instalação:

opencode --version
# 1.14.33

Primeiro Uso

Com o OpenCode instalado, o fluxo é direto:

1. Configure um provider:

opencode auth login

O comando interativo guia você pela escolha do provider e método de autenticação. Para o caminho mais rápido, use o OpenCode Zen:

# Na TUI, execute:
/connect
# Selecione "opencode", acesse opencode.ai/auth
# Faça login, adicione billing, copie a API key

Ou configure via variáveis de ambiente:

export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."
export GEMINI_API_KEY="aiza..."

2. Navegue até seu projeto e inicie:

cd /caminho/do/seu/projeto
opencode

3. Inicialize o projeto:

Na TUI, execute o comando /init. O OpenCode analisa seu repositório e cria um arquivo AGENTS.md na raiz — similar ao CLAUDE.md do Claude Code. Esse arquivo ajuda o agente a entender a estrutura, padrões e convenções do projeto.

/init

4. Comece a usar:

Agora é só conversar. Use @ para referenciar arquivos com fuzzy search:

@src/auth.ts como a autenticação funciona aqui?

[IMAGEM: Screenshot da TUI do OpenCode com uma sessão ativa mostrando o fuzzy search de arquivos]

Uso Intermediário: Plan Mode e Build Mode

O OpenCode tem dois modos fundamentais que você alterna com Tab:

Plan Mode (somente leitura): O agente lê, raciocina e propõe um plano, mas não pode modificar arquivos nem executar comandos. Ideal para:

• Code reviews
• Auditorias de arquitetura
• Exploração “e se eu fizesse X?”

Build Mode (padrão): O agente tem acesso completo a ferramentas — edita arquivos, executa comandos, cria commits.

Fluxo recomendado para features complexas:

# 1. Mude para Plan Mode (Tab)
<TAB>

# 2. Descreva o que quer
Quando um usuário deletar uma nota, quero marcar como deletada no banco.
Depois criar uma tela que mostra notas deletadas recentemente.
Dessa tela, o usuário pode restaurar ou deletar permanentemente.

# 3. Revise o plano, itere
Quero que a tela siga o design de @src/components/NoteList.tsx

# 4. Volte para Build Mode (Tab)
<TAB>

# 5. Peça para implementar
Parece bom! Faça as alterações.

Modo Headless para CI/CD

O opencode run executa o agente sem interface interativa — perfeito para automação:

# Execução one-shot
opencode run "revise o último commit para problemas de segurança" --dir /repo

# Com modelo específico
opencode run --model anthropic/claude-sonnet-4-6 "refatore src/auth" 

# Continuando sessão anterior
opencode run "agora escreva testes para a função que você adicionou" --continue

# Output em JSON para pipelines
opencode run "resuma este repo" --format json | jq -r 'select(.type=="text") | .part.text'

Para ambientes de CI totalmente automatizados (use apenas em VMs descartáveis):

opencode run "corrija os testes falhando" \
  --dangerously-skip-permissions \
  --dir /repo

Configuração Avançada

O OpenCode usa dois níveis de configuração:

1. Global: ~/.config/opencode/opencode.json
2. Por projeto: ./opencode.json (na raiz do repo)

Exemplo de configuração completa:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "anthropic/claude-haiku-4-5",
  "theme": "tokyo-night",
  "keybinds": {
    "leader": "ctrl+x",
    "session_new": "<leader>n"
  },
  "permission": [
    { "permission": "bash", "pattern": "rm -rf *", "action": "deny" },
    { "permission": "bash", "pattern": "git push --force *", "action": "deny" },
    { "permission": "bash", "pattern": "git push *", "action": "ask" },
    { "permission": "read", "pattern": "*.env", "action": "ask" },
    { "permission": "*", "pattern": "*", "action": "allow" }
  ],
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp@latest"]
    }
  },
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"]
    }
  },
  "formatter": {
    "*.py": "ruff format -",
    "*.{ts,tsx,js,jsx}": "prettier --stdin-filepath {file}"
  }
}

MCP Servers

Adicionar MCP servers é trivial:

# Filesystem
opencode mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# GitHub
GITHUB_TOKEN=ghp_... opencode mcp add github npx -y @modelcontextprotocol/server-github

# Postgres
opencode mcp add postgres npx -y @modelcontextprotocol/server-postgres "postgresql://user:pass@host:5432/db"

Custom Commands

Crie comandos personalizados como arquivos markdown em .opencode/commands/:

# .opencode/commands/test.md
---
description: Roda testes e corrige falhas
agent: build
model: anthropic/claude-sonnet-4-6
---

Rode a suite de testes, identifique falhas e corrija.
Output dos testes:
!`npm test`

Arquivos de teste recentes:
@tests/

Foco em: $ARGUMENTS

Depois, na TUI:

/test src/auth/

Deep Dive

Arquitetura: Como o OpenCode Funciona

O OpenCode roda sobre uma arquitetura cliente-servidor local. Mesmo quando você usa a TUI, por baixo existe um servidor HTTP que gerencia sessões, ferramentas e comunicação com providers.

Isso habilita cenários poderosos:

# Rode um servidor headless
opencode serve --port 4096 --hostname 0.0.0.0

# Conecte de outra máquina
opencode attach http://10.0.1.10:4096 --password "$PW"

# Ou abra no browser
opencode web --port 4096

Com tmux ou systemd, você mantém um servidor OpenCode rodando no seu homelab e conecta de qualquer laptop na rede.

LSP Integration

O OpenCode integra com Language Server Protocol para dar ao LLM feedback em tempo real sobre seu código:

{
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"]
    },
    "python": {
      "command": ["pyright-langserver", "--stdio"]
    }
  }
}

Com LSP habilitado, o agente recebe diagnósticos (erros, warnings) automaticamente — sem precisar rodar o build manualmente para descobrir problemas. Isso acelera significativamente o ciclo de correção.

[IMAGEM: Diagrama mostrando o fluxo OpenCode → LSP → Diagnósticos → LLM → Correção]

Multi-Session e Multi-Agent

O OpenCode suporta múltiplas sessões em paralelo no mesmo projeto. Cada sessão é independente, com seu próprio contexto e histórico.

Além disso, o sistema de agents permite criar roles especializados:

opencode agent create \
  --description "revisor de Terraform read-only" \
  --mode primary \
  --permissions "bash,read,grep,glob,webfetch,task" \
  --model anthropic/claude-sonnet-4-6 \
  --path .opencode/agents/tf-reviewer.md

Agents built-in:

• build: agente padrão com acesso completo (sujeito a permissões)
• compaction: resume e compacta sessões longas
• explore: investigador read-only, sem risco de edições

Workflow multi-agente em produção:

Um padrão comum usa pipeline de agentes especializados:

1. @check — revisor de design (read-only), identifica riscos
2. @simplify — revisor de complexidade, flagra overengineering
3. @test — autor de testes TDD, só escreve arquivos de teste
4. @make — implementador sandboxed, faz RED → GREEN

Sessions: Compartilhar, Exportar, Forkar

# Listar sessões recentes
opencode session list -n 10

# Continuar última sessão
opencode -c

# Forkar antes de continuar (preserva original)
opencode -c --fork

# Compartilhar via URL pública
opencode --share -m anthropic/claude-sonnet-4-6 --prompt "explique o fluxo de auth"

# Exportar sessão completa
opencode export ses_abc123 > session.json

# Importar em outra máquina
opencode import session.json

Sistema de Permissões

O OpenCode tem um engine de permissões granular que avalia regras top-to-bottom (first match wins):

Categorias de permissão:

• bash <pattern> — comandos shell
• read <glob> — leitura de arquivos
• edit <glob> — escrita de arquivos
• external_directory <path> — escrita fora do projeto
• doom_loop — guard contra loops infinitos

GitHub Agent

O OpenCode inclui um agente GitHub nativo que reage a menções /opencode em comentários de PR:

# Instalar (cria .github/workflows/opencode.yml)
opencode github install

# Testar localmente
opencode github run

# Puxar um PR e abrir OpenCode nele
opencode pr 1234

Compatibilidade com Outros Agentes

O OpenCode lê automaticamente:

• AGENTS.md (próprio)
• CLAUDE.md e .claude/skills (Claude Code)
• GEMINI.md (Gemini)

Isso significa que se você já usa Claude Code e tem um CLAUDE.md configurado, o OpenCode aproveita esse contexto sem configuração adicional. Você pode desabilitar essa leitura seletivamente:

OPENCODE_DISABLE_CLAUDE_CODE=1            # ignora .claude inteiro
OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1     # ignora ~/.claude/CLAUDE.md
OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1     # ignora .claude/skills

Essa interoperabilidade é um diferencial estratégico: você pode migrar gradualmente de outro agente para o OpenCode sem perder o contexto que já construiu.

Desktop App: TUI vs Desktop

O Desktop App (beta) está disponível para macOS, Windows e Linux. Quando usar cada um:

O Desktop App oferece a mesma funcionalidade da TUI com uma interface gráfica nativa. A TUI continua sendo a interface mais poderosa — com 60+ atalhos de teclado e integração profunda com o terminal.

Tracking de Custos

O OpenCode rastreia automaticamente tokens e custos por sessão, modelo e período:

# Últimos 7 dias
opencode stats --days 7

# Breakdown por modelo
opencode stats --models

# Filtrar por projeto
opencode stats --project meu-projeto

Output real:

┌────────────────────────────────────────────────────────┐
│                    COST & TOKENS                       │
├────────────────────────────────────────────────────────┤
│Total Cost                                        $0.01 │
│Avg Cost/Day                                      $0.00 │
│Avg Tokens/Session                                11.2K │
│Input                                                 2 │
│Output                                               34 │
│Cache Read                                            0 │
│Cache Write                                       11.1K │
└────────────────────────────────────────────────────────┘

Cada execução headless (opencode run --format json) também retorna custo no evento step_finish, permitindo integrar com dashboards de custo da sua equipe.

Skills e Plugins

O OpenCode suporta skills (bundles de capacidade reutilizáveis) e plugins (extensões npm):

# Instalar plugin
opencode plugin some-opencode-plugin

# Instalar globalmente
opencode plugin some-opencode-plugin --global

A comunidade Oh-My-OpenAgent oferece um gerenciador de plugins com agents, temas e skill bundles pré-construídos.

Se você trabalha com skills para agentes de codificação, vale conhecer o skilldev.pro — um marketplace dedicado a skills que funcionam com OpenCode e outros agentes.

Avaliação: Spider Chart

Notas de 1 a 10 baseadas em benchmarks públicos + avaliação prática.

Média geral: 7.0/10

Metodologia: Código baseia-se em SWE-bench Verified + Aider Polyglot (aplicados ao modelo, não à ferramenta). Autonomia em Terminal-Bench + avaliação prática. Demais eixos são avaliação prática comparativa com Claude Code, Cursor, Copilot e Codex como referência. Escala: 1-4 (fraco), 5-6 (adequado), 7-8 (bom), 9-10 (excelente/líder).

[IMAGEM: Spider chart radar com 8 eixos mostrando as notas do OpenCode]

Prós e Contras

Prós

• Agnóstico de provider — 75+ providers, sem vendor lock-in. Troque de modelo com uma flag (-m provider/model). Use Claude hoje, DeepSeek amanhã, Ollama local quando quiser privacidade total.

• Open-source de verdade — Licença MIT, 160K+ stars, 900+ contributors. Você pode auditar o código, contribuir, ou forkar. Nenhum dado seu é armazenado pelos servidores do OpenCode.

• Arquitetura server-mode — Rode um servidor persistente e conecte de múltiplas máquinas. Perfeito para homelabs, equipes, e cenários enterprise.

• Multi-agent nativo — Crie pipelines de agentes especializados com permissões granulares. Revisores read-only, implementadores sandboxed, PMs com acesso a ferramentas específicas.

• Ecossistema rico — MCP servers, custom commands, plugins, skills, LSP integration, GitHub agent, ACP para IDEs. A superfície de extensibilidade é enorme.

• Custo flexível — Do free tier ao BYOK, passando pelo Go a $10/mês. Você controla exatamente quanto gasta.

• Headless para CI/CD — opencode run com output JSON é perfeito para automação, pipelines e integração com outras ferramentas.

Contras

• Curva de aprendizado — 18 comandos CLI, 60+ atalhos, sistema de permissões, agents, modes, skills… a superfície é grande. Leva tempo para dominar.

• Terminal moderno obrigatório — Precisa de WezTerm, Alacritty, Ghostty ou Kitty. Terminais básicos (Terminal.app do macOS, cmd do Windows) não renderizam a TUI corretamente.

• Desktop App ainda em beta — Funcional, mas menos polido que a TUI. Se você não é pessoa de terminal, a experiência ainda não é ideal.

• Dependência de Bun — O runtime usa Bun internamente, que requer suporte a AVX2 na CPU. VMs com CPU genérica podem ter problemas.

• Qualidade depende do modelo — Como é agnóstico de provider, a experiência varia drasticamente conforme o modelo escolhido. Modelos baratos/gratuitos podem frustrar em tarefas complexas.

• Documentação fragmentada — A docs oficial é boa, mas features avançadas (multi-agent, custom commands, plugins) exigem exploração no GitHub e comunidade.

Veredicto

OpenCode é ideal para:

• Desenvolvedores que querem liberdade total de escolha de modelo
• Quem já usa o terminal como ambiente principal de trabalho
• Equipes que precisam de self-hosting e controle de dados
• Power users que querem customizar cada aspecto do agente
• Cenários de CI/CD e automação com agentes

OpenCode NÃO é ideal para:

• Quem quer experiência plug-and-play sem configuração
• Desenvolvedores que preferem interface gráfica e não usam terminal
• Quem quer a melhor experiência possível com um único modelo (nesse caso, Claude Code para Anthropic ou Cursor para multi-modelo com GUI)

O OpenCode é o canivete suíço dos agentes de codificação. A flexibilidade é incomparável — mas flexibilidade vem com complexidade. Se você valoriza controle, transparência e liberdade de escolha acima de conveniência imediata, o OpenCode é provavelmente a melhor opção open-source disponível em 2026.

Versão testada: OpenCode 1.14.33 (maio 2026). Dados de preço e features podem mudar — consulte opencode.ai para informações atualizadas.