Construa um Gerenciador de Favoritos Full-Stack com OpenCode em 30 Minutos (Passo a Passo)

O Que Estamos Construindo

Esqueça listas de funcionalidades. A melhor maneira de aprender uma ferramenta é construindo algo com ela.

Neste tutorial, você usará o OpenCode — o agente de codificação de IA open-source com 120K+ GitHub stars — para construir um bookmark manager completo do zero. O app terá:

• Uma REST API com Express.js e TypeScript
• Um banco de dados SQLite com full-text search
• Um sistema de tags para organizar bookmarks
• Um frontend simples, mas funcional
• Testes unitários

Cada funcionalidade do OpenCode é introduzida no momento em que você precisa dela — não em uma seção abstrata de funcionalidades. Ao final, você saberá como instalar o OpenCode, configurar modelos, usar os modos Build e Plan, configurar servidores MCP e criar agentes personalizados — tudo porque você os usou para construir um projeto real.

Tempo: ~30 minutes Pré-requisitos: Node.js 18+ instalado, um terminal (macOS, Linux, ou WSL no Windows) Custo: Grátis (usando modelos OpenCode Zen)

Fase 1: Instalando o OpenCode e Configurando o Projeto (5 minutes)

Instale o OpenCode

Abra seu terminal e execute um destes comandos:

# Option 1: npm (recommended)
npm i -g opencode-ai@latest

# Option 2: Homebrew (macOS/Linux)
brew install sst/tap/opencode

# Option 3: One-line installer
curl -fsSL https://opencode.ai/install.sh | bash

Verifique a instalação:

opencode --version

Você deverá ver o número da versão. Em March 2026, a versão estável mais recente está disponível no OpenCode GitHub repository.

Crie o Diretório do Projeto

mkdir bookmark-manager && cd bookmark-manager
git init
npm init -y

Inicie o OpenCode pela Primeira Vez

opencode

Isso abre a TUI (Terminal User Interface) do OpenCode — uma interface interativa em tela cheia construída com Bubble Tea. Você verá uma entrada de chat na parte inferior e um painel de conversa na área principal.

Escolha um Modelo

No primeiro lançamento, o OpenCode solicitará que você selecione um modelo. Você tem três caminhos:

Grátis (Zen models): Digite /models e selecione um dos free Zen models. Para este tutorial, Grok Code Fast 1 ou GLM 4.7 funcionam bem. Estes são gratuitos e não requerem API key.

Local (Ollama): Se você tiver o Ollama instalado, o OpenCode o detectará automaticamente. O recommended model for Ollama é glm-4.7:cloud.

Pago (traga sua própria chave): Digite /connect para vincular sua Anthropic, OpenAI, ou Google API key. As chaves são armazenadas localmente em ~/.local/share/opencode/auth.json.

Para este tutorial, qualquer modelo funciona. Modelos de maior capacidade (Claude Sonnet 4.6, GPT-5.4) produzirão melhores resultados em tarefas complexas, mas os modelos gratuitos Zen lidam com tudo o que estamos construindo aqui.

Fase 2: Estruturando o Projeto com o Build mode (4 minutes)

O OpenCode inicia no Build mode por padrão. O Build mode dá ao agente de IA acesso total para criar arquivos, editar código e executar comandos. É isso que queremos para a estruturação.

Seu Primeiro Prompt

Digite isto no chat do OpenCode:

Set up a TypeScript Node.js project with Express for a bookmark manager REST API.
Use SQLite via better-sqlite3 for the database. Add TypeScript, ts-node, and
nodemon as dev dependencies. Create a src/ directory with an index.ts entry point
that starts an Express server on port 3000.

O OpenCode irá:

1. Criar um tsconfig.json
2. Instalar dependências com npm install
3. Criar src/index.ts com a configuração do servidor Express
4. Atualizar o package.json com scripts de inicialização

Observe a TUI — você verá o agente executando comandos de terminal, criando arquivos e explicando o que faz em cada etapa. Isso não é geração de código no vácuo; o OpenCode tem acesso total ao seu sistema de arquivos e terminal.

Verifique se Funciona

Assim que o OpenCode terminar, diga a ele:

Run the server and verify it starts correctly on port 3000.

O OpenCode executará npx nodemon src/index.ts e confirmará que o servidor está escutando. Você deverá ver uma saída como Server running on http://localhost:3000.

O Que Acabou de Acontecer (Funcionalidade: Build mode)

O Build mode é o agente padrão do OpenCode. Ele tem acesso a todas as ferramentas: leitura/escrita de arquivos, execução de terminal e edição de código. De acordo com a OpenCode documentation, você pode pensar nele como um programador parceiro de IA com acesso total ao seu ambiente de desenvolvimento.

Fase 3: Criando o Modelo de Dados e o Banco de Dados (4 minutes)

Projete o Schema

Digite este prompt:

Create a database module at src/db.ts that:
1. Initializes a SQLite database at ./data/bookmarks.db
2. Creates a bookmarks table with: id (auto-increment), url (text, unique),
   title (text), description (text, nullable), created_at (datetime),
   updated_at (datetime)
3. Creates a tags table with: id (auto-increment), name (text, unique)
4. Creates a bookmark_tags junction table for many-to-many relationships
5. Enables WAL mode for concurrent read performance
6. Creates an FTS5 virtual table for full-text search on title and description
Export a function to get the database instance.

O OpenCode gerará o módulo de banco de dados completo. Preste atenção em como ele lida com a configuração do FTS5 (Full-Text Search 5) — esta é uma funcionalidade do SQLite que alimentará nossa funcionalidade de busca mais tarde.

Inicialize o Banco de Dados no Início do Servidor

Import the database module in index.ts and initialize it when the server starts.
Log a confirmation message.

Crie a Configuração opencode.json

Este é um bom momento para introduzir a configuração do projeto. Crie um arquivo dizendo ao OpenCode:

Create an opencode.json file in the project root with the project name
"bookmark-manager" and a rule that says "This is a TypeScript Express API
using better-sqlite3. Follow RESTful conventions. Use async/await. Return
JSON responses with consistent error formatting."

Isso cria o project configuration file que o OpenCode lê na inicialização. Ele fornece à IA um contexto persistente sobre o seu projeto — padrões de codificação, decisões de arquitetura e restrições — para que você não precise repeti-los em cada prompt.

Fase 4: Construindo os Endpoints da REST API (5 minutes)

Gere as Rotas

Create a routes module at src/routes/bookmarks.ts with these endpoints:
- POST /api/bookmarks — create a bookmark (validate url and title are present)
- GET /api/bookmarks — list all bookmarks with pagination (page, limit params)
- GET /api/bookmarks/:id — get a single bookmark with its tags
- PUT /api/bookmarks/:id — update a bookmark
- DELETE /api/bookmarks/:id — delete a bookmark and its tag associations
Use proper HTTP status codes. Return JSON with a consistent shape:
{ success: boolean, data: any, error?: string }

Registre as Rotas

Import the bookmark routes in index.ts and register them. Also add
express.json() middleware and a global error handler.

Teste com curl

Start the server, then create a test bookmark using curl:
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://opencode.ai", "title": "OpenCode - AI Coding Agent"}'
Then fetch all bookmarks to verify it was saved.

O OpenCode executará esses comandos no seu terminal e mostrará as respostas. É aqui que a ferramenta brilha — você nunca sai do terminal, e a IA verifica seu próprio trabalho.

Fase 5: Adicionando Busca com FTS5 (4 minutes)

Introduza o Plan mode

Antes de construir a busca, vamos usar o Plan mode para pensar na implementação. Alterne os modos:

/plan

Agora você está no Plan mode. A IA pode ler seu código e analisá-lo, mas não pode modificar nenhum arquivo. Isso é útil para planning before making changes.

Analyze my current database schema and FTS5 table. Plan how to implement a
search endpoint that queries the FTS5 table and returns bookmarks ranked by
relevance. Consider edge cases: empty queries, special characters, partial
matches.

O OpenCode examinará seu código, escreverá um plano em .opencode/plans/ e explicará sua abordagem sem tocar em nenhum arquivo. Leia o plano, ajuste se necessário e então volte:

/build

Implemente a Busca

Based on the plan, implement a GET /api/bookmarks/search?q=query endpoint
that uses the FTS5 virtual table for full-text search. Include snippet
highlighting and relevance ranking. Handle edge cases from the plan.

Teste a Busca

Create three more test bookmarks with different titles and descriptions,
then test the search endpoint with a query that should match two of them.

O Que Acabou de Acontecer (Funcionalidade: Plan mode)

O fluxo de trabalho Plan/Build é como desenvolvedores experientes usam o OpenCode em tarefas complexas. Planeje primeiro, revise a abordagem e depois construa. Os arquivos de plano são salvos em .opencode/plans/ e can be referenced later pelo agente de build. Isso evita que a IA tome grandes decisões estruturais de improviso.

Fase 6: Implementando o Sistema de Tags (4 minutes)

Crie os Endpoints de Tag

Create a routes module at src/routes/tags.ts with:
- POST /api/tags — create a new tag
- GET /api/tags — list all tags with bookmark counts
- POST /api/bookmarks/:id/tags — add a tag to a bookmark
- DELETE /api/bookmarks/:id/tags/:tagId — remove a tag from a bookmark
- GET /api/bookmarks?tag=tagname — filter bookmarks by tag (update existing
  list endpoint to support this query parameter)
Register the tag routes in index.ts.

Teste o Fluxo de Tags

Create two tags: "dev-tools" and "tutorials". Add the "dev-tools" tag to
the OpenCode bookmark. Then fetch bookmarks filtered by the "dev-tools" tag.

Fase 7: Construindo um Frontend Simples (5 minutes)

Gere o Frontend

Create a public/ directory with a single-page frontend:
- index.html with a clean, minimal design (no framework, just HTML/CSS/JS)
- A form to add bookmarks (url, title, description)
- A search bar that queries the search endpoint with debounced input
- A list of bookmarks showing title, url, tags, and a delete button
- A tag filter sidebar that shows all tags with counts
- Use fetch() for API calls. Mobile responsive. No build step needed.
Serve the public/ directory as static files from Express.

O OpenCode gerará o frontend completo — estrutura HTML, estilização CSS e JavaScript para interações com a API — em uma única passagem. A vantagem de construir isso no terminal com um agente de IA é que ele pode testar imediatamente se o frontend se conecta à API.

Teste a Stack Completa

Start the server, open http://localhost:3000 in a description, and verify
that adding a bookmark from the form, searching, and filtering by tag all
work correctly.

Fase 8: Adicionando Testes com um Agente Personalizado (5 minutes)

Crie um Agente de Teste Personalizado

É aqui que entra a funcionalidade de custom agents do OpenCode. Em vez de usar o agente Build genérico para testes, criaremos um especializado.

Adicione isto ao seu opencode.json:

{
  "agents": {
    "test": {
      "name": "Test Writer",
      "instructions": "You are a testing specialist. Write comprehensive tests using Vitest. Focus on edge cases and error paths. Never modify source code — only create and edit test files.",
      "tools": ["read", "write", "terminal"]
    }
  }
}

Agora mude para o agente de teste:

/agent test

Gere os Testes

Write comprehensive tests for the bookmark API using Vitest and supertest.
Cover:
- Creating a bookmark with valid data
- Creating a bookmark with missing required fields
- Fetching all bookmarks with pagination
- Searching with FTS5 (matching and non-matching queries)
- Adding and removing tags
- Deleting a bookmark removes its tag associations
Use an in-memory SQLite database for test isolation.

Execute os Testes

Install vitest and supertest as dev dependencies, add a test script to
package.json, then run the test suite.

O Que Acabou de Acontecer (Funcionalidade: Agentes Personalizados)

Agentes personalizados permitem que você crie personas focadas com instruções específicas e acesso a ferramentas. O agente de teste que criamos só pode ler arquivos, escrever arquivos de teste e executar comandos de terminal — ele não pode modificar o código-fonte. Essa restrição evita o problema comum da IA "corrigir" seu código-fonte quando os testes falham, em vez de corrigir os testes.

Você pode criar agentes para qualquer fluxo de trabalho especializado: revisão de código, documentação, migrações de banco de dados, scripts de DevOps. A OpenCode agents documentation tem mais exemplos.

Bônus: Conectando um Servidor MCP para Funcionalidade Aprimorada

Se você quiser estender seu bookmark manager, pode conectar ferramentas externas via servidores MCP (Model Context Protocol).

Exemplo: Adicionando um Servidor MCP de Link Preview

Imagine que você quer que o OpenCode busque automaticamente metadados (título, descrição, favicon) de URLs ao criar bookmarks. Você pode conectar um servidor MCP que faz buscas HTTP:

Adicione isto ao seu opencode.json:

{
  "mcp": {
    "link-preview": {
      "type": "local",
      "command": ["npx", "link-preview-mcp-server"]
    }
  }
}

Agora o OpenCode tem uma nova ferramenta disponível: ele pode buscar metadados de URL como parte de seu fluxo de trabalho. Quando você pedir para ele "add a bookmark for https://example.com and auto-fill the title and description," ele usará o servidor MCP para buscar esses dados.

Servidores MCP Remotos

Para serviços em nuvem, use servidores MCP remotos com automatic OAuth handling:

{
  "mcp": {
    "cloud-storage": {
      "type": "remote",
      "url": "https://mcp.example.com/storage",
      "headers": {
        "Authorization": "Bearer ${STORAGE_TOKEN}"
      }
    }
  }
}

O OpenCode detecta respostas 401 e inicia o fluxo OAuth automaticamente se o servidor suportar Dynamic Client Registration.

Bônus: Usando OpenCode em CI/CD

O OpenCode possui um CLI mode que funciona sem a TUI — perfeito para automação. Você pode usá-lo no GitHub Actions ou em qualquer pipeline de CI:

# Run a single prompt and exit
opencode -p "Review the changes in the last commit for security issues" --no-tui

# Use a specific model
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

Para o nosso bookmark manager, você poderia adicionar uma etapa de CI que executa o OpenCode para revisar PRs automaticamente. A OpenCode GitHub integration fornece uma versão mais simplificada deste fluxo de trabalho.

A Estrutura Completa do Projeto

Depois de seguir este tutorial, seu projeto deve se parecer com isto:

bookmark-manager/
  opencode.json          # OpenCode project config + custom agents + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Express server entry point
    db.ts                # SQLite database module with FTS5
    routes/
      bookmarks.ts       # CRUD + search endpoints
      tags.ts            # Tag management endpoints
  public/
    index.html           # Single-page frontend
  tests/
    bookmarks.test.ts    # API test suite
  data/
    bookmarks.db         # SQLite database (gitignored)
  .opencode/
    plans/               # Plans from Plan mode sessions

O Que Você Aprendeu

Ao construir um projeto real, você praticou estas capacidades do OpenCode:

A principal diferença entre o OpenCode e outras ferramentas de codificação por IA é que ele é entirely open source, roda no seu terminal e não armazena seu código ou dados de contexto. Você controla os modelos, os dados permanecem locais e a comunidade de 800+ colaboradores o mantém evoluindo rápido.

Para equipes que usam múltiplas ferramentas de IA, o OpenCode funciona bem como o complemento baseado em terminal para assistentes de IDE. Na ZBuild, frequentemente o usamos ao lado de ferramentas baseadas em editor para diferentes partes do fluxo de trabalho de desenvolvimento.

Próximos Passos

Agora que você tem um bookmark manager funcional e uma compreensão sólida do OpenCode, aqui estão algumas direções para explorar:

1. Adicione autenticação — Use o agente Build para adicionar auth baseada em JWT com contas de usuário
2. Implante em produção — Peça ao OpenCode para gerar um Dockerfile e implantar no Fly.io ou Railway
3. Construa uma extensão de navegador — Crie uma extensão do Chrome que adicione bookmarks via API
4. Explore mais Zen models — Experimente Big Pickle, MiniMax M2.1, ou execute um modelo local através do Ollama
5. Crie mais agentes personalizados — Um agente de "refactor", um agente de "docs" ou um agente de "security audit"

A OpenCode documentation e o awesome-opencode repository têm mais plugins, temas e configurações da comunidade para explorar.

Fontes

• OpenCode — Official Documentation
• OpenCode — GitHub Repository
• OpenCode — Zen Models
• OpenCode — Agents Documentation
• OpenCode — MCP Servers
• OpenCode — CLI Mode
• OpenCode — Configuration
• OpenCode — GitHub Integration
• Ollama — OpenCode Integration
• awesome-opencode — Community Resources
• Composio — MCP with OpenCode
• Computing for Geeks — Setup OpenCode AI