Sistemas de Plugins en Programación Agentica: OpenCode, Codex CLI y Claude Code — Clase Magistral

1 Introducción — Las 3 Plataformas y sus Filosofías

Tres plataformas compiten hoy por ser el entorno definitivo para programación agentica asistida por IA. Cada una tiene una filosofía distinta, un ecosistema de plugins diferente, y —lo más importante— un modelo mental particular sobre qué significa "extender" la plataforma.

Analicemos las capacidades reales de cada plataforma desde sus fundamentos arquitectónicos. No se trata de declarar un ganador absoluto, sino de entender dónde se pueden construir extensiones, qué tipo de extensiones permite cada una, y cómo portar un plugin entre las tres con el mínimo esfuerzo.

Filosofías de Extensibilidad

Cada plataforma responde una pregunta distinta sobre la extensibilidad:

• OpenCode pregunta: "¿Qué hooks necesita un desarrollador para modificar cualquier aspecto del pipeline?" — Su respuesta son 17 hooks asíncronos que cubren desde la modificación del mensaje hasta la configuración global, pasando por proveedores y autorización.
• Codex CLI pregunta: "¿Cómo construimos un ecosistema enterprise con plugins seguros y multi-lenguaje?" — Su respuesta es un ciclo de vida de plugin con init/start/stop, manifests explícitos, y SDK para Python, TypeScript, Go y Java.
• Claude Code pregunta: "¿Cómo creamos la experiencia de desarrollo más pulida para extender el agente?" — Su respuesta incluye ~30 hooks CLI, marketplace funcional, edict remoto, y la documentación más completa del ecosistema.

2 OpenCode — Sistema de Plugins

OpenCode implementa un sistema de plugins basado en middleware asíncrono. Cada plugin es una función que recibe un contexto (PluginInput) y devuelve un objeto con hooks. La plataforma ofrece 17 hooks que cubren prácticamente todos los puntos de extensión del pipeline de conversación.

Los 17 Hooks

Cada hook es un punto de extensión en el pipeline de la conversación. Los hooks reciben un contexto y pueden devolver modificaciones parciales o completas del comportamiento.

Arquitectura del Plugin System

En OpenCode, un plugin es simplemente una función que recibe PluginInput y devuelve hooks:

type Plugin = (
  input: PluginInput,
  options?: PluginOptions
) => Promise<Hooks>

PluginInput completo

El contexto que OpenCode inyecta a cada plugin contiene:

interface PluginInput {
  client: Client              // Cliente LLM (OpenAI, Anthropic, etc.)
  project: Project           // Proyecto actual
  directory: string          // Directorio del proyecto
  worktree: string           // Worktree de git (si aplica)
  experimental_workspace: Workspace  // Workspace experimental
  serverUrl: string          // URL del servidor MCP/local
  $: typeof Bun.$            // Template literal para shell
}

Carga y Descubrimiento de Plugins

OpenCode descubre plugins mediante tres mecanismos:

1. Auto-descubrimiento local — Archivos .ts/.js en .opencode/plugins/ se cargan automáticamente al iniciar, sin necesidad de declararlos. El nombre canónico del directorio es plugins (plural), aunque plugin (singular) también se acepta por retrocompatibilidad. También escanea ~/.config/opencode/plugins/ a nivel global. El patrón es {plugin,plugins}/*.{ts,js} (solo primer nivel).
2. Paquetes npm — Vía array "plugins" en opencode.json con nombres de paquetes npm.
3. Rutas explícitas — Vía array "plugins" en opencode.json con URLs file:// o rutas absolutas.

Soporta hot reload nativo: los cambios en plugins se reflejan sin reiniciar la sesión. Esto es único entre las tres plataformas.

Caso de Estudio: opencode-model-fallback

Este plugin en producción usa 3 hooks para implementar failover automático entre modelos LLM. Veamos cómo funciona:

import { Plugin, PluginInput } from "opencode/plugin";

interface Config {
  fallbackModels: Record<string, string[]>;
  cooldownMs: number;
  retryOriginalAfterMs: number;
  maxFallbackDepth: number;
}

const state = new Map<string, {
  currentModel: string;
  depth: number;
  lastFallbackAt: number;
}>();

export const plugin: Plugin = async (input: PluginInput, options?: Config) => ({
  async event({ type, payload, sessionId }) {
    if (["rate_limit", "quota_exceeded", "5xx", "timeout", "overloaded"]
      .includes(type)) {
      const s = state.get(sessionId) ?? {
        currentModel: payload.model,
        depth: 0, lastFallbackAt: Date.now()
      };
      s.depth++; s.lastFallbackAt = Date.now();
      state.set(sessionId, s);
    }
  },

  async chat.message({ messages, sessionId, variant }) {
    const s = state.get(sessionId);
    if (!s || s.depth === 0) return { messages };
    const agentName = variant ?? "default";
    const fallbacks = options?.fallbackModels?.[agentName];
    const fallbackIdx = Math.min(s.depth - 1, (fallbacks?.length ?? 1) - 1);
    if (fallbacks?.[fallbackIdx] && s.depth <= (options?.maxFallbackDepth ?? 3)) {
      return { messages, variant: fallbacks[fallbackIdx] };
    }
    return { messages };
  },

  async tool.execute.after({ sessionId, result }) {
    const s = state.get(sessionId);
    if (s && s.depth > 0 && !result.isError) {
      setTimeout(() => { s.depth = 0; s.currentModel = ""; },
        options?.retryOriginalAfterMs ?? 900000);
    }
    return { result };
  }
});

El patrón —detectar evento → modificar mensaje → verificar éxito— es reproducible en las 3 plataformas con adaptaciones mínimas en la capa de integración, aunque el cambio de modelo en runtime es exclusivo de OpenCode.

3 Codex CLI — Sistema de Plugins

Codex CLI, la plataforma de OpenAI, implementa un sistema de plugins con un enfoque enterprise: ciclo de vida explícito, manifests con metadatos, y un SDK multi-lenguaje que permite escribir plugins en Python, TypeScript, Go y Java.

Ciclo de Vida del Plugin

Cada plugin en Codex CLI pasa por tres fases:

A diferencia de OpenCode (donde el plugin es una función pura), en Codex CLI el plugin es una clase que extiende CodexPlugin y puede mantener estado interno con un ciclo de vida gestionado por la plataforma.

Manifest: plugin.json

Cada plugin de Codex CLI requiere un manifest explícito:

{
  "name": "model-fallback",
  "version": "1.0.0",
  "description": "Automatic model failover",
  "hooks": ["onError", "postExec"],
  "env": {
    "FALLBACK_COOLDOWN_MS": "300000"
  },
  "permissions": ["network", "fs.read"]
}

Puntos de Extensión

Los plugins de Codex CLI pueden integrarse mediante:

• MCP tools — El mecanismo principal. Los plugins exponen herramientas como servidores MCP que el agente puede invocar. Soporta validación JSON Schema.
• Plugin hooks — Puntos de extensión en el ciclo de vida del agente: onError, postExec, preMessage.
• Background workers — Procesos asíncronos que el plugin puede lanzar durante start() para monitoreo, watch mode, o tareas periódicas.
• Resource templates — Para modificar el system prompt vía MCP resources.

SDK Multi-Lenguaje

Codex CLI es la única plataforma que ofrece un SDK oficial para múltiples lenguajes:

Marketplace Emergente

OpenAI está construyendo un registry de plugins para Codex CLI. Los plugins se pueden descubrir y compartir via el sistema de manifests, aunque el marketplace aún está en fase emergente. La carga puede ser desde un registry o desde rutas locales definidas en codex.json.

4 Claude Code — Sistema de Plugins

Claude Code, también de Anthropic, tiene el ecosistema de plugins más maduro de las tres plataformas. Con aproximadamente 30 hooks CLI, un marketplace funcional, y el protocolo MCP como columna vertebral, representa el estado del arte en extensibilidad agentica desde la perspectiva de producto.

Arquitectura de Hooks

Claude Code expone hooks CLI que se declaran en claude.json y se ejecutan en puntos específicos del pipeline:

Manifest: claude.json

Los plugins de Claude Code se declaran con un archivo de configuración similar a Codex pero con un ecosistema más estandarizado:

{
  "name": "model-fallback",
  "version": "1.0.0",
  "hooks": {
    "pre_message": "./hooks/pre-message.js",
    "post_tool": "./hooks/post-tool.js"
  },
  "env": { "FALLBACK_COOLDOWN_MS": "300000" },
  "mcp_servers": ["./mcp/server.js"]
}

Capacidades Distintivas

• Edict remoto — Un mecanismo único para modificar el comportamiento del agente a través de instrucciones remotas que se inyectan en tiempo real. No requiere despliegue de plugins.
• Claude Marketplace — El marketplace más maduro de los tres. Los plugins se publican, versionan y descubren desde una interfaz centralizada.
• MCP nativo — Claude Code fue diseñado desde el inicio con el Model Context Protocol como ciudadano de primera clase. Cualquier servidor MCP es automáticamente un plugin.
• LSP bundling — Integración nativa con Language Server Protocol para edición inteligente de código, completado y diagnósticos.
• Watch mode — Monitoreo de archivos en background para re-ejecutar tareas automáticamente ante cambios.

Detección de Plugins

Claude Code descubre plugins mediante escaneo de node_modules/ (paquetes @anthropic-ai/*) y configuración explícita en claude.json. No soporta hot reload — los cambios requieren reiniciar el agente.

5 Comparativa Cross-Platform

Las diferencias no están en "quién tiene más features", sino en dónde cada plataforma pone los límites de extensibilidad. Veamos la tabla más completa hasta la fecha:

Fortalezas de OpenCode

• ✔ Extensibilidad profunda: Es la única plataforma que permite modificar el modelo, los parámetros LLM, el system prompt y la configuración global en runtime desde un hook.
• ✔ Model-agnóstico: OpenCode funciona con OpenAI, Anthropic, Google, OpenRouter, Ollama y providers locales. Codex solo OpenAI, Claude solo Anthropic.
• ✔ Open Source: MIT License. Puedes forkear, auditar, modificar. Las otras tienen restricciones.
• ✔ Plugin system más potente: 17 hooks, 14 modifican comportamiento. La competencia no se acerca en este aspecto.

Debilidades de OpenCode

• ✘ Marketplace: No tiene. Claude Code tiene Claude Marketplace, Codex tiene registry emergente. OpenCode confía en npm.
• ✘ Plugin manifest: No tiene formato explícito. Los plugins se cargan desde .opencode/plugins/ por auto-descubrimiento o vía opencode.json.
• ✘ Monitors background: No tiene workers en background. Los hooks son síncronos. Codex y Claude tienen watch mode nativo.
• ✘ Documentación: La documentación de OpenCode es más escasa y está menos organizada que la de Claude Code.
• ✘ LSP bundling: No tiene SDK multi-lenguaje. Si quieres un tool en Python, tienes que gestionar el subproceso tú mismo.

6 Tabla de Equivalencias

Este es el mapa que necesitas para portar un plugin entre las 3 plataformas. Cada fila es una capacidad que quieres implementar y cómo se logra en cada plataforma:

7 Estrategia Cross-Platform

La estrategia para construir plugins que funcionen en las tres plataformas no es "elegir una y adaptar", sino Core-First: aislar la lógica portable en un núcleo independiente y construir adapters específicos para cada plataforma.

Core Layer (100% portable entre plataformas)

Este código se escribe una vez y funciona en todas partes:

• Lógica de negocio — detección de errores, colas, rate limiting, cooldown, scoring
• State management — mapas de sesión, contadores, timestamps
• Modelos de datos — interfaces, types, validación Zod
• Algoritmos — selección de fallback, rotación, lógica de decisión

Platform Adapter Layer (lo que cambia por plataforma)

Lo que realmente cambia por plataforma

No es la lógica de negocio. Es dónde y cómo te conectas al pipeline:

8 Conclusión y Lecciones Aprendidas

No hay un ganador absoluto. Hay ganadores por categoría:

La lección más importante de esta clase magistral es metodológica: cuando analices arquitecturas de software, no te detengas en la documentación superficial. El código fuente es la única fuente de verdad. La documentación miente por omisión; el código fuente no.

El sistema de plugins de OpenCode es significativamente más potente de lo que su documentación superficial sugiere. Codex CLI tiene un SDK multi-lenguaje que ninguna otra plataforma iguala. Claude Code tiene el marketplace y la experiencia de desarrollo más madura. Cada una gana en una dimensión distinta, y la estrategia correcta no es elegir una, sino diseñar para portabilidad desde el día 1.

El patrón Core-First permite que ~80% del código de un plugin viaje entre plataformas sin cambios. Los adapters específicos (ese ~20% restante) son el precio justo por acceder a las capacidades únicas de cada ecosistema.

📚 Fuentes y Referencias

Todas las afirmaciones en esta clase están respaldadas por documentación oficial y código fuente verificable.

OpenCode

• Documentación oficial de Plugins — Plugin API, hooks, directorios de carga, ejemplo model-fallback
• Documentación oficial de Configuración — Formato opencode.json, load order, schema de plugins
• @opencode-ai/plugin en npm — SDK oficial para crear plugins y custom tools
• Código fuente en GitHub — Repositorio oficial (MIT License)

Codex CLI (OpenAI)

• Documentación oficial: Build a plugin — Manifest format, estructura, marketplace
• Documentación oficial: Plugins overview — Instalación, plugin directory, CLI commands
• Documentación oficial: Hooks — Lifecycle events, trust flow, managed hooks
• Código fuente en GitHub — Repositorio oficial (Rust core, 90K+ estrellas)

Claude Code (Anthropic)

• Documentación oficial de Plugins — Manifest, estructura, scaffolding, marketplaces
• Documentación oficial de Hooks — Lifecycle events, tipos de hook, ubicaciones
• Documentación oficial de MCP — Transportes, CLI, plugin integration, tool search
• Documentación oficial de Settings — 125+ keys, precedencia, formatos
• Documentación oficial de Skills — SKILL.md format, progressive disclosure
• Documentación oficial de Subagents — Definición, campos, aislamiento
• Plugins oficiales en GitHub — Repositorio curado por Anthropic
• Plugins comunitarios en GitHub — Catálogo de la comunidad

MCP (Model Context Protocol)

• Especificación oficial MCP — JSON-RPC 2.0, transportes, seguridad
• GitHub — Model Context Protocol — SDKs, servidores, especificación

SDKs y Paquetes

• @opencode-ai/plugin — SDK de plugins para OpenCode
• opencode-model-fallback — Plugin de fallback de modelos (implementación real de referencia)
• @modelcontextprotocol/sdk — SDK oficial de MCP para TypeScript
• Paquete Python mcp — SDK oficial de MCP para Python con FastMCP

Última verificación: Junio 2026. Las especificaciones y documentación pueden cambiar; consulte las fuentes oficiales para información actualizada.