Plugin para OpenCode 2

Qué instala y qué está publicado #

El paquete @2jmalvarez/[email protected] está publicado y verificado en npm, independientemente de OEC autónomo. No sustituye la conversación ni modifica OpenCode: añade un editor y paneles dentro de su TUI.

npm install -g openeditorcode instala solamente el editor autónomo. El plugin se configura aparte en cli.json. No necesitas clonar ni compilar para solicitar el paquete npm.

El proyecto al lado de la conversación #

01 / La conversación sigue abiertaAmpliar captura ↗

Ver detalle legible de Files y Diff

Recorte de la captura de conversación, sin alterar el contenido de los paneles.

• Files muestra carpetas y archivos; Ctrl+F o el selector Fuzzy ^F / Literal ^F / Name ^F alterna nombre/ruta y contenido. Ctrl+E conserva Fuzzy/Literal para nombres.
• Diff muestra cambios del repositorio local, no solo archivos tocados por el agente. Puedes mantener ambos paneles abiertos y seguir escribiendo en el chat.
• F7 oculta toda la sección Files, incluida su cabecera. Contraer mediante la cabecera es distinto y conserva el buscador/árbol para recuperarlos después. F8 alterna Diff sin alterar Files.
• Files y Diff muestran cabeceras desde el inicio sin leer disco antes del consentimiento. panelHeight: expanded usa el viewport restante real, descontando contexto/MCP; las listas comparten igual altura. compact conserva alturas acotadas. Cada árbol tiene su scroll independiente.

Un editor, sin abandonar la sesión #

F6 alterna conversación/editor conservando paneles, documentos, cursor, scroll y cambios pendientes. No envía un prompt ni guarda automáticamente. Las pestañas de archivos son independientes de las sesiones de OpenCode.

La captura muestra README en fuente: numeración, resaltado y controles de edición. Markdown también tiene preview, y las imágenes se abren en pestañas de lectura; se explican más abajo.

02 / Del chat al archivo, con F6Ampliar captura ↗

Antes de instalar #

• OpenCode 2: API mínima 2.0.26, rango declarado >=2.0.26 <3. Matriz de publicación verificada: 2.0.26 / 2.0.27 / 2.1.0 / 2.1.1 en Windows y Linux. No es compatible con V1 ni certifica cada terminal o versión posterior.
• Runtime Bun 1.3.14+. OpenCode aporta OpenTUI >=0.5.17 <0.7.0 y Solid >=1.9 <2; no instales copias privadas. Para OpenCode 2.1.x usa plugin 0.3.1 o posterior: las versiones anteriores no satisfacen sus requisitos de propietario de recursos nativos. Git debe estar disponible para Diff; editar archivos no requiere un repositorio.
• Carpeta local accesible y consentimiento explícito antes de leerla, salvo permiso recordado para esa raíz exacta y equipo/usuario u override localRoot. El plugin sigue la carpeta de la sesión; no usa su carpeta de instalación como proyecto. Las raíces conservan controllers, documentos y borradores separados.

1. Localiza la configuración global #

1. Abre cli.json en la carpeta informada; normalmente ~/.config/opencode/cli.json. XDG_CONFIG_HOME puede cambiarla. Guarda una copia antes de editar.
2. Agrega la entrada del plugin al array plugins existente. Conserva sus otras entradas y opciones. No reemplaces todo el archivo si ya contiene configuración.
3. No lo agregues a opencode.json ni a .oec/config.json: estas son opciones de la TUI de OpenCode. No existe cli.json de proyecto.

opencode --version
opencode debug paths config

2. Configura el paquete en Windows #

OpenCode descarga el paquete al cargarlo. No hace falta instalar OEC globalmente ni indicar localRoot. Guarda el archivo y recarga el plugin o reinicia la TUI. Ante un error de instalación consulta /plugins, la versión del anfitrión y el alcance de verificación al inicio de esta guía.

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    {
      "package": "@2jmalvarez/[email protected]",
      "options": {
        "toggleBinding": "f6",
        "filesBinding": "f7",
        "diffBinding": "f8",
        "explorerWidth": 30
      }
    }
  ]
}

La misma instalación en Linux #

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    {
      "package": "@2jmalvarez/[email protected]",
      "options": {
        "toggleBinding": "f6",
        "filesBinding": "f7",
        "diffBinding": "f8",
        "explorerWidth": 30
      }
    }
  ]
}

3. Abre tu primer archivo #

1. Abre una sesión en tu proyecto y busca OEC: opencode-editor en Ctrl+P. Confirma el acceso a la carpeta EN ESTA COMPUTADORA cuando se solicite. Cancelar no lee archivos.
2. F7 muestra Files; ↑/↓ navega, Enter abre archivos o expande carpetas. Diff aparece por defecto después del consentimiento y se controla aparte con F8.
3. En fuente editable, Tab lleva el foco al texto, Enter crea una línea y Ctrl+S guarda. Ctrl+W cierra con confirmación si hay ediciones pendientes.
4. F6 vuelve a la conversación. Regresa con F6 para continuar: las pestañas, ediciones y visibilidad de paneles siguen allí.

Permisos locales: permitir, recordar u olvidar #

• Allow for this TUI only autoriza hasta cerrar OpenCode. Allow and remember this folder recuerda la raíz exacta para este equipo/usuario. Deny access o Esc no lee el proyecto. No se autorizan otras raíces o subcarpetas abiertas como proyectos independientes.
• Forget remembered folder access en la paleta elimina el permiso guardado sin cerrar documentos ni perder borradores; se pregunta otra vez tras reiniciar. localRoot sigue autorizando explícitamente su ruta hasta quitarlo de cli.json. Los workspaces remotos requieren override explícito incluso si existe un permiso recordado; no hay lectura remota.

Encuentra archivos: Fuzzy o Literal #

• Pulsa / desde el árbol o haz clic en Search files… Tanto el editor como el chat muestran resultados dentro de sus carpetas padre. Incluye archivos de carpetas cerradas.
• Fuzzy (default) acepta letras en orden a lo largo de la ruta. Literal busca texto consecutivo en el nombre; si incluyes /, busca en la ruta. Ambos ignoran mayúsculas. Cambia con Ctrl+E; el selector a la derecha alterna nombre/contenido.
• ↑/↓ elige y Enter abre o expande. Tab entra al árbol sin borrar la consulta. Esc limpia; con el campo vacío devuelve el foco al chat. Los nombres largos seleccionados se desplazan horizontalmente hasta el final.
• Ctrl+F en este campo cambia a contenido literal sin distinguir mayúsculas: lee disco, no borradores, y conserva carpetas padre. Primeros 80 archivos sobre índice de 50.000 entradas; respeta .gitignore, excluye .git, binarios, UTF-8 inválido y textos mayores de 2 MiB. Consultas nuevas cancelan resultados anteriores. F5 reconstruye; no es la búsqueda avanzada por líneas de OEC. Ctrl+F en fuente editable sigue siendo búsqueda local.

Árboles y scroll sin perder el lugar #

Rueda y scrollbar desplazan Files y Diff sin volver automáticamente a la selección. Los refrescos conservan esa posición manual. Al navegar con teclado se vuelve a hacer visible la selección. Files conserva posiciones distintas para árbol normal y resultados.

Home/End selecciona primera/última fila; RePág/AvPág recorre una página. Enter/→ expande carpetas; ← contrae o vuelve al padre. Las cabeceras se contraen con Enter/espacio; F7/F8 cambian visibilidad, no son el mismo control.

Git local: del árbol Diff al archivo #

1. Guarda primero: Diff lee disco e índice, no buffers sin guardar. ● identifica staged (HEAD → índice), ○ cambios (índice → disco) y ? archivos sin seguimiento. Una ruta puede aparecer en ambas áreas.
2. Expande carpetas y pulsa Enter o haz clic en un archivo cambiado. Abre su diff en una pestaña propia de solo lectura; staged y working tree tienen pestañas distintas. Reabrir el mismo diff actualiza su pestaña.
3. F4 abre el archivo ACTUAL para editar sin cerrar el diff ni restaurar contenido antiguo. Si fue eliminado, avisa sin recrearlo. No se puede guardar ni generar borradores de un diff.

• La vista split/unified se elige en configuración. +N se muestra verde, −N rojo; ● azul identifica staged, ○ verde archivos nuevos, rojo eliminados y amarillo modificados/renombrados. Letras y símbolos conservan significado sin depender solo del color. Usa el componente público OpenTUI y tema del anfitrión.
• Actualiza por eventos y cada tres segundos mientras Diff está visible y expandido; F5 fuerza lectura local sin fetch. Contraer u ocultar detiene timers y suscripciones. Para rutas UNC WSL usa Git de esa distribución.
• El plugin no hace stage, commit, descarte, pull ni push. Los comandos de lectura usan argumentos separados, límites y timeout; patches con --no-ext-diff y --no-textconv. Binarios o cambios sin hunks muestran descripción Git.

Markdown: lee con formato, edita con F4 #

1. Abre un .md, .markdown o .mdown desde Files. Con markdownPreview: true aparece formateado en una vista de lectura.
2. Pulsa F4 para editar su fuente. Vuelve a pulsar F4 para revisar el contenido con formato, también antes de guardarlo. Cambiar de vista no guarda automáticamente.
3. Guarda explícitamente con Ctrl+S. Si prefieres empezar siempre editando, usa markdownPreview: false. F4 desde un diff abre directamente la fuente editable.

Sí: también puedes ver imágenes #

1. Selecciona un PNG, JPEG, GIF o WebP en Files y ábrelo con Enter o clic, igual que un archivo de código.
2. Se abre en una pestaña de solo lectura, ajustada al espacio disponible. Puedes alternar con documentos y volver al chat. No se edita, guarda ni incluye en borradores.
3. Si tu terminal no muestra la imagen correctamente, abre Ctrl+P → OEC: opencode-editor → plugin configuration → Image protocol y prueba blocks. Para hacerlo persistente configura imageProtocol en cli.json.

• Límite de 16 MiB por imagen. auto negocia el protocolo soportado por la terminal; blocks usa celdas de color, útil en Windows Terminal/WSL sin protocolo gráfico compatible.
• Una imagen corrupta muestra un aviso. SVG tiene preview estático separado y XML editable con F4. No se promete animación GIF, zoom, retoque ni compatibilidad gráfica idéntica entre terminales. F4 no convierte imágenes raster en documentos editables.
• Las capturas de esta guía muestran el chat y el editor fuente; no son demostraciones del visor de imágenes.

SVG: preview y XML con F4 #

SVG abre en preview local. F4 alterna XML editable y preview del borrador sin guardar; Ctrl+S guarda explícitamente. Un SVG inválido muestra un aviso y permite volver al código. Usa imageProtocol auto/blocks, texto hasta 2 MiB y raster hasta 1600 píxeles por dimensión.

WASM y fuente se incluyen con sus licencias en el paquete. El render es estático: no ejecuta scripts, DTD ni entidades y no carga imágenes externas. Las ediciones conservan confirmaciones, conflictos y recuperación de borradores.

Renombrar sin perder lo que estabas editando #

Con foco en Files, selecciona un archivo o carpeta y pulsa F2. Confirma el nuevo nombre; se actualizan las rutas de pestañas afectadas, incluidos descendientes de carpetas, conservando sus ediciones. No sobrescribe un destino existente ni permite salir de la raíz.

Es una operación real sobre el disco: el agente y Git pueden observar el cambio. El plugin no añade por ello creación/eliminación de archivos, Guardar como ni un gestor completo de operaciones Git.

Todos los atajos, por contexto #

Aliases heredados del editor de texto #

Además de los controles anteriores, el plugin expone los bindings del textarea que aporta OpenCode. La lista exacta del runtime está en All keyboard shortcuts; depende de la versión OpenTUI del anfitrión y de qué modificadores transmite tu terminal. Las reasignaciones OEC tienen prioridad: Ctrl+A selecciona todo, Ctrl+D selecciona palabra, Ctrl+F busca y Ctrl+W cierra.

La paleta es el mapa del plugin #

Ctrl+P → OEC: opencode-editor agrupa todas las acciones por contexto, sin repetir OEC en cada título. Incluye alternar nombre/contenido, Fuzzy/Literal, altura expanded/compact, expandir/contraer Files y Diff, refrescar, limpiar consulta, navegación/abrir/contraer árboles, preview/fuente Markdown/SVG y operaciones de documentos. All keyboard shortcuts y plugin configuration muestran ayudas y valores. También están guardar/cerrar/recargar, wrap, foco, siguiente pestaña, renombrar y borrar borradores explícitamente.

Opciones y valores predeterminados #

Ejemplo: búsqueda, previews y diffs #

{
  "searchMode": "fuzzy",
  "markdownPreview": true,
  "diffView": "split",
  "imageProtocol": "auto"
}

Migración desde 0.2.x #

En 0.2.2 F6 dejaba Files solo y F7 controlaba Diff; filesBinding era alias de diffBinding. Desde 0.3.0 F6 conserva paneles, filesBinding controla Files (f7) y diffBinding controla Diff (f8). Si fijaste diffBinding: f7, cámbialo a f8 para evitar el conflicto. No se reescribe cli.json automáticamente.

Desde 0.2.1 hay guardado nativo WSL, resultados de búsqueda en árbol, nombres largos desplazables y Ctrl+L. Desde 0.3.0 Diff deja de depender del servidor/visor general de OpenCode: lee Git local y abre el archivo elegido en una pestaña propia.

Selección y portapapeles #

Ctrl+C copia solo la selección mediante OSC 52; sin selección no copia la línea ni termina OpenCode. Ctrl+V reemplaza la selección conservando saltos finales y normaliza CRLF a LF en el buffer. Si cambian documento, contenido, cursor, selección o contexto mientras lee el portapapeles, cancela el pegado para no insertarlo en otro lugar.

Guardado y cambios del agente #

• El archivo activo se comprueba al entrar al editor, cada tres segundos mientras está montado y con F5. Limpio: recarga. Con cambios locales: conserva tu texto y avisa. Guardar compara con la versión conocida en disco; no sobrescribe cambios externos ni recrea eliminados silenciosamente.
• Reload file from disk pide confirmar el descarte de ediciones. Cerrar un documento modificado permite cancelar, guardar y cerrar o cerrar sin guardar. Se conserva la convención CRLF al escribir cuando corresponde.
• Guardado atómico con permisos POSIX o ACL Windows preservados. En rutas UNC WSL (wsl.localhost / wsl$) usa wsl.exe y herramientas GNU de la distribución para conservar propietario, permisos y atributos. Si falla, no aplica un fallback inseguro.

Recuperación y privacidad de borradores #

Los documentos viven fuera de las vistas: alternar no los cierra. El storage durable del anfitrión guarda contenido, base y posición fuera del proyecto, con una entrada por instancia/generación. Al volver a abrir el editor puedes recuperar una entrada explícitamente; cancelar la conserva. Recuperar no guarda el archivo automáticamente.

Los borradores pueden contener código sensible; no son un almacén cifrado propio. Por nombre se excluyen .env y variantes, claves/certificados, credenciales, .npmrc, .pypirc y carpetas .aws/.ssh. No detecta secretos por contenido. drafts.exclude agrega patrones y drafts.enabled: false evita nuevas copias.

Desactivar o cambiar exclusiones no borra copias antiguas. Delete stored drafts for this project solicita confirmación y no borra archivos ni ediciones abiertas. La persistencia se difiere 300 ms, hasta dos segundos en edición continua; un cierre abrupto puede perder los cambios más recientes.

Ejemplo: desactivar recuperación #

{
  "drafts": {
    "enabled": false,
    "exclude": [
      "private/**",
      "**/service-account*.json"
    ]
  }
}

Alternativa: compilar una copia local #

Si necesitas cargar la fuente revisada en lugar de npm, usa un clon nuevo. Ejecuta desde la raíz de openeditorcode, no desde la web ni la subcarpeta del plugin. Bun es necesario para compilar.

git clone https://github.com/2jmalvarez/openeditorcode.git
cd openeditorcode
git checkout 84643031df30cbd4ee5552701012465eb49a8986
bun install --frozen-lockfile
bun run plugin:build

Cargar la carpeta compilada #

En Linux usa, por ejemplo, /home/usuario/Projects/openeditorcode/plugins/opencode-editor. Esta ruta instala el plugin, no fija el proyecto editado. Reemplaza solo package; no cargues la entrada local y npm a la vez. La confirmación de acceso sigue siendo necesaria.

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    {
      "package": "C:/Projects/openeditorcode/plugins/opencode-editor",
      "options": {
        "toggleBinding": "f6",
        "filesBinding": "f7",
        "diffBinding": "f8",
        "explorerWidth": 30
      }
    }
  ]
}

Límites y diferencias con OEC autónomo #

• Hasta 64 documentos abiertos; textos UTF-8 válidos, sin NUL y hasta 2 MiB al leer/guardar. Imágenes: 16 MiB. Rutas y symlinks deben permanecer dentro de la raíz autorizada. Workspaces remotos requieren override local explícito; no hay lectura remota.
• Borradores: 16 MiB por snapshot. Deshacer/rehacer pertenece al textarea y se reinicia al cambiar de archivo o desmontarlo; contenido, cursor y scroll sí se conservan. El scroll exacto del chat depende de OpenCode.
• Incluye rename, Markdown, SVG, imágenes y filtro por contenido; no incluye crear/eliminar archivos, búsqueda avanzada por líneas, reemplazo, formateo, multicursor ni mutaciones/historial/checkout Git. No hereda automáticamente todas las capacidades del editor autónomo.

Si algo no funciona #

Actualizar o desinstalar #

Guarda los archivos y cambia la versión fijada de package por otra publicación revisada; recarga o reinicia. En alternativa local revisa fuente y recompila. El launcher npm del editor autónomo no actualiza este plugin.

Para desinstalar elimina únicamente su entrada en plugins de cli.json y reinicia. No borra OEC autónomo ni archivos del proyecto. Los borradores son datos del anfitrión: elimínalos antes con la acción específica si lo deseas; no borres su base de datos ni todo su almacenamiento.