> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dados.rio/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode - Guia do Usuário

> Como instalar, configurar e usar o OpenCode com Bifrost na IplanRio

O OpenCode é um agente de IA no terminal que lê o contexto do seu repositório e executa tarefas de desenvolvimento de ponta a ponta — escreve, edita, testa e refatora código com base em instruções em linguagem natural.

Na IplanRio, o OpenCode é configurado via **Bifrost**, nosso proxy centralizado de IA. Você não gerencia credenciais de cloud: basta sua Virtual Key.

***

## Como Solicitar Acesso

1. Acesse o canal **`#peça-permissão`** no Discord da IplanRio
2. Envie sua solicitação:

```
🤖 Solicitação de Acesso - OpenCode

Nome: [Seu nome completo]
Email: [seu.email@prefeitura.rio]
Área/Projeto: [Ex: Escritório de Dados, SMS, etc.]
Justificativa: [Para que você pretende usar]
```

3. Aguarde aprovação da equipe de IA
4. Receba por email sua **Virtual Key** e os comandos de instalação

***

## Limites de Uso

O acesso ao Bifrost é compartilhado e possui **limites diários de tokens por Virtual Key**. Ao atingir o limite, as requisições retornam erro até a renovação automática no dia seguinte.

Se precisar de mais cota antes da renovação, solicite no canal **`#peça-permissão`** do Discord da IplanRio informando sua necessidade.

<Warning>
  Use modelos mais leves para tarefas simples — isso preserva cota para quando você precisar de mais capacidade.
</Warning>

***

## Instalação Automática

<Tabs>
  <Tab title="Linux / macOS / WSL">
    ```bash theme={null}
    curl -fsSL https://storage.googleapis.com/iplanrio-opencode/install.sh | bash -s -- [sua-virtual-key]
    ```

    O script detecta seu sistema, instala o OpenCode e cria `~/.config/opencode/config.json` com o Bifrost configurado.
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    & ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/install.ps1'))) -VirtualKey '[sua-virtual-key]'
    ```

    Instala o binário em `%LOCALAPPDATA%\Programs\opencode` e cria `%APPDATA%\opencode\config.json`.
  </Tab>
</Tabs>

<Info>
  A Virtual Key é pessoal e intransferível. Re-executar o script atualiza providers e modelos preservando todas as outras configurações existentes.
</Info>

### Atualizar a configuração

Re-execute o script a qualquer momento para aplicar novos providers ou modelos. A Virtual Key existente é reutilizada automaticamente — não é obrigatório passá-la novamente. Mesmo assim, passe-a explicitamente para evitar ambiguidades:

<Tabs>
  <Tab title="Linux / macOS / WSL">
    ```bash theme={null}
    # Sem a chave — usa a chave já configurada
    curl -fsSL https://storage.googleapis.com/iplanrio-opencode/install.sh | bash

    # Recomendado: passe a chave explicitamente
    curl -fsSL https://storage.googleapis.com/iplanrio-opencode/install.sh | bash -s -- [sua-virtual-key]
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    # Sem a chave — usa a chave já configurada
    & ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/install.ps1')))

    # Recomendado: passe a chave explicitamente
    & ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/install.ps1'))) -VirtualKey '[sua-virtual-key]'
    ```
  </Tab>
</Tabs>

***

## Migrando do Claude Code

Quem usou o **Claude Code** antes do OpenCode recebeu uma chave de service account do GCP e variáveis de ambiente apontando direto para o Google Vertex AI. A IplanRio removeu essas service accounts na migração para o Bifrost, e a chave órfã agora gera o erro:

```
invalid_grant: Invalid grant: account not found
```

O OpenCode usa apenas o `config.json` + Virtual Key. As variáveis antigas só atrapalham e precisam ser removidas.

<Info>
  O script de instalação **remove essas variáveis automaticamente**, criando backup antes. Para resolver, basta reexecutá-lo. As instruções abaixo são para quem configurou manualmente ou prefere limpar à mão.
</Info>

### Variáveis a remover

* `CLAUDE_CODE_USE_VERTEX`
* `ANTHROPIC_VERTEX_PROJECT_ID`
* `ANTHROPIC_VERTEX_REGION`
* `GOOGLE_APPLICATION_CREDENTIALS`
* `GOOGLE_CLOUD_PROJECT` e `GOOGLE_CLOUD_LOCATION` (quando setadas para o Claude Code)

### Limpeza manual

<Tabs>
  <Tab title="Linux / macOS / WSL">
    Remova ou comente as linhas `export` acima no seu profile (`~/.zshrc`, `~/.bashrc` ou equivalente), depois recarregue o shell:

    ```bash theme={null}
    # Desativar na sessão atual
    unset CLAUDE_CODE_USE_VERTEX ANTHROPIC_VERTEX_PROJECT_ID ANTHROPIC_VERTEX_REGION \
          GOOGLE_APPLICATION_CREDENTIALS GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION \
          GCP_PROJECT GCLOUD_PROJECT

    # Recarregar o profile
    source ~/.zshrc   # ou ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    foreach ($v in 'CLAUDE_CODE_USE_VERTEX','ANTHROPIC_VERTEX_PROJECT_ID','ANTHROPIC_VERTEX_REGION','GOOGLE_APPLICATION_CREDENTIALS','GOOGLE_CLOUD_PROJECT','GOOGLE_CLOUD_LOCATION','GCP_PROJECT','GCLOUD_PROJECT') {
        [Environment]::SetEnvironmentVariable($v, $null, 'User')
        Remove-Item "Env:$v" -ErrorAction SilentlyContinue
    }
    ```

    Reabra o terminal em seguida.
  </Tab>
</Tabs>

<Warning>
  O Claude Code não faz mais parte do fluxo da IplanRio — use o **OpenCode**. Se você rodava `claude` por hábito, passe a rodar `opencode`.
</Warning>

***

## Configuração Manual

Para quem prefere configurar manualmente, usa o **OpenCode Desktop**, ou quer adicionar o Bifrost a uma instalação existente.

### Instalar o OpenCode

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    brew install anomalyco/tap/opencode
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    curl -fsSL https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-x64.tar.gz \
      | tar -xz -C /usr/local/bin opencode
    chmod +x /usr/local/bin/opencode
    ```

    Para ARM64 substitua `x64` por `arm64`.
  </Tab>

  <Tab title="Windows">
    Baixe o `.zip` em [releases](https://github.com/anomalyco/opencode/releases/latest) e adicione a pasta ao PATH.
  </Tab>

  <Tab title="Desktop">
    | Sistema             | Arquivo                            |
    | ------------------- | ---------------------------------- |
    | macOS Apple Silicon | `opencode-desktop-mac-arm64.dmg`   |
    | macOS Intel         | `opencode-desktop-mac-x64.dmg`     |
    | Windows             | `opencode-desktop-win-x64.exe`     |
    | Linux (deb)         | `opencode-desktop-linux-amd64.deb` |

    Baixe em [releases](https://github.com/anomalyco/opencode/releases/latest).
  </Tab>
</Tabs>

### Arquivo de configuração

Crie ou edite o arquivo abaixo com sua Virtual Key:

<Tabs>
  <Tab title="Linux / macOS — ~/.config/opencode/config.json">
    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "model": "anthropic/claude-haiku-4-5",
      "provider": {
        "anthropic": {
          "name": "Bifrost IplanRio (Anthropic)",
          "options": {
            "apiKey": "[sua-virtual-key]",
            "baseURL": "https://bifrost.iplan.dados.rio/anthropic/v1"
          },
          "models": {
            "claude-haiku-4-5": {
              "limit": {
                "context": 200000,
                "output": 64000
              }
            }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows — %APPDATA%\opencode\config.json">
    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "model": "anthropic/claude-haiku-4-5",
      "provider": {
        "anthropic": {
          "name": "Bifrost IplanRio (Anthropic)",
          "options": {
            "apiKey": "[sua-virtual-key]",
            "baseURL": "https://bifrost.iplan.dados.rio/anthropic/v1"
          },
          "models": {
            "claude-haiku-4-5": {
              "limit": {
                "context": 200000,
                "output": 64000
              }
            }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Desktop">
    Vá em **Settings → Providers → Add Provider**:

    | Campo    | Valor                                          |
    | -------- | ---------------------------------------------- |
    | Provider | Anthropic                                      |
    | Name     | Bifrost IplanRio (Anthropic)                   |
    | API Key  | `[sua-virtual-key]`                            |
    | Base URL | `https://bifrost.iplan.dados.rio/anthropic/v1` |

    Defina o modelo padrão como `claude-haiku-4-5`.
  </Tab>
</Tabs>

O exemplo acima habilita apenas o Claude. Para os demais modelos (Gemini, Kimi, GLM), adicione o provider `bifrost-google` ao mesmo `config.json`. O script de instalação escreve este bloco automaticamente.

<Accordion title="Adicionar Gemini, Kimi e GLM (provider bifrost-google)">
  ```json theme={null}
  {
    "provider": {
      "bifrost-google": {
        "npm": "@ai-sdk/openai-compatible",
        "name": "Bifrost (Google)",
        "options": {
          "apiKey": "[sua-virtual-key]",
          "baseURL": "https://bifrost.iplan.dados.rio/openai/v1"
        },
        "models": {
          "gemini-3.5-flash": {
            "id": "vertex/gemini-3.5-flash",
            "limit": { "context": 200000, "output": 64000 }
          },
          "gemini-3.1-pro-preview": {
            "id": "vertex/gemini-3.1-pro-preview",
            "limit": { "context": 200000, "output": 64000 }
          },
          "kimi-k2-thinking": {
            "id": "vertex/moonshotai/kimi-k2-thinking-maas",
            "limit": { "context": 256000, "output": 64000 }
          },
          "glm-5": {
            "id": "vertex/zai-org/glm-5-maas",
            "limit": { "context": 200000, "output": 64000 }
          }
        }
      }
    }
  }
  ```
</Accordion>

### Verificar

```bash theme={null}
opencode --version
```

Abra o OpenCode e confirme com `/status`:

```
> /status
API Provider: Anthropic (Bifrost IplanRio)
Model: claude-haiku-4-5
```

***

## Como Usar

### Início rápido

Execute `opencode` dentro do diretório do projeto. O agente lê o repositório e fica pronto para instruções:

```bash theme={null}
cd meu-projeto
opencode
```

Digite qualquer instrução em linguagem natural. O agente lê os arquivos relevantes, propõe e executa edições, roda comandos de build e lint para verificar e itera até concluir.

### Comandos internos

Dentro do OpenCode, use `/` para acessar funções do sistema:

| Comando    | O que faz                                     |
| ---------- | --------------------------------------------- |
| `/status`  | Exibe provider, modelo e uso da sessão        |
| `/clear`   | Limpa o histórico da conversa atual           |
| `/compact` | Comprime o histórico para economizar contexto |
| `/help`    | Lista todos os comandos disponíveis           |
| `/exit`    | Encerra o OpenCode                            |

### Modo não-interativo

Ideal para automações e integração com outros comandos:

```bash theme={null}
# Instrução pontual
opencode -p "Explique o que a função calculate_tax faz e seus edge cases"

# Passando arquivo via stdin
opencode -p "Revise este código e aponte problemas" < src/handler.go

# Encadeando com git
git diff HEAD~1 | opencode -p "Resuma as mudanças deste diff em português"
```

### Permissões

Para projetos onde você quer que o agente trabalhe com mais autonomia, sem confirmar cada passo, adicione ao `config.json`:

```json theme={null}
{
  "permission": {
    "bash": "allow",
    "edit": "allow",
    "write": "allow",
    "read": "allow"
  }
}
```

<Warning>
  Use permissões abertas apenas em repositórios onde você tem controle total. Em repositórios compartilhados, prefira o modo padrão com confirmação a cada ação.
</Warning>

***

## Modelos Disponíveis e Otimização de Custo

O Bifrost IplanRio dá acesso a múltiplos modelos. Escolha o modelo adequado à tarefa para preservar sua cota diária.

| Modelo                                  | Quando usar                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------ |
| `anthropic/claude-haiku-4-5`            | **Padrão** — tarefas do dia a dia, explicar código, commits, perguntas rápidas |
| `anthropic/claude-sonnet-4-6`           | Features complexas, revisões profundas, refatorações grandes                   |
| `bifrost-google/gemini-3.5-flash`       | Alternativa rápida e econômica para tarefas de baixa complexidade              |
| `bifrost-google/gemini-3.1-pro-preview` | Raciocínio avançado, análise de arquiteturas complexas                         |
| `bifrost-google/kimi-k2-thinking`       | Problemas que exigem raciocínio profundo passo a passo                         |
| `bifrost-google/glm-5`                  | Alternativa de baixo custo para tarefas gerais                                 |

### Trocar o modelo na sessão

Dentro do OpenCode, use o seletor de modelo para escolher sem editar o arquivo de configuração.

### Definir um modelo padrão diferente

Edite o campo `model` em `~/.config/opencode/config.json` (Linux/macOS) ou `%APPDATA%\opencode\config.json` (Windows):

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4-6"
}
```

<Tip>
  O padrão `claude-haiku-4-5` cobre bem a maioria das tarefas. Mude para `claude-sonnet-4-6` quando precisar de raciocínio mais profundo — desenvolvimento de features complexas, revisões de arquitetura ou refatorações grandes.
</Tip>

***

## Contexto de projeto com AGENTS.md

Crie um `AGENTS.md` na raiz do repositório para dar contexto permanente ao agente — o OpenCode lê este arquivo automaticamente em toda sessão.

### Estrutura recomendada

```markdown theme={null}
# [Nome do Projeto]

## Stack
- [Linguagem e versão]
- [Framework principal]
- [Banco de dados / infra]

## Comandos importantes
- `just build` — compila
- `just test` — roda testes
- `just lint` — verifica qualidade

## Estrutura do projeto
[Breve descrição das pastas principais]

## Convenções
[Padrões de código, nomenclatura, commits]

## O que NÃO fazer
[Antipadrões, arquivos que não devem ser alterados]
```

### Exemplos por tipo de repositório IplanRio

<Tabs>
  <Tab title="API Go (Gin)">
    ```markdown theme={null}
    # API [Nome]

    ## Stack
    - Go 1.24 + Gin
    - PostgreSQL via Cloud SQL (driver pgx)
    - Autenticação via JWT (Keycloak)
    - Deploy em GKE

    ## Comandos
    - `just build` — compila o binário
    - `just test` — roda testes com cobertura
    - `just lint` — golangci-lint
    - `just run` — inicia localmente com .env

    ## Estrutura
    - `cmd/` — entrypoints (main.go)
    - `internal/handlers/` — handlers HTTP
    - `internal/service/` — lógica de negócio
    - `internal/repository/` — acesso ao banco

    ## Convenções
    - Handlers retornam apenas HTTP; lógica fica em service/
    - Erros sempre propagados com contexto: `fmt.Errorf("...: %w", err)`
    - Testes ao lado dos arquivos (`_test.go`)
    - Commits em Conventional Commits (feat/fix/chore)
    ```
  </Tab>

  <Tab title="Pipeline dbt">
    ```markdown theme={null}
    # Pipeline dbt — [Nome]

    ## Stack
    - dbt + BigQuery
    - Prefect para orquestração

    ## Comandos
    - `dbt run` — executa os modelos
    - `dbt test` — roda os testes
    - `dbt docs generate && dbt docs serve` — documentação local

    ## Estrutura de camadas
    - `models/raw_` — dados brutos sem transformação
    - `models/int_` — transformações intermediárias
    - `models/dim_` / `models/fct_` — marts de consumo

    ## Convenções de nomenclatura
    - Tabelas: `<camada>_<fonte>__<entidade>` (ex: `raw_ergon__servidores`)
    - Colunas de data: sufixo `_data` (ex: `data_admissao`)
    - IDs externos: sufixo `_id` (ex: `matricula_id`)
    - Toda tabela deve ter testes de `not_null` e `unique` na PK

    ## O que NÃO fazer
    - Nunca colocar lógica de negócio em raw_
    - Não usar SELECT * em marts
    ```
  </Tab>

  <Tab title="Script Python / Prefect">
    ```markdown theme={null}
    # [Nome do flow] — Prefect

    ## Stack
    - Python 3.12 + uv
    - Prefect 3
    - BigQuery como destino

    ## Comandos
    - `uv run python flow.py` — executa localmente
    - `uv run pytest` — roda testes
    - `uv run ruff check .` — lint

    ## Estrutura
    - `flow.py` — definição principal do flow
    - `tasks/` — tasks Prefect reutilizáveis
    - `utils/` — helpers sem dependência de Prefect

    ## Convenções
    - Tasks são funções puras sempre que possível
    - Segredos via `Secret.load("nome-do-secret")`
    - Logs com `get_run_logger()`, nunca `print()`
    - Type hints obrigatórios em todas as funções
    ```
  </Tab>
</Tabs>

***

## Fluxo de trabalho típico

### Desenvolvimento de feature

```bash theme={null}
git checkout -b feat/nova-feature
opencode
# Descreva o que quer construir:
> Implemente o endpoint POST /api/vagas com campos [título, descrição, secretaria],
  validação no padrão dos handlers existentes e persistência no banco.
  Escreva os testes de integração junto.

# O agente lê os handlers existentes, cria o novo, escreve os testes e roda just test
```

### Code review antes do PR

```bash theme={null}
git diff main | opencode -p "
Revise este diff como code reviewer experiente em Go.
Aponte bugs, problemas de segurança, desvios das convenções e melhorias de performance.
Seja direto e específico com número de linha.
"
```

### Depuração de erro

```bash theme={null}
opencode -p "
Estou recebendo este erro em produção:
[cole o stack trace aqui]

Analise o código em internal/service/payment.go e identifique a causa raiz.
"
```

### Escrita de commits

```bash theme={null}
git diff --staged | opencode -p "
Escreva uma mensagem de commit em Conventional Commits para este diff.
Seja específico sobre o que mudou e por quê.
"
```

***

## Exemplos no contexto IplanRio

```bash theme={null}
# Revisar modelo dbt antes do PR
opencode -p "Revise models/fct_servidores.sql: nomenclatura, testes ausentes e otimizações"

# Criar handler Go seguindo padrão do projeto
opencode -p "Crie GET /api/cidadao/:cpf seguindo o padrão de internal/handlers/servidor.go"

# Otimizar query BigQuery lenta
opencode -p "Esta query demora 45s. Reescreva usando particionamento e clustering adequados"

# Documentar endpoints
opencode -p "Gere a spec OpenAPI 3.0 para todos os endpoints em internal/handlers/"

# Migração de dados
opencode -p "Escreva script Python que migra ergon.servidores para o formato RMI com validação e relatório de erros"
```

***

## Recursos

* [Documentação oficial do OpenCode](https://opencode.ai/docs)
* [Repositório OpenCode](https://github.com/anomalyco/opencode)
* [Releases e changelogs](https://github.com/anomalyco/opencode/releases)
* [Boas práticas de agentes de código](https://www.anthropic.com/engineering/claude-code-best-practices) — material conceitual, válido para qualquer agente de código

***

## Diagnóstico Automático

Se algo não estiver funcionando, rode o script de diagnóstico. Ele usa um **modelo gratuito** do OpenCode — não precisa de Virtual Key configurada — e verifica, identifica e corrige os problemas sozinho.

<Tabs>
  <Tab title="Linux / macOS / WSL">
    ```bash theme={null}
    curl -fsSL https://storage.googleapis.com/iplanrio-opencode/doctor.sh | bash
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    & ([scriptblock]::Create((irm 'https://storage.googleapis.com/iplanrio-opencode/doctor.ps1')))
    ```
  </Tab>
</Tabs>

O agente verifica e corrige automaticamente:

* Binário `opencode` no PATH
* `config.json` — model, providers Anthropic e Google, estrutura de modelos
* `opencode.json` — `small_model`
* Conectividade com o Bifrost
* Presença e validade da Virtual Key

Se a Virtual Key estiver ausente ou inválida, o agente instrui a solicitá-la no canal **`#peça-permissão`** do Discord da IplanRio.

***

## Troubleshooting

**`invalid_grant: Invalid grant: account not found`**

Variáveis de ambiente do antigo setup Claude Code + Vertex AI continuam ativas no seu shell. Reexecute o script de instalação — ele remove essas variáveis automaticamente, com backup — ou siga a [limpeza manual](#migrando-do-claude-code).

**`opencode: command not found` após instalação no Linux**

O binário foi instalado em `~/.local/bin`. Adicione ao PATH:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # ou ~/.zshrc
```

**`401 Unauthorized` ao usar o OpenCode**

A Virtual Key expirou ou foi revogada. Solicite uma nova no `#peça-permissão`.

**Erro de conexão com o Bifrost**

O Bifrost (`bifrost.iplan.dados.rio`) requer HTTPS na porta 443. Verifique sua conexão ou VPN.

**Modelo errado aparecendo**

Confirme que `"model": "anthropic/claude-haiku-4-5"` está no nível raiz do `config.json`. Reexecute o script de instalação se necessário.

**Agente editando arquivos que não deveria**

Remova o bloco `"permission"` do `config.json` para voltar ao modo com confirmação a cada ação.