# Guia Definitivo: OpenCode

> OpenCode é o agente de codificação open-source que roda no terminal, desktop e IDE com suporte a 75+ providers. Guia completo.

Source: https://agentify.ia.br/blog/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:

 Interface Descrição TUI Interface de terminal interativa (principal) CLI headless Execução one-shot para CI/CD e scripts Desktop App App nativo para macOS, Windows e Linux (beta) IDE Extension Extensão via ACP (Agent Client Protocol) Web UI Interface browser via opencode web

### Preço

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

 Opção Custo O que inclui Free tier $0 Modelos gratuitos hospedados pelo OpenCode (Big Pickle, modelos experimentais) OpenCode Go $5 primeiro mês, depois $10/mês Acesso a modelos open-source de ponta (DeepSeek V4, Qwen 3.6, Kimi K2.6, MiniMax M2.7) OpenCode Zen Pay-per-request Modelos curados e testados pela equipe, cobrança por uso BYOK (Bring Your Own Key) Custo da API do provider Use sua própria chave de qualquer provider

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

- **Global**: `~/.config/opencode/opencode.json`

- **Por projeto**: `./opencode.json` (na raiz do repo)

Exemplo de configuração completa:

```server
{
 "$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 --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
```

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:

```server
{
 "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:

- **@check** — revisor de design (read-only), identifica riscos

- **@simplify** — revisor de complexidade, flagra overengineering

- **@test** — autor de testes TDD, só escreve arquivos de teste

- **@make** — implementador sandboxed, faz RED → GREEN

### Sessions: Compartilhar, Exportar, Forkar

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

# 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):

 Ação Comportamento allow Aprovação silenciosa ask Pede confirmação ao usuário deny Bloqueia silenciosamente

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

### 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= # ignora .claude inteiro
OPENCODE_DISABLE_CLAUDE_CODE_PROMPT= # ignora ~/.claude/CLAUDE.md
OPENCODE_DISABLE_CLAUDE_CODE_SKILLS= # 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:

 Cenário Recomendação Desenvolvimento diário, SSH, servidores TUI Quem prefere interface gráfica Desktop CI/CD, automação, scripts CLI headless Acesso remoto de múltiplas máquinas Server + Attach Integração com editor existente IDE Extension (ACP)

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

# 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](https://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.

 Eixo Nota Justificativa Código (qualidade) 7/10 Depende do provider escolhido (75+). Com Claude Opus 4.7 ou GPT-5 atinge nível top-tier, mas a ferramenta em si não tem benchmark próprio — qualidade varia drasticamente conforme o modelo Contexto (compreensão) 7/10 LSP integration fornece diagnósticos em tempo real, file awareness via @mentions com fuzzy search. Porém sem indexação profunda de codebase como Cursor ou Antigravity Autonomia 7/10 Modo headless com opencode run , execução autônoma completa, --dangerously-skip-permissions para CI. Menos refinado que Claude Code (Terminal-Bench 68.5%) mas funcional Velocidade 8/10 Binary Go/Bun rápido, TUI responsiva com 60+ atalhos. Latência depende do provider, mas overhead local é mínimo. Multi-session paralelo acelera workflows Custo-benefício 9/10 Open-source gratuito (MIT), free tier incluso, OpenCode Go a $10/mês com modelos de ponta, BYOK para controle total. Melhor relação custo/flexibilidade do mercado Especialização (skills) 6/10 AGENTS.md + custom commands em markdown + compatibilidade com CLAUDE.md/GEMINI.md. Sistema funcional mas menos maduro que .cursorrules ou steering files do Kiro Multi-agente 5/10 Sem multi-agente nativo — requer plugins como Oh-My-OpenCode para orquestração. Multi-session paralelo existe, mas cada sessão é independente sem coordenação Ecossistema 7/10 160K+ stars, 900+ contributors, 75+ providers, MCP servers, plugins, GitHub agent, ACP para IDEs, comunidade ativa. Ecossistema jovem mas crescendo rapidamente

**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](https://opencode.ai) para informações atualizadas.*

-->