OpenCode: O Terminal com Superpoderes de IA

Transforma o teu terminal num verdadeiro engenheiro de software. O OpenCode é um agente de IA open-source que lê, escreve e refatora código: tudo sem sair da linha de comandos. E o melhor: és tu que controlas tudo.

Já imaginaste ter um par de programação sénior disponível 24/7, diretamente no teu terminal? Um que conhece a tua base de código, respeita o teu estilo de programação, e nunca se cansa de fazer code reviews?

O OpenCode é isso mesmo. Um fork open-source do Claude Code da Anthropic, construído em Go, que corre nativamente no teu Mac e se integra com os modelos de linguagem que preferires: Claude, GPT, Gemini, e dezenas de outros.

Vou mostrar-te tudo:

• Instalação no macOS Apple Silicon (e Intel)
• Configuração de providers e API keys
• Workflow diário: como interagir com o OpenCode
• Agentes personalizados: o sistema que torna o OpenCode único
• Plugins, Skills e MCP: a arquitetura extensível
• Dicas e boas práticas para tirares o máximo partido

⬆ 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. Foi originalmente baseado no Claude Code da Anthropic, mas evoluiu como projeto independente sob a alçada da Anomaly, disponível em opencode.ai.

Ao contrário de ferramentas como o Cline (extensão do VS Code) ou o GitHub Copilot (autocomplete), o OpenCode é agentic: 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 é escrito em Go e usa a Bubble Tea (da Charm) para a interface TUI. Isto significa que é rápido, leve e funciona em qualquer terminal moderno: Terminal.app, iTerm2, WezTerm, Alacritty, Kitty, Ghostty, etc.

Instalação no macOS

Antes de começares, precisas de:

• macOS 14+ (Sonoma/Sequoia): 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 opencode v0.1.48 (a versão atual 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. O OpenCode também lê um ficheiro .env se existir no diretório do projeto.

⬆ 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. Custom path (OPENCODE_CONFIG env var)
4. Config do projeto (opencode.json na raiz)
5. Config inline (OPENCODE_CONFIG_CONTENT env var)
6. Definições geridas por MDM (macOS managed preferences)

Exemplo de ficheiro opencode.json

{
  "provider": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "options": {
        "timeout": 600000
      }
    },
    "openai": {
      "apiKey": "sk-proj-..."
    },
    "openrouter": {
      "apiKey": "sk-or-..."
    }
  },
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-4-20250514",
  "autoupdate": true,
  "agent": {
    "build": {
      "mode": "primary",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    }
  }
}

Providers personalizados

Além dos providers oficiais (Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure), podes adicionar qualquer API compatível com OpenAI:

{
  "provider": {
    "openai": {
      "apiKey": "sk-..."
    },
    "anthropic": {
      "apiKey": "sk-ant-...",
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    },
    "openrouter": {
      "apiKey": "sk-or-..."
    }
  }
}

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 o que torna o OpenCode verdadeiramente poderoso. Em vez de um único assistente genérico, tens um ecossistema de 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-20250514",
      "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-20250514
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 disponíveis

Criar uma Skill personalizada

A estrutura de uma skill é simples. Cria uma pasta em .opencode/skills/<nome-da-skill>/ com um ficheiro SKILL.md:

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

# SKILL.md
# Meu Revisor Personalizado

Revisa 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 "revisa este código", analisa-o segundo os critérios acima.

As skills instaladas ficam em .opencode/skills/ no diretório do projeto. Podes ver o conteúdo de qualquer skill instalada nessa pasta.

Dica: A skill agent-browser é especialmente útil: permite ao OpenCode interagir com páginas web, preencher formulários, e fazer screenshots. Ideal para testar aplicações web ou extrair dados de sites.

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

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 .opencode/rules

Cria um ficheiro .opencode/rules no teu projeto. O conteúdo é injetado no system prompt de todas as sessões desse projeto. É 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

# .opencode/rules — 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: claude-haiku ou gpt-4o-mini para refactoring rápido
• Define maxTokens por request: limita a resposta do modelo
• 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. auto_continue para Tarefas Longas

Para tarefas complexas que exigem múltiplas iterações do modelo, ativa a continuação automática:

/task "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 OpenCode continua automaticamente até completar a tarefa. Se atingir o limite de tokens, faz auto-compact e continua.

4. Git Integrado

O OpenCode tem integração nativa com git. 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 Ctrl+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: user:prime-context para analisar a codebase antes de começar.

Conclusão

O OpenCode é, neste momento, uma das ferramentas mais poderosas para programadores que vivem no terminal. Combina a flexibilidade de um agente de IA open-source com a potência de um sistema de agents, skills, e plugins extensível.

Vantagens:

• 100% terminal: sem GUI, sem Electron, sem distrações. Corre em qualquer lado onde haja um terminal
• 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, comunidade ativa, sem vendor lock-in
• Git integrado: commits, PRs, tudo pelo terminal 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: modelos poderosos (Claude Sonnet, GPT-4o) gastam tokens rapidamente. Precisas de gerir o orçamento
• Dependência de API: embora corra localmente, precisa de conexão aos providers. 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
• Bubble Tea: framework TUI
• Comunidade Discord do OpenCode