OpenCode: um Agente de IA no Terminal

O OpenCode é um agente de IA open-source que lê, escreve e refatora código sem saíres da linha de comandos. Escolhes tu o modelo e decides o que ele pode fazer.

Um assistente que lê o teu projeto, corre comandos e propõe alterações, tudo dentro do terminal. É isso que o OpenCode tenta ser.

O OpenCode é um agente de programação open-source (licença MIT), escrito em TypeScript, que corre no teu Mac e se liga aos modelos que preferires — Claude, GPT, Gemini e muitos outros (a documentação fala em mais de 75 providers).

O ecossistema OpenCode: CLI central com conexão a providers, agents, skills e servidores MCP

O que é o OpenCode?

O OpenCode é um agente de IA open-source para programadores. Pensa nele como um pair programmer que vive no teu terminal. É um projeto independente (não é um fork do Claude Code, que é proprietário), desenvolvido pela Anomaly, a equipa por trás do SST, e está disponível em opencode.ai como interface de terminal, aplicação de secretária e extensão para IDE.

Ao contrário de um simples autocomplete, o OpenCode é um agente: não se limita a sugerir código. Ele analisa a tua base de código, planeia alterações, executa comandos, lê ficheiros, escreve código, faz commits e até abre PRs.

O OpenCode corre no terminal e funciona nos terminais modernos — Terminal.app, iTerm2, WezTerm, Alacritty, Kitty, Ghostty, etc.

Não confundir: existe outro projeto com o mesmo nome, o opencode-ai/opencode, escrito em Go. Foi arquivado e continuou como o Crush, da Charm. Este guia é sobre o OpenCode da Anomaly (opencode.ai).

Instalação no macOS

Antes de começares, precisas de:

• Um Mac com macOS atual — funciona em Apple Silicon e Intel
• Homebrew recomendado — brew instalado e atualizado
• Terminal moderno — WezTerm, Ghostty, iTerm2 ou Terminal.app
• API keys — pelo menos uma conta num provider de LLM (Anthropic, OpenAI, etc.)

Método 1: Homebrew (recomendado)

Usa o tap oficial do OpenCode:

brew install anomalyco/tap/opencode

Existe também a fórmula oficial mantida pela equipa do Homebrew, mas é atualizada com menos frequência:

brew install opencode

Método 2: Script de instalação (curl)

Se preferires o binário mais recente diretamente do GitHub:

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

Método 3: NPM / Bun / pnpm

# Com npm
npm install -g opencode-ai

# Com bun
bun install -g opencode-ai

Verificar a instalação

opencode --version

Deves ver algo como 1.18.35 (a versão depende de quando lês isto).

Configurar API Keys

O OpenCode precisa de pelo menos uma API key para funcionar. A forma mais direta é usar variáveis de ambiente no teu ~/.zshrc:

# Adiciona ao ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."

# Ou para OpenAI
export OPENAI_API_KEY="sk-proj-..."

# Ou para Google Gemini
export GEMINI_API_KEY="AIza..."

Para recarregar sem reiniciar o terminal:

source ~/.zshrc

Dica: Se és novo nisto, usa o comando /connect dentro do OpenCode ou opencode auth login para configurares os providers de forma interativa. As chaves ficam guardadas em ~/.local/share/opencode/auth.json, fora dos teus projetos.

Sessão OpenCode ao vivo — interação com o agente a implementar autenticação

Primeiros Passos — O Workflow

Abrir o OpenCode

Navega até ao teu projeto e corre:

cd /caminho/do/projeto
opencode

O OpenCode arranca automaticamente. Na primeira vez, recomendo correr /init para ele analisar o projeto e criar um ficheiro AGENTS.md na raiz. Este ficheiro ajuda o OpenCode a perceber a estrutura do projeto, as convenções de código e os padrões que usas.

Dica: Faz commit do AGENTS.md para o repositório — a equipa toda beneficia do contexto partilhado.

Como interagir

O OpenCode funciona como um chat no terminal. Escreves uma mensagem, ele processa e responde com texto, código, ou ações. As ferramentas que ele pode usar incluem:

Uma das funcionalidades mais úteis é o modo Plan. Carrega na tecla Tab para alternar entre o modo Build (faz alterações) e Plan (só analisa). Isto é excelente para pedires uma análise antes de autorizares qualquer modificação.

# Exemplo de interação no modo Plan
Tu: Precisamos de adicionar um sistema de cache à API.
     Podes fazer um plano primeiro?

OpenCode (Plan): Claro! Aqui está o que proponho:
  1. Criar um módulo src/lib/cache.ts com Redis
  2. Adicionar middleware de cache nas rotas GET
  3. Configurar TTL de 60s para listagens
  4. Invalidar cache em mutações

   (sem alterações — estou em modo Plan)

# Agora carrega Tab para mudar para Build

Tu: Parece bem. Avança com a implementação.

OpenCode (Build):  Cache implementada.
  • 3 ficheiros alterados
  • Testes passam
  • Queres que faça commit? (yes/no)

Abreviatura @ para ficheiros

Usa o símbolo @ para pesquisar ficheiros no projeto com fuzzy search. Isto é especialmente útil para dares contexto preciso ao modelo:

Como é feita a autenticação em @src/middleware/auth.ts?
Implementa o mesmo padrão em @src/middleware/admin.ts

Ciclo de desenvolvimento com OpenCode: discutir, implementar, rever, commitar

Configuração Avançada — opencode.json

O OpenCode é altamente configurável através de ficheiros JSON (ou JSONC). Podes ter configuração global em ~/.config/opencode/opencode.json e configurações por projeto num opencode.json na raiz do projeto.

Os ficheiros são fundidos (merged), não substituídos. Isto significa que podes ter definições globais (como API keys) e refiná-las por projeto (como modelo ou agentes).

Ordem de precedência (do menos prioritário ao mais):

1. Config remota (via .well-known/opencode)
2. Config global (~/.config/opencode/opencode.json)
3. Caminho personalizado (variável de ambiente OPENCODE_CONFIG)
4. Config do projeto (opencode.json na raiz)
5. Pastas .opencode (agents, commands, plugins)
6. Config inline (variável de ambiente OPENCODE_CONFIG_CONTENT)
7. Ficheiros de configuração geridos (por exemplo, /etc/opencode/ no Linux)
8. Definições geridas por MDM (macOS managed preferences), com a prioridade mais alta

Exemplo de ficheiro opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

A chave não fica escrita no ficheiro: {env:ANTHROPIC_API_KEY} lê-a da variável de ambiente (também podes usar {file:...}). O small_model é usado em tarefas leves, como gerar títulos. Com "ask", o OpenCode pede confirmação antes de editar ficheiros ou correr comandos. O autoupdate não funciona em instalações feitas por gestores de pacotes, como o Homebrew.

Providers personalizados

Além dos providers que já vêm de origem (Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure, entre outros), podes adicionar qualquer API compatível com OpenAI. Primeiro corre /connect, escolhe Other e indica o ID do provider e a chave; depois declara-o no opencode.json com o mesmo ID:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "meuprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Nome do meu provider",
      "options": {
        "baseURL": "https://api.meuprovider.com/v1"
      },
      "models": {
        "nome-do-modelo": {
          "name": "Nome do modelo"
        }
      }
    }
  }
}

Usa @ai-sdk/openai-compatible para endpoints /v1/chat/completions (se o modelo usar /v1/responses, usa @ai-sdk/openai). Depois corre /models para escolher o novo modelo.

Sabias? Podes usar opencode models para listar todos os modelos disponíveis nos teus providers configurados. Usa opencode models --refresh para atualizar a cache.

Agentes OpenCode — O Pilar do Sistema

Os agentes são uma das peças centrais do OpenCode. Em vez de um único assistente genérico, tens vários assistentes especializados, cada um com o seu propósito, modelo e permissões.

Agentes Built-in

Para alternar entre agentes primary, carrega na tecla Tab durante uma sessão. Para invocar subagents, usa a menção @ na tua mensagem:

# Invocar subagent Explore
@explore encontra todas as funções que usam o padrão Observer

# Invocar subagent General para uma tarefa complexa
@general analisa a performance da função de busca e sugere otimizações

Hierarquia de agentes no OpenCode: primary agents, subagents built-in, e agentes personalizados

Criar Agentes Personalizados

Podes criar os teus próprios agentes de duas formas:

Via JSON (no opencode.json):

{
  "agent": {
    "bookwriter": {
      "description": "Escreve artigos técnicos e newsletters em Português",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.7,
      "prompt": "{file:./prompts/bookwriter.txt}",
      "permission": {
        "read": "allow",
        "write": "allow",
        "edit": "allow",
        "bash": "deny",
        "webfetch": "allow"
      }
    },
    "oracle": {
      "description": "Revisor de código. Foco em segurança, performance e manutenibilidade",
      "mode": "subagent",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Via Markdown (ficheiro .md):

Cria um ficheiro em ~/.config/opencode/agents/ ou .opencode/agents/. O nome do ficheiro (sem extensão) torna-se o nome do agente:

---
description: Revisor de código especializado em SQL e bases de dados
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  bash: deny
  grep: allow
---

És um revisor de SQL e esquemas de base de dados.
Foco-te em:

- Índices em falta e queries lentas
- Normalização vs denormalização
- Deadlocks e locking
- Segurança (SQL injection, RBAC)

Fornece feedback construtivo sem fazer alterações ao código.

Skills e Plugins

As skills são bundles de instruções + scripts que estendem as capacidades do OpenCode. Podes instalar skills pré-definidas ou criar as tuas.

Skills prontas a usar

O OpenCode não tem um comando para instalar skills: uma skill é só uma pasta com um ficheiro SKILL.md. Podes escrevê-las tu, copiá-las de repositórios de skills, ou instalar um plugin que as traga já feitas. O oh-my-opencode-slim, por exemplo, inclui estas:

Criar uma Skill personalizada

A estrutura de uma skill é simples. Cria uma pasta em .opencode/skills/<nome-da-skill>/ com um ficheiro SKILL.md, que tem de começar por um cabeçalho com o name (igual ao nome da pasta) e uma description:

.opencode/skills/meu-revisor/
├── SKILL.md         # instruções + metadados
└── scripts/
    └── lint.py      # scripts auxiliares (opcional)

---
name: meu-revisor
description: Revê código TypeScript à procura de erros de tipos e padrões que podem causar erros em execução
---
# Meu Revisor Personalizado

Revê código TypeScript à procura de:
- Erros comuns de types
- Padrões que podem causar runtime errors
- Oportunidades de refatoração

## Uso
Quando o developer pedir "revê este código", analisa-o segundo os critérios acima.

O OpenCode procura skills em .opencode/skills/ (no projeto) e em ~/.config/opencode/skills/ (globais), e também em .claude/skills/ e .agents/skills/, por compatibilidade. Carrega-as quando são precisas, através da ferramenta skill.

Comandos Essenciais do Dia-a-Dia

O OpenCode tem comandos de terminal (CLI) e comandos internos (TUI). Aqui estão os que uso todos os dias:

Comandos CLI

Comandos Internos (TUI) e Atalhos

A maior parte dos atalhos usa ctrl+x como tecla líder: carregas em ctrl+x e depois na letra.

Importante: O comando /undo pode ser usado múltiplas vezes para reverter várias alterações. É uma rede de segurança excelente quando o modelo faz algo inesperado.

Dicas e Boas Práticas

1. Regras Persistentes com AGENTS.md

Cria um ficheiro AGENTS.md na raiz do projeto (o /init cria um por ti). O OpenCode lê-o e junta-o às instruções de todas as sessões desse projeto; se não existir, usa o CLAUDE.md. Para regras que valem em todos os projetos, usa o ~/.config/opencode/AGENTS.md. É o sítio ideal para:

• Convenções de código específicas do projeto
• Preferências de estilo (ex: "usa tabs, não spaces")
• Informação sobre a arquitetura
• Lista de comandos de build/test frequentemente usados

# AGENTS.md — Regras persistentes para este projeto

## Stack
- TypeScript + React (Next.js 15)
- Drizzle ORM + PostgreSQL
- Tailwind CSS para estilos

## Convenções
- Nomes de ficheiros em kebab-case
- Componentes React com arrow functions
- Testes com Vitest, ao lado do ficheiro (component.spec.tsx)
- Commits seguem Conventional Commits (feat, fix, chore, docs...)

## Comandos
- Build: npm run build
- Test: npm run test
- Dev: npm run dev (porta 3000)
- DB migrate: npm run db:migrate

2. Controlo de Custos

O OpenCode pode gastar muitos tokens se não tiveres cuidado. Algumas dicas:

• Usa modelos mais pequenos para tarefas simples: um modelo da família Haiku ou um modelo "mini" chega para refactoring rápido
• Usa opencode stats para veres o consumo de tokens e custos por sessão
• Modo Plan primeiro antes de Build — evita gastar tokens em alterações erradas
• Auto-compact ativado por defeito — o OpenCode resume automaticamente conversas longas

3. Tarefas Longas

Para tarefas complexas, descreve o objetivo completo numa só mensagem. Se quiseres validar a abordagem antes, começa no modo Plan e muda para Build quando concordares com o plano:

Refatora o módulo de autenticação: extrai a lógica de
verificação de tokens para um serviço separado, adiciona testes
unitários, e atualiza os imports em todo o projeto

O agente trabalha em vários passos até concluir (ou até precisar de uma decisão tua). Quando o contexto enche, o OpenCode compacta a conversa automaticamente.

4. Git Integrado

O OpenCode usa o git (e o gh) através da ferramenta bash. Podes pedir-lhe para:

• Fazer commits com mensagens descritivas (e no formato que preferires)
• Criar PRs no GitHub (precisa de gh CLI configurado)
• Rever alterações antes de fazer stage
• Gerir branches — criar, merge, rebase

# Exemplo de workflow git com OpenCode
Tu: Faz commit das alterações com mensagem conventional commit

OpenCode: git diff a analisar...
  ...
   Alterações detetadas em 3 ficheiros:
    • src/auth/service.ts (refactor)
    • src/auth/spec.ts (new tests)
    • src/utils/tokens.ts (new file)

   Proposta de commit:
  feat(auth): extrair verificação de tokens para serviço dedicado

  - Cria src/utils/tokens.ts com lógica de verificação
  - Adiciona testes unitários em src/auth/spec.ts
  - Atualiza imports no módulo de autenticação

  Confirmas? (yes/no):

5. Sessões e Contexto

• Mantém sessões focadas — uma tarefa de cada vez. O auto-compact ajuda, mas mudar de contexto é mais eficiente.
• Usa /new (ou ctrl+x n) para criar uma nova sessão quando mudas de tarefa.
• Partilha sessões com /share para pedires feedback à equipa.
• Arrasta imagens para o terminal — o OpenCode consegue analisar screenshots e mockups.

Dica de produtividade: Cria custom commands para operações frequentes. Guarda ficheiros .md em ~/.config/opencode/commands/ com prompts pré-definidos. Ex: um prime-context.md, que invocas com /prime-context, para analisar a codebase antes de começar.

Conclusão

O OpenCode é uma boa opção para quem vive no terminal e quer escolher o modelo que usa. Junta um agente de IA open-source a um sistema extensível de agents, skills e plugins.

Vantagens:

• Terminal em primeiro lugar — a interface principal é a TUI, que corre em qualquer lado onde haja um terminal (também há aplicação de secretária e extensão para IDE)
• Múltiplos providers — não ficas preso a um modelo ou vendor. Usa Claude, GPT, Gemini, ou o que preferires
• Agentes especializados — cada tarefa com o assistente certo. Plan para análise, Build para executar, subagents para tarefas específicas
• Extensível — skills, plugins, MCP servers, custom commands. Adaptas o OpenCode ao teu workflow, não o contrário
• Open-source — código aberto (MIT), comunidade ativa, sem vendor lock-in
• Git e GitHub no terminal — commits e PRs através do git e do gh, sem mudar de contexto

Limitações honestas:

• Curva de aprendizagem — não é tão imediato como um autocomplete do Copilot. Leva algum tempo até estares confortável com atalhos, agentes e configuração
• Custo de tokens — os modelos maiores (Claude Sonnet, GPT, etc.) gastam tokens rapidamente. Precisas de gerir o orçamento
• Dependência de API — embora corra localmente, precisa de ligação aos providers, a não ser que uses um modelo local. Se a API estiver em baixo, o OpenCode não funciona
• Ainda em evolução — é um projeto ativo, com alterações frequentes. Algumas funcionalidades podem mudar entre versões

Se és developer no macOS e passas tempo no terminal, o OpenCode merece um lugar no teu toolkit. Instala hoje, experimenta com um projeto pequeno, e vê como ele se encaixa no teu fluxo de trabalho.

E já agora: este artigo foi escrito com a ajuda do agente bookwriter do OpenCode. Sim, estou a usar a ferramenta para falar sobre ela própria — meta suficiente para ti?

Recursos

• Site oficial do OpenCode
• Código fonte no GitHub (anomalyco)
• Documentação oficial
• Configuração (opencode.json)
• Guia de Agentes
• CLI e comandos
• Comunidade Discord do OpenCode