opencode-session-state

Plugin para OpenCode que mantiene un estado inteligente de la sesión para preservar contexto tras compactaciones, cambios de modelo o sesiones largas.

Por qué

OpenCode y otros agentes LLM pierden contexto tras compactar la ventana, cambiar de modelo, o en sesiones largas. Este plugin:

• Detecta automáticamente cambios de tema y crea episodios
• Resume de forma incremental (nunca relee toda la conversación)
• Inyecta el estado en el system prompt antes de cada petición
• Preserva el contexto durante las compactaciones
• Expone una herramienta session_state para inspeccionar el estado

Instalación

Hay dos métodos equivalentes. Elige según tu flujo de trabajo.

Método A — Via npm (recomendado para usuarios finales)

npm install -g opencode-session-state

Añade el plugin a tu opencode.json (global en ~/.config/opencode/opencode.json o de proyecto):

{
  "plugin": [
    [
      "opencode-session-state",
      {
        "temperature": 0.1,
        "logging": "info"
      }
    ]
  ]
}

Copia el comando /session-state a tu directorio de comandos:

# Linux/macOS:
cp node_modules/opencode-session-state/commands/session-state.md ~/.config/opencode/commands/

# Windows (PowerShell):
Copy-Item node_modules/opencode-session-state/commands/session-state.md $env:USERPROFILE\.config\opencode\commands\

Reinicia OpenCode.

Método B — Via GitHub (desarrollo/contribuidores)

git clone https://github.com/tmogeid/opencode-session-state.git
cd opencode-session-state
npm install
npm run build

Enlaza en opencode.json con la ruta absoluta al dist/index.js:

{
  "plugin": [
    [
      "/ruta/absoluta/a/opencode-session-state/dist/index.js",
      {
        "temperature": 0.1,
        "logging": "info"
      }
    ]
  ]
}

Copia el comando /session-state:

# Linux/macOS:
cp commands/session-state.md ~/.config/opencode/commands/

# Windows (PowerShell):
Copy-Item commands\session-state.md $env:USERPROFILE\.config\opencode\commands\

Reinicia OpenCode.

Modelo predeterminado

El plugin usa un LLM para resumir incrementalmente la conversación. El modelo por defecto es:

meta/llama-3.1-8b-instruct (NVIDIA)

• Model ID: meta/llama-3.1-8b-instruct
• Endpoint: https://integrate.api.nvidia.com/v1
• Precio: Gratis (NVIDIA build.nvidia.com free tier)
• Cómo obtener la API key:
  1. Visita build.nvidia.com
  2. Inicia sesión y genera una API key
  3. La key tendrá formato nvapi-...
  4. Configúrala como variable de entorno:

# Linux/macOS:
export NVIDIA_API_KEY=nvapi-...

# Windows (PowerShell sesión actual):
$env:NVIDIA_API_KEY='nvapi-...'

# Windows (persistente):
[Environment]::SetEnvironmentVariable('NVIDIA_API_KEY', 'nvapi-...', 'User')

No necesitas configurar model ni apiBaseUrl — el plugin funciona out-of-the-box con la variable de entorno configurada.

Configuración mínima:

{
  "plugin": [
    [
      "opencode-session-state",
      {
        "temperature": 0.1,
        "logging": "info"
      }
    ]
  ]
}

API Key

El plugin busca la API key en este orden:

1. apiKey explícita en la config del plugin
2. NVIDIA_API_KEY (env var, RECOMENDADA)
3. OPENROUTER_API_KEY (env var, alternativa)
4. OPENAI_API_KEY (env var, fallback)

Mejor usar env vars que pasar la key directamente en la config (por seguridad).

Configuración

Todas las opciones configurables:

Opción	Tipo	Default	Descripción
model	string	meta/llama-3.1-8b-instruct	Modelo LLM para resúmenes
apiBaseUrl	string	https://integrate.api.nvidia.com/v1	URL base de la API
apiKey	string	(env vars)	API key explícita
temperature	number	0.1	Temperatura del modelo
maxTokens	number	2000	Tokens máximos por llamada
maxEpisodes	number	4	Máximo de episodios
maxStateTokens	number	5000	Máximo tokens del estado
logging	string	info	Nivel: debug, info, warn, error
storageDir	string	.session-state	Directorio para archivos
injection	boolean	true	Inyectar estado en system prompt
autoSummary	boolean	true	Resumen automático via LLM
summarizerInterval	number	30000	Intervalo mínimo (ms)

Cómo funciona

Mensaje usuario → chat.message hook → SessionManager:
  1. Encola turno en pendingTurns
  2. Detecta cambio de tema → crea episodio
  3. Aplica heurísticas (archivos, errores, decisiones)
  4. Cada 30s y ≥2 turnos → LLM resume incremental
     → mergeStateUpdate + persistencia a disco

Respuesta asistente → event/message.updated → SessionManager:
  1. Encola respuesta
  2. Extrae conclusiones heurísticas
  3. Trigger summarizer si aplica

Antes de cada prompt → system.transform hook:
  → formatStateAsXml(state) → inyecta en system prompt

Estado de sesión

Archivos JSON individuales en .session-state/<sessionId>.json:

Campo	Descripción
currentTask	Tarea actual detectada
currentObjective	Objetivo actual
mainTopic	Tema principal del episodio
episodes[]	Lista de episodios
decisions[]	Decisiones tomadas
pendingTasks[]	Tareas pendientes
importantFiles[]	Archivos mencionados
knownErrors[]	Errores conocidos
risks[]	Riesgos identificados
nextSteps[]	Próximos pasos
conclusions[]	Conclusiones

Herramienta session_state

Acción	Descripción
ver (default)	Estado completo formateado
resumen	Episodio activo actual
episodios	Lista de todos los episodios
limpiar	Eliminar sesiones archivadas >30 días

Logs

Los logs van a .session-state/logs/<YYYY-MM-DD>.log:

• DEBUG/INFO → solo archivo (no molesta al TUI)
• WARN → console.warn (silencioso en UI)
• ERROR → console.warn + toast notification

Hooks de OpenCode

Hook	Propósito
tool	Herramienta session_state
chat.message	Mensajes del usuario
event	Lifecycle de sesiones
experimental.chat.system.transform	Inyectar estado
experimental.session.compacting	Preservar en compactación
experimental.compaction.autocontinue	Continuar post-compactación

Arquitectura del código

src/
├── index.ts              # Entry point — hooks
├── config.ts             # Configuración defaults + merge
├── logger.ts             # Logging archivo + toast
├── state-store.ts        # Persistencia JSON por sesión
├── session-manager.ts    # Orquestador principal
├── episode-detector.ts   # Detección cambios de tema
├── summarizer.ts         # LLM incremental summarization
├── context-injector.ts   # Formateo XML para system prompt
└── tools/
    └── session-state.ts  # Herramienta ver/resumen/episodios/limpiar

Licencia

GPL-3.0 — Copyright (c) 2026 tmogeid

Repositorio

• Código: github.com/tmogeid/opencode-session-state
• Issues: github.com/tmogeid/opencode-session-state/issues
• npm: npmjs.com/package/opencode-session-state