Crea un Bookmark Manager Full-Stack con OpenCode en 30 minutos (Paso a paso)

Qué estamos construyendo

Olvídate de las listas de funciones. La mejor manera de aprender una herramienta es construyendo algo con ella.

En este tutorial, usarás OpenCode — el agente de codificación de AI de código abierto con más de 120K estrellas en GitHub — para construir un gestor de marcadores completo desde cero. La aplicación tendrá:

• Una API REST con Express.js y TypeScript
• Una base de datos SQLite con búsqueda de texto completo
• Un sistema de etiquetas para organizar marcadores
• Un frontend simple pero funcional
• Unit tests

Cada función de OpenCode se presenta en el momento en que la necesitas, no en una sección de funciones abstractas. Al final, sabrás cómo instalar OpenCode, configurar modelos, usar los modos Build y Plan, configurar servidores MCP y crear agentes personalizados, todo porque los usaste para construir un proyecto real.

Tiempo: ~30 minutos Requisitos previos: Node.js 18+ instalado, una terminal (macOS, Linux o WSL en Windows) Costo: Gratis (usando los Zen models de OpenCode)

Fase 1: Instalación de OpenCode y configuración del proyecto (5 minutos)

Instalar OpenCode

Abre tu terminal y ejecuta uno de estos 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

Verifica la instalación:

opencode --version

Deberías ver el número de versión. A partir de March 2026, la última versión estable está disponible en el repositorio de GitHub de OpenCode.

Crear el directorio del proyecto

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

Iniciar OpenCode por primera vez

opencode

Esto abre la TUI (Terminal User Interface) de OpenCode — una interfaz interactiva de pantalla completa construida con Bubble Tea. Verás una entrada de chat en la parte inferior y un panel de conversación en el área principal.

Elegir un modelo

En el primer inicio, OpenCode te pedirá que selecciones un modelo. Tienes tres caminos:

Gratis (Zen models): Escribe /models y selecciona uno de los Zen models gratuitos. Para este tutorial, Grok Code Fast 1 o GLM 4.7 funcionan bien. Estos son gratuitos y no requieren API key.

Local (Ollama): Si tienes Ollama instalado, OpenCode lo detectará automáticamente. El modelo recomendado para Ollama es glm-4.7:cloud.

Pago (trae tu propia key): Escribe /connect para vincular tu API key de Anthropic, OpenAI o Google. Las keys se almacenan localmente en ~/.local/share/opencode/auth.json.

Para este tutorial, cualquier modelo funciona. Los modelos de mayor capacidad (Claude Sonnet 4.6, GPT-5.4) producirán mejores resultados en tareas complejas, pero los Zen models gratuitos manejan todo lo que estamos construyendo aquí.

Fase 2: Andamiaje del proyecto con Build mode (4 minutos)

OpenCode comienza en Build mode por defecto. Build mode le da al agente de AI acceso total para crear archivos, editar código y ejecutar comandos. Esto es lo que queremos para el andamiaje.

Tu primer prompt

Escribe esto en el chat de 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.

OpenCode hará lo siguiente:

1. Creará un tsconfig.json
2. Instalará las dependencias con npm install
3. Creará src/index.ts con la configuración del servidor Express
4. Actualizará el package.json con los scripts de inicio

Observa la TUI — verás al agente ejecutando comandos de terminal, creando archivos y explicando lo que hace en cada paso. Esto no es generación de código en el vacío; OpenCode tiene acceso total a tu filesystem y terminal.

Verificar que funcione

Una vez que OpenCode termine, dile:

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

OpenCode ejecutará npx nodemon src/index.ts y confirmará que el servidor está escuchando. Deberías ver una salida como Server running on http://localhost:3000.

Qué acaba de suceder (Función: Build mode)

Build mode es el agente predeterminado de OpenCode. Tiene acceso a todas las herramientas: lectura/escritura de archivos, ejecución en terminal y edición de código. Según la documentación de OpenCode, puedes pensarlo como un programador de par de AI con acceso total a tu entorno de desarrollo.

Fase 3: Creación del modelo de datos y la base de datos (4 minutos)

Diseñar el esquema

Escribe 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.

OpenCode generará el módulo de base de datos completo. Presta atención a cómo maneja la configuración de FTS5 (Full-Text Search 5) — esta es una función de SQLite que potenciará nuestra funcionalidad de búsqueda más adelante.

Inicializar la base de datos al iniciar el servidor

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

Crear la configuración opencode.json

Este es un buen momento para introducir la configuración del proyecto. Crea un archivo diciéndole a 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."

Esto crea el archivo de configuración del proyecto que OpenCode lee al iniciarse. Le da a la AI un contexto persistente sobre tu proyecto — estándares de codificación, decisiones de arquitectura y restricciones — para que no tengas que repetirlos en cada prompt.

Fase 4: Construcción de los endpoints de la API REST (5 minutos)

Generar las rutas

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 }

Registrar las rutas

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

Probar con 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.

OpenCode ejecutará estos comandos en tu terminal y te mostrará las respuestas. Aquí es donde la herramienta brilla — nunca sales de la terminal y la AI verifica su propio trabajo.

Fase 5: Adición de búsqueda con FTS5 (4 minutos)

Introducir Plan mode

Antes de construir la búsqueda, usemos el Plan mode para pensar en la implementación. Cambia de modo:

/plan

Ahora estás en Plan mode. La AI puede leer tu código y analizarlo, pero no puede modificar ningún archivo. Esto es útil para planificar antes de realizar cambios.

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.

OpenCode examinará tu código, escribirá un plan en .opencode/plans/ y explicará su enfoque sin tocar ningún archivo. Lee el plan, ajústalo si es necesario y luego vuelve a cambiar:

/build

Implementar la búsqueda

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.

Probar la búsqueda

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

Qué acaba de suceder (Función: Plan mode)

El flujo de trabajo Plan/Build es cómo los desarrolladores experimentados usan OpenCode en tareas complejas. Primero planificar, revisar el enfoque y luego construir. Los archivos de plan se guardan en .opencode/plans/ y pueden ser referenciados más tarde por el agente de construcción. Esto evita que la AI tome decisiones estructurales importantes sobre la marcha.

Fase 6: Implementación del sistema de etiquetas (4 minutos)

Crear endpoints de etiquetas

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.

Probar el flujo de etiquetas

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: Construcción de un frontend sencillo (5 minutos)

Generar el 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.

OpenCode generará el frontend completo — estructura HTML, estilos CSS y JavaScript para interacciones con la API — en una sola pasada. La ventaja de construir esto en la terminal con un agente de AI es que puede probar inmediatamente si el frontend se conecta a la API.

Probar el stack completo

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: Adición de pruebas con un agente personalizado (5 minutos)

Crear un agente de pruebas personalizado

Aquí es donde entra la función de agentes personalizados de OpenCode. En lugar de usar el agente Build genérico para las pruebas, crearemos uno especializado.

Agrega esto a tu 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"]
    }
  }
}

Ahora cambia al agente de pruebas:

/agent test

Generar pruebas

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.

Ejecutar las pruebas

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

Qué acaba de suceder (Función: Agentes personalizados)

Los agentes personalizados te permiten crear personas enfocadas con instrucciones específicas y acceso a herramientas. El agente de pruebas que creamos solo puede leer archivos, escribir archivos de prueba y ejecutar comandos de terminal — no puede modificar el código fuente. Esta restricción evita el problema común de que la AI "arregle" tu código fuente cuando las pruebas fallan en lugar de arreglar las pruebas.

Puedes crear agentes para cualquier flujo de trabajo especializado: revisión de código, documentación, migraciones de bases de datos, scripts de DevOps. La documentación de agentes de OpenCode tiene más ejemplos.

Bonus: Conexión de un servidor MCP para una funcionalidad mejorada

Si deseas extender tu gestor de marcadores, puedes conectar herramientas externas a través de servidores MCP (Model Context Protocol).

Ejemplo: Adición de un servidor MCP de vista previa de enlaces

Imagina que quieres que OpenCode obtenga automáticamente metadatos (título, descripción, favicon) de las URLs al crear marcadores. Puedes conectar un servidor MCP que realice la obtención HTTP:

Agrega esto a tu opencode.json:

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

Ahora OpenCode tiene una nueva herramienta disponible: puede obtener metadatos de URL como parte de su flujo de trabajo. Cuando le pidas que "agregue un marcador para https://example.com y complete automáticamente el título y la descripción", usará el servidor MCP para obtener esos datos.

Servidores MCP remotos

Para servicios en la nube, usa servidores MCP remotos con manejo automático de OAuth:

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

OpenCode detecta respuestas 401 e inicia el flujo OAuth automáticamente si el servidor admite Dynamic Client Registration.

Bonus: Uso de OpenCode en CI/CD

OpenCode tiene un CLI mode que se ejecuta sin la TUI — perfecto para la automatización. Puedes usarlo en GitHub Actions o en cualquier 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 nuestro gestor de marcadores, podrías agregar un paso de CI que ejecute OpenCode para revisar los PR automáticamente. La integración con GitHub de OpenCode proporciona una versión más optimizada de este flujo de trabajo.

Estructura completa del proyecto

Después de seguir este tutorial, tu proyecto debería verse así:

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

Qué aprendiste

Al construir un proyecto real, practicaste estas capacidades de OpenCode:

La diferencia clave entre OpenCode y otras herramientas de codificación de AI es que es completamente de código abierto, se ejecuta en tu terminal y no almacena tu código ni tus datos de contexto. Tú controlas los modelos, los datos permanecen locales y la comunidad de más de 800 colaboradores lo mantiene evolucionando rápidamente.

Para los equipos que usan múltiples herramientas de AI, OpenCode funciona bien como el complemento basado en terminal para los asistentes de IDE. En ZBuild, a menudo lo usamos junto con herramientas basadas en editores para diferentes partes del flujo de trabajo de desarrollo.

Pasos siguientes

Ahora que tienes un gestor de marcadores en funcionamiento y una comprensión sólida de OpenCode, aquí hay algunas direcciones para explorar:

1. Agregar autenticación — Usa el agente Build para agregar autenticación basada en JWT con cuentas de usuario
2. Desplegar a producción — Pide a OpenCode que genere un Dockerfile y lo despliegue en Fly.io o Railway
3. Construir una extensión de navegador — Crea una extensión de Chrome que agregue marcadores a través de la API
4. Explorar más Zen models — Prueba Big Pickle, MiniMax M2.1, o ejecuta un modelo local a través de Ollama
5. Crear más agentes personalizados — Un agente de "refactorización", un agente de "documentación" o un agente de "auditoría de seguridad"

La documentación de OpenCode y el repositorio awesome-opencode tienen más plugins, temas y configuraciones de la comunidad para explorar.

Fuentes

• 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