Agent Sessions — extensión de VS Code

Lista, previsualiza y reanuda en el terminal integrado tus sesiones de agentes de código (Claude Code, Codex, OpenCode, Gemini).

Es la mitad "gestor de sesiones" del proyecto aterm portada a VS Code. El editor ya pone el terminal, así que la extensión solo aporta la UI (un WebviewView en la barra lateral con cards a tamaño real, no un TreeView) y delega todo el descubrimiento, metadata y transferencia en el binario sidecar agent-sessions-cli, que comparte el núcleo Rust (agent-sessions) con la app nativa. Una sola fuente de verdad.

Arquitectura

VS Code (TypeScript)                  Rust (compartido con aterm)
┌─────────────────────────┐  spawn   ┌────────────────────────────┐
│ WebviewView (cards)      │ ───────▶ │ agent-sessions-cli (JSON)  │
│ comando "Reanudar"       │ ◀─────── │  └─ agent-sessions (core)  │
│  └─ window.createTerminal│  stdout  └────────────────────────────┘
└─────────────────────────┘

El sidecar es read-only para las sesiones (rutas derivadas del $HOME, nunca recibe paths del editor). Sí escribe en ~/.config/aterm/session-metadata.json (rename/tags/color) y en ~/.claude/projects/** al importar — los mismos sitios que usa la app nativa, así ambas UIs ven la misma metadata.

Funciona en VS Code y en sus forks (Cursor, VSCodium, Windsurf, …): se publica en el Marketplace de VS Code y en Open VSX.

Funcionalidades

Panel y navegación

• Panel de sesiones tipo card (avatar de proveedor, dos líneas de meta, acento de color del proyecto, acciones al hover) — no un TreeView.
• Agrupado por proveedor / proyecto (cwd) / cascada / fecha (Hoy, Ayer, …) / grupo (colecciones propias). En la vista por proyecto, los subproyectos (cwd descendientes) se anidan bajo su proyecto ancestro.
• Modo selección (multiselección con checkboxes): abrir varias sesiones, eliminar varias o agruparlas de una vez desde la barra de acciones.
• Modo compacto (toggle de densidad) para ver más sesiones de un vistazo.
• Plegar / desplegar todas las secciones con un botón.
• Paleta de acciones (Ctrl/Cmd+Alt+A): quick-pick de todas las sesiones → menú de acciones, sin ratón.
• Menú de acciones «⋯» en la barra del panel: todas las acciones de la extensión agrupadas, sin pasar por la paleta de comandos.
• Modelo visible por sesión; indicador "abierta" (el clic enfoca el terminal existente en vez de duplicar el resume).

Reanudar y lanzar

• Reanudar en el terminal integrado (clic o ▶) con el resumeArgv del proveedor.
• Reanudar con prompt y Continuar en otro agente (handoff) desde el menú.
• Nueva sesión eligiendo directorio (workspace / cwd conocido con alias / otra ruta), con acciones rápidas «nueva sesión aquí» y «abrir terminal aquí» en cada cabecera de proyecto.
• Nueva sesión en varios proyectos a la vez (un terminal por carpeta elegida).
• Smart-launch: agente recomendado según el cwd.
• Compactar contexto (»«, solo Claude): lanza /compact sin reanudar, o «compactar con instrucciones…» (un prompt que enfoca el resumen, /compact <texto>).
• Comandos del proyecto: explorador (botón en la cabecera de cada proyecto) que reúne, en secciones separadas, los slash-commands del proyecto (.claude/commands/**, versionados con el repo), los globales del usuario (~/.claude/commands/**), los scripts del repo (package.json/Makefile/justfile/Cargo) y las acciones de la extensión. Al lanzar un script puedes pasarle argumentos o ver su ayuda (--help) en vez de ejecutarlo a ciegas.
• Comandos globales de usuario: acceso propio (menú «⋯» / comando) a los slash-commands de ~/.claude/commands, independiente de un proyecto: eliges dónde lanzarlos.
• Terminal Profiles por proveedor en el desplegable + del terminal.
• Plantillas de lanzamiento con etiquetas y cwd · comparativa paralela con un git worktree por agente. (funciones Pro — ver más abajo)

Búsqueda y filtros

• Filtro con predicados: provider:, model:, cwd:, branch:, #tag, cost>, tokens>, ctx>, age<, has:notes|favorite|persisted, active:true.
• Filtros rápidos: botón «solo activos» y popover «por etiqueta».
• Búsqueda en el contenido (FTS) dentro del panel: el botón 🔍 usa el filtro como query y muestra los resultados con el fragmento resaltado.

Metadata y organización

• Renombrar, etiquetas (+ catálogo de tags reutilizables), color, notas, favoritos e icono/emoji por sesión. Compartido con la app nativa (el icono se guarda en el estado de la extensión).
• Grupos manuales: colecciones propias (nombre + color + icono) para agrupar sesiones; asignación por menú, por la barra de multiselección o arrastrando la card a un bucket de grupo, con su propia vista «por grupo».
• Proyectos: alias, color e icono por cwd; drag & drop de Claude entre proyectos; añadir la carpeta del proyecto al workspace de VS Code con un clic.
• Eliminar sesiones: una a una, en multiselección, o por fecha («más antiguas que N días»).

Persistencia y transferencia

• ⭐ Persistir sesiones (Persistir en el menú): guarda una copia durable bajo ~/.config/aterm/archive que sobrevive aunque el proveedor borre el original por inactividad. La sesión sigue en el panel (badge naranja) y, al reanudarla, se restaura al vuelo a la ruta que Claude espera. (Restaurar/ reanudar: Claude por ahora.)
• Export a .zip (byte-compatible con multi-claude) e import (Claude).
• Backup/restore del catálogo (metadata + proyectos + plantillas).
• Copiar/guardar la conversación como Markdown.

Costes y monitorización

• Quota del proveedor: pill de % con cuenta atrás hasta el reset. El uso 5h/7d se obtiene de la fuente nativa de Claude o, si falta, del endpoint oficial de uso de Anthropic con cache propio — sin depender de plugins de terceros.
• Dashboard con KPIs (sesiones, coste $, tokens), barras por proveedor/proyecto y sparkline de 30 días.
• Alerta de coste diario + indicador en la barra de estado.
• Estado del servicio como badge junto al nombre del proveedor; al pulsarlo abre su página de estado (Claude, Codex, Gemini, OpenCode). Notificaciones idle/finish con nivel configurable (notificationLevel: todas / importantes / errores / ninguna; los diálogos de confirmación nunca se silencian).
• % de contexto por sesión; en Claude la ventana es fijable (claudeContextWindow: auto / 200k / 1M) para que el porcentaje no se infle en cuentas con ventana de 1M.

Integración

• MCP server (agent-sessions-cli serve, OSS) + comando «Configurar servidor MCP…» (Pro) que lo registra con un clic. El servidor en sí es libre (puedes lanzarlo y configurarlo a mano, ver "Uso como MCP"); la conveniencia de registrarlo desde la extensión requiere licencia Pro.
• Previsualizar la conversación en un panel estilado (turnos en burbujas con cabecera de metadatos y render Markdown), reutilizable entre sesiones.
• Auto-localización del sidecar (empaquetado en el .vsix o target/).

Edición Pro

La extensión es open-core: casi todo es gratis. Unas pocas funciones avanzadas son Pro:

• Gráfico de memoria: mapea la jerarquía de memoria del proveedor (global / proyecto / local + directorio de memoria) como árbol o vista de secciones, con preview estructurada de cada .md. Crear/añadir/borrar/notas: el agente redacta y la extensión guarda (con tu confirmación). Botón por proyecto.
• Ejecutar scripts del proyecto (npm / Make / justfile / Cargo), agrupados por intérprete, con inferencia de argumentos y parseo de --help para CLIs seguros (cargo, python, uv, pytest…). (Los slash-commands del agente son gratis.)
• Comparativa paralela (un agente por git worktree) + comparar/limpiar worktrees.
• Plantillas de lanzamiento (guardar / lanzar / gestionar).
• Perfiles de espacio de trabajo: guarda un conjunto de sesiones y reábrelas todas de un clic (restaura el entorno de un proyecto en segundos).
• Dashboard Pro: informe visual (panel con gráficas — donut por proveedor, barras de proyectos/modelos, sparkline 30d) con filtros por rango de fecha y export a CSV. Accesible desde el botón «Informe avanzado (Pro)» del panel de estadísticas. (Los presupuestos admin→equipo se reservan para un futuro tier Team.)
• Exportar conversación a HTML estilado (para compartir/archivar; PDF vía imprimir).
• Automatizaciones: aviso cuando una sesión lleva idle más de N minutos (pro.idleAlertMin) y resumen diario de actividad/coste.
• Configurar servidor MCP con un clic: registra el servidor MCP en .vscode/mcp.json (o copia el snippet) desde la extensión. El servidor en sí (agent-sessions-cli serve) es OSS y puedes configurarlo a mano gratis.
• Portar sesión entre proveedores: lleva una conversación de un agente a otro. Genera un hand-off con la transcripción completa y lanza el proveedor destino sembrado con ese contexto. OpenCode vale como destino, no como origen (su contenido no es legible desde disco).
• Duplicar proyecto para otro proveedor: clona la carpeta del proyecto y convierte su configuración de agente a las convenciones del destino — fichero de instrucciones (CLAUDE.md ↔ AGENTS.md ↔ GEMINI.md) y comandos personalizados (.claude/commands/*.md ↔ .gemini/commands/*.toml ↔ .opencode/command/*.md, incluidos los placeholders de argumentos). Excluye node_modules/build, conserva .git y deja un PORT-NOTES.md.

Hay una prueba de 14 días; un indicador en la barra de estado muestra «Pro / Prueba Nd / Activar Pro». Después de la prueba, esas acciones piden activar una licencia (las demás siguen gratis). Activa con «Agent Sessions: Activar licencia Pro…» y consulta el estado con «Estado de la licencia Pro».

Licencias (Lemon Squeezy)

Las claves son license keys de Lemon Squeezy: el comprador las recibe automáticamente al pagar y la extensión las valida online contra la License API pública de Lemon Squeezy (no requiere API key ni servidor propio). La validación se cachea, así que el gate funciona offline tras la primera activación.

Hay dos planes (anual y mensual); al pulsar «Comprar Pro» se elige plan y se abre su checkout. Configura en src/license.ts antes de publicar:

• BUY_URL_ANNUAL / BUY_URL_MONTHLY: enlaces de checkout de Lemon Squeezy.
• PRODUCT_ID (opcional): restringe las claves aceptadas a tu producto.

Instalar

Desde un .vsix

code --install-extension agent-sessions-<plataforma>-<versión>.vsix

El .vsix lleva el sidecar dentro, así que no necesitas compilar nada más.

En desarrollo (F5)

El core Rust (que produce el sidecar) vive como submodule en ./aterm. Clónalo recursivamente o inicialízalo:

git clone --recurse-submodules git@github.com:Aterm-labs/agent-sessions.git
# o, si ya lo tienes clonado:
git submodule update --init --recursive

Abre esta carpeta en VS Code y pulsa F5. La extensión auto-localiza el sidecar en aterm/target/release/agent-sessions-cli (o debug/…); si no existe, compílalo:

cargo build --release -p agent-sessions-cli --manifest-path aterm/Cargo.toml

O fija agentSessions.cliPath a una ruta concreta en los ajustes.

Empaquetar el .vsix

cd vscode-extension
npm install
./scripts/build-vsix.sh                 # auto-detecta plataforma host
./scripts/build-vsix.sh darwin-arm64    # explícito (requiere cross-compile)

El script construye agent-sessions-cli para el target indicado, lo deposita en bin/<rust-triple>/ y llama a vsce package --target <vsce-target>. El resultado es un .vsix específico de plataforma, listo para subir al Marketplace o compartir.

Targets soportados: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64, win32-arm64. Para release multiplataforma corre el script una vez por target en el host correspondiente (o vía CI con cross-compile).

Uso como MCP server

El sidecar incluye un modo serve que habla JSON-RPC 2.0 sobre stdio (protocolo MCP 2024-11-05) y expone tres tools al propio agente:

• list_sessions(provider?, cwd?, limit?) → resumen de sesiones recientes.
• get_session_turns(provider, id, limit?) → turnos user/assistant.
• search_sessions(query, limit?) → match contra título/cwd/branch/tags.

Pro. Las tools del MCP requieren licencia Pro (o la prueba de 14 días). El gate lo controla la extensión, que al activar/validar la licencia escribe ~/.config/aterm/pro-license.json; el servidor serve lo lee y, sin Pro válido, anuncia cero tools y rechaza las llamadas. El binario es OSS, así que es un gate de cortesía, no inviolable.

Para registrarlo con Claude Code (~/.claude/mcp.json):

{
  "mcpServers": {
    "agent-sessions": {
      "command": "/ruta/a/agent-sessions-cli",
      "args": ["serve"]
    }
  }
}

Tras reiniciar Claude Code, el agente puede pedirse a sí mismo "busca en mis sesiones donde toqué transfer.rs" y obtener un listado real con título, cwd y modelo. Codex/OpenCode/Gemini se configuran de forma análoga si soportan MCP.

Ajustes