← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 3: Primeros Pasos

Por: Artiko
opencodeaituiprimeros-pasos

Capitulo 3: Primeros Pasos

< Volver al Indice del Tutorial

Iniciar OpenCode

Para comenzar, navega a la raíz de tu proyecto y ejecuta:

opencode

OpenCode detecta automáticamente el tipo de proyecto (lenguaje, framework, estructura de directorios) y carga la TUI (Terminal User Interface). La primera vez que lo ejecutes en un proyecto nuevo, toma unos segundos mientras analiza la estructura de archivos y determina el contexto.

Si es la primera vez que usas OpenCode y no has configurado un proveedor, verás un mensaje indicándote que ejecutes /connect para autenticarte. Esto solo necesitas hacerlo una vez — las credenciales se guardan globalmente.

Conectar un Proveedor

La primera vez que uses OpenCode necesitas autenticarte con un proveedor LLM. El comando /connect simplifica este proceso:

/connect

Este comando abre tu navegador y te redirige a opencode.ai/auth, donde puedes:

  1. Seleccionar tu proveedor (Anthropic, OpenAI, Google, GitHub Copilot, etc.)
  2. Autorizar el acceso de forma segura
  3. Las credenciales se guardan automáticamente en tu configuración global

Para proveedores que requieren API key directa, también puedes configurarlos como variables de entorno antes de iniciar OpenCode:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
opencode

OpenCode detecta automáticamente las API keys disponibles en el entorno y las usa sin configuración adicional.

Verificar la Conexion

Una vez conectado, puedes verificar qué proveedores están configurados observando la status bar en la parte superior de la TUI. El modelo activo aparece junto al nombre del agente. Si necesitas cambiar de modelo, usa /models.

La Interfaz TUI

La TUI es la interfaz principal de OpenCode y donde pasarás la mayor parte del tiempo. Está diseñada para ser eficiente y no salir de la terminal.

Estructura de la Pantalla

La TUI se divide en varias áreas funcionales:

graph TD
    subgraph TUI["Terminal User Interface"]
        SB[Status Bar - Agente, Modelo, Tokens, Estado]
        OP[Output Panel - Respuestas, código, diffs]
        IP[Input Panel - Prompts y comandos]
    end
    SB --> OP --> IP

Status Bar

En la parte superior de la pantalla. Muestra información clave en tiempo real:

Area de Output

Ocupa la mayor parte de la pantalla. Aquí se renderiza:

El output soporta scroll con las teclas de navegación para revisar respuestas anteriores en la conversación.

Area de Input

En la parte inferior de la pantalla. Aquí escribes tus prompts y comandos. Características clave:

Inicializar el Proyecto

El comando /init es uno de los más importantes. Analiza tu proyecto completo y genera un archivo AGENTS.md en la raíz:

/init

OpenCode examina la estructura de directorios, los archivos de configuración (package.json, Cargo.toml, go.mod, etc.), los scripts de build/test/lint, y genera un documento que contiene:

Por Que es Importante AGENTS.md

El archivo AGENTS.md funciona como la “memoria del proyecto” para OpenCode. Cada vez que inicias una sesión, el agente lee este archivo para entender el contexto. Sin él, el agente tiene que deducir las convenciones cada vez, lo que consume tokens y puede llevar a inconsistencias.

Importante: commitea AGENTS.md al repositorio. Así todos los miembros del equipo comparten el mismo contexto:

git add AGENTS.md
git commit -m "feat: agregar AGENTS.md para OpenCode"

Puedes editar AGENTS.md manualmente para agregar reglas que la detección automática no capturó, como convenciones de naming, arquitectura preferida, o restricciones de seguridad. También puedes ejecutar /init de nuevo para regenerarlo si el proyecto ha cambiado significativamente.

Alternar entre Agentes

OpenCode incluye dos agentes built-in, cada uno diseñado para un tipo de trabajo diferente. Usa Tab para alternar entre ellos:

AgenteFunciónPuede ModificarHerramientas
BuildDesarrollo activo: lee, escribe, ejecutaSíTodas
PlanAnálisis y planificaciónNo (solo lectura)read, glob, grep

Cuando Usar Plan

Usa el agente Plan cuando quieras:

Cuando Usar Build

Usa el agente Build cuando estés listo para:

Un flujo de trabajo común es empezar con Plan para entender el problema, y luego cambiar a Build para implementar la solución.

Referenciar Archivos con @

Puedes referenciar archivos directamente en tus prompts usando @. Esto le da contexto específico al agente sobre qué archivos debe considerar:

Refactoriza @src/index.ts para separar las rutas en su propio archivo
Explica qué hace @src/utils/parser.ts y sugiere mejoras
Agrega tests unitarios para @src/services/auth.ts basándote en @src/services/auth.test.ts

Puedes referenciar múltiples archivos en un mismo prompt. El agente leerá todos los archivos referenciados antes de procesar tu solicitud, lo que le da un contexto más preciso y reduce la necesidad de que busque archivos por su cuenta.

Consejos para Referencias Efectivas

Slash Commands Basicos

Los comandos se ejecutan escribiendo / seguido del nombre. Los más importantes para empezar:

Gestion de Sesion

ComandoDescripción
/clearLimpia el historial de la sesión actual
/compactComprime el contexto para ahorrar tokens sin perder información clave
/shareGenera un enlace para compartir la sesión con otros
/connectAgrega o cambia el proveedor LLM autenticado
/initAnaliza el proyecto y genera AGENTS.md

Edicion y Control

ComandoDescripción
/undoDeshace el último cambio realizado por el agente
/redoRehace el último cambio deshecho
/modelsLista y cambia el modelo LLM activo
/helpMuestra todos los comandos disponibles con descripción

Compactacion de Contexto

El comando /compact es especialmente útil en sesiones largas. Cuando el contexto crece demasiado (muchos archivos leídos, mucha conversación), el consumo de tokens se dispara. /compact resume la conversación manteniendo la información esencial y liberando espacio en la ventana de contexto.

OpenCode v1.3.15 soporta compactación automática configurable:

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

Con esta configuración, el agente compacta automáticamente cuando el contexto supera cierto umbral, y reserva 10,000 tokens para mantener siempre información crítica disponible.

Multi-Sesion

Una de las novedades más importantes de OpenCode v1.3.15 es el soporte de múltiples sesiones simultáneas. Esto te permite mantener diferentes líneas de trabajo activas sin perder el contexto de ninguna.

Como Funciona

Cada sesión mantiene de forma independiente:

Puedes cambiar entre sesiones desde la TUI, y al volver a una sesión anterior encuentras todo exactamente como lo dejaste.

Casos de Uso para Multi-Sesion

Modo No Interactivo

Para automatización, scripts y CI/CD, OpenCode soporta ejecución directa sin abrir la TUI:

opencode run "agrega un endpoint GET /health que retorne status 200"

El agente ejecuta la tarea y termina. El output se imprime en stdout para que pueda ser capturado por scripts o pipelines.

Flags Disponibles

# Usar un modelo específico
opencode run --model anthropic/claude-sonnet-4-5 "genera tests unitarios para auth.ts"

# Limitar herramientas disponibles
opencode run --tools read,write "corrige el typo en README.md"

# Modo silencioso (solo output del agente)
opencode run --quiet "lista todos los TODOs del proyecto"

Integracion con Scripts

El modo no interactivo es perfecto para integrar OpenCode en scripts de shell:

#!/bin/bash
# Script de pre-commit que verifica convenciones
opencode run --tools read,grep --quiet \
  "verifica que todos los archivos en src/ siguen las convenciones de AGENTS.md"

Flujo de Trabajo Tipico

Un flujo de trabajo completo con OpenCode se ve así:

flowchart TD
    A[opencode - Abrir TUI] --> B{Primera vez?}
    B -->|Sí| C[/connect - Autenticar]
    C --> D[/init - Generar AGENTS.md]
    B -->|No| E[Tab → Plan]
    D --> E
    E --> F[Analizar el problema]
    F --> G[Tab → Build]
    G --> H[Implementar cambios]
    H --> I{Resultado OK?}
    I -->|No| J[/undo - Deshacer]
    J --> H
    I -->|Sí| K[git diff - Revisar]
    K --> L[git commit]

Paso a paso:

  1. opencode — abrir la TUI en la raíz de tu proyecto
  2. /connect — autenticar proveedor (solo la primera vez)
  3. /init — generar AGENTS.md (solo la primera vez, o cuando cambie el proyecto)
  4. Tab para Plan — analizar qué necesitas hacer sin modificar nada
  5. Tab para Build — implementar los cambios cuando tengas claro el plan
  6. Revisar con git diff los cambios realizados
  7. /undo si algo no quedó bien — puedes deshacer y reintentar
  8. Commitear cuando estés satisfecho con los cambios

Atajos de Teclado

Los atajos de teclado están diseñados para mantener las manos en el teclado sin necesidad del ratón:

AtajoAcción
TabAlternar entre agentes (Build ↔ Plan)
Ctrl+CCancelar la generación actual del agente
Ctrl+DSalir de OpenCode
Shift+EnterNueva línea en el input (prompt multilínea)
Up/DownNavegar historial de prompts anteriores
EscCerrar paneles flotantes o cancelar acción

Los atajos son personalizables a través del archivo tui.json, que veremos en detalle en el capítulo siguiente.

Consejos para Empezar

Prompts Efectivos

La calidad de los resultados depende mucho de cómo formules tus peticiones:

Gestionar Tokens

Los tokens son tu principal costo al usar OpenCode con proveedores cloud. Para optimizarlos:

Cuando Algo Sale Mal

Siguiente: Capitulo 4: Configuracion —>

← Volver al listado de tecnologías ← Índice de OpenCode