OSS · Plugin de Claude Code

compact-ops

Después de /compact, tu agente olvida lo que estaba haciendo.

compact-ops escribe un archivo de estado estructurado de 10 secciones antes de cada compactación y lo inyecta de vuelta justo después del compact y en claude --resume. Solo hooks oficiales, todos fail-open. Instálalo una vez y luego usa /compact como siempre.

Deja el summary intacto. El seguro se pone por fuera.

Descargar en GitHub Cómo funciona →

Gratis · MIT · solo hooks oficiales · nada sale de tu máquina salvo tu propia llamada al CLI claude

  • 10 secciones fijas por archivo de estado
  • 60% de aviso de uso, umbral configurable
  • 72h de ventana de fallback en resume
  • 30d de retención del estado en disco
  • Sin descarrilar tras el compact el agente retoma con summary + estado, dos pistas en lugar de una
  • Sin auto-compact sorpresa un aviso al 60% con recitación de 3 líneas: plan, fase, última decisión
  • Sobrevive a un reinicio del PC claude --resume reinyecta el estado más reciente dentro de 72 horas
  • No rompe nada al romperse todos los hooks son fail-open; la compactación estándar siempre pasa
Demo en terminal: nombres reales de eventos de hooks.json, una ejecución real del hook de backup del PreCompact con una reducción de bytes real, y la estructura de 10 secciones de un archivo de estado real

Cuatro hooks, sin daemon

Cada uno de estos es un evento de hook oficial de Claude Code. Sin proceso en segundo plano, sin polling.

  • PreCompact Respalda el transcript (gzip) y un LLM escribe el archivo de estado de 10 secciones
  • PostCompact Reinicia el cooldown del aviso de uso
  • SessionStart matcher compact | resume: inyecta el archivo de estado y la nota de relectura de los originales
  • UserPromptSubmit Calcula el uso de contexto desde el transcript; avisa una sola vez al superar el umbral

Los cuatro son fail-open. Si los cuatro fallan, la compactación corre exactamente como si compact-ops nunca se hubiera instalado.

Tres pasos

  1. claude plugin install compact-ops Clona el repo, añádelo como marketplace local, instala. Una sola vez.
  2. /compact Compacta como siempre. El PreCompact respalda el transcript y escribe el archivo de estado solo.
  3. recuperación inyectada El contexto nuevo recibe el estado, una nota para releer los originales y la lista de skills invocadas.

Para quién es

  • Usuarios intensivos de Claude Code con sesiones que cruzan una o más compactaciones al día
  • Operadores de agentes que corren sesiones largas o programadas y las retoman al día siguiente con claude --resume
  • Equipos que traspasan sesiones el archivo de estado es Markdown puro que un humano lee como nota de traspaso
  • Autores de hooks un ejemplo completo de plugin hecho solo con hooks oficiales, fail-open de punta a punta

Cuándo usarlo

  • Cuando el auto-compact ya se tragó una decisión a mitad de tarea: el aviso al 60% te deja elegir el momento
  • Antes de trabajos de varios días: el estado sobrevive a la compactación, al cierre de la sesión y a un reinicio del PC
  • Cuando el agente vuelve a pedir una aprobación que ya tenía, o repite un enfoque que ya falló: esas son exactamente las secciones fijas del archivo de estado
  • Si alguna vez le dijiste a un agente pos-compact "eso ya lo decidimos", este plugin existe para ese incidente

Instalación

git clone https://github.com/kenimo49/compact-ops.git
claude plugin marketplace add /path/to/compact-ops --scope user
claude plugin install compact-ops@compact-ops-local

Requiere Claude Code v2.x, jq y el CLI claude como backend de LLM. Soporta Linux y macOS. Después de instalar, basta ejecutar /compact como siempre; los hooks se encargan del resto.

Qué hace

  • PreCompact: respalda el transcript (gzip, el JSONL se reduce a cerca de 1/10) y un LLM escribe un archivo de estado con 10 secciones: plan activo, decisiones, bloqueos, archivos en edición e intentos fallidos
  • Justo después de la compactación: inyecta en el contexto nuevo el archivo de estado, una nota para releer los originales y la lista de skills ya invocadas
  • En claude --resume: la misma inyección de recuperación, con fallback al estado más reciente del proyecto dentro de 72 horas, sobreviviendo a un reinicio del PC
  • Aviso de uso de contexto calculado por el propio plugin (por defecto 60%): recomienda /compact una sola vez, con recitación de 3 líneas del plan, la fase y la última decisión
  • El estado persiste en ~/.claude/compact-ops/ con retención de 30 días, organizado por proyecto; el session_id pasa una validación de allowlist antes de usarse en una ruta
  • La salida del LLM se valida en las 10 secciones antes de escribirse; una salida inválida conserva el estado anterior y falla en abierto
  • Derivado de u-ichi/compact-plus (MIT), hecho autocontenido: sin scripts externos de statusline y con backends de LLM solo en Claude (Sonnet primario, Haiku de fallback)

Con y sin compact-ops

Mismo algoritmo de compactación, mismo summary integrado. La diferencia es todo lo que hay alrededor.

MomentoClaude Code a secasCon compact-ops
El uso pasa del 60% Sin aviso. El auto-compact llega sin anunciarse Una notificación + recitación de 3 líneas: plan, fase, última decisión
El compact en sí El prompt integrado genera el summary; contenido no controlable La misma compresión, más backup del transcript y un estado de 10 secciones
Justo después del compact El agente sigue solo con el summary Estado + nota de relectura de los originales inyectados en el contexto nuevo
Tras cerrar la sesión El summary solo existe dentro de esa sesión El estado queda 30 días en disco y se inyecta en claude --resume
Cuando un hook falla — Fail-open: la compactación estándar pasa intacta

Fuente: el README del proyecto. El algoritmo de compresión queda intocado; todo son hooks oficiales acoplados desde fuera.

Cómo queda el archivo de estado

Captura de pantalla del terminal: las 10 secciones de un archivo de estado real de compact-ops, desde Active Plan y Session Decisions hasta Failed Attempts y Recovery Notes
Un archivo de estado real, solo los títulos (el cuerpo contiene la conversación, así que queda privado). Esta misma página se revisó a lo largo de dos compactaciones, retomada desde archivos como este.

Uso

# compacta como siempre, los hooks se encargan del resto
/compact

# los argumentos se vuelven guía prioritaria para el generador de estado
/compact conserva todas las decisiones de diseño

# ajusta con el bloque env de ~/.claude/settings.json
COMPACT_OPS_WARN_THRESHOLD=70
COMPACT_OPS_PRIMARY_BACKEND=""
COMPACT_OPS_DEBUG=1

Probado en campo en su propio lanzamiento

El primer beneficiario fue la sesión que lo construyó. Tres momentos de uso real, sin montaje:

  • Durante el trabajo de release de la v0.2.0, el propio aviso del 60% saltó al 67% dentro de la misma sesión que hacía el release: el autor escribió el aviso y fue salvado por él esa misma noche.
  • Minutos después, una reorganización de directorios rompió tres de sus hooks a mitad de sesión. La compactación terminó intacta de todos modos, porque todo hook es fail-open: el modo de fallo se probó en producción por accidente.
  • Esta página que estás leyendo se revisó en una sesión que cruzó dos compactaciones, retomando cada vez desde el archivo de estado que ella misma describe.

El log del día del lanzamiento, incluido el aviso del 67% y la falla triple de hooks, está escrito completo en el blog del proyecto (en japonés y portugués).

Cómo funciona →

Costes a conocer: cada compact añade una llamada de LLM para generar el estado (por defecto Sonnet; se puede bajar a Haiku o desactivar vía env). Los archivos de estado y los backups guardan la conversación íntegra; se crean con umask 077 (directorios 700, archivos 600), se quedan en tu máquina y se borran automáticamente a los 30 días.

Por qué existe este plugin

El summary integrado se defiende bien con el código. Lo que pierde son hechos operativos: "el push ya está aprobado", "este enfoque ya se intentó y falló", "ese número salió de aquel archivo". Cuando eso desaparece, el agente vuelve a pedir aprobaciones, repite callejones sin salida, y pagas dos veces por el mismo trabajo. compact-ops da a esos hechos secciones fijas propias y los guarda fuera del summary. Hubo una línea de diseño innegociable: el archivo de estado nunca se trata como más confiable que los archivos del proyecto. Un resumen de LLM creído a ciegas por otro LLM es solo un teléfono descompuesto acelerado, así que la guía de recuperación siempre apunta de vuelta a los originales.

Junto a compact-plus y al Claude Code a secas

compact-ops es un derivado de u-ichi/compact-plus (MIT), pionero de la idea de escribir estado estructurado antes del compact. Las diferencias de abajo son las razones de que exista el derivado.

compact-opscompact-plusClaude Code a secas
Aviso de uso Calculado por el propio plugin, sin setup extra Depende de un script de statusline de otro repo Ninguno; el auto-compact llega sin aviso
Dónde vive el estado ~/.claude/compact-ops/, 30 días, por proyecto $TMPDIR (se pierde al reiniciar) El summary solo vive dentro de la sesión
Recuperación en --resume ✓ con fallback de 72h en el mismo proyecto — —
Inyección tras el compact Directa, vía el matcher compact de SessionStart Archivo marker y luego el siguiente UserPromptSubmit (dos hooks) —
Backend de LLM Sonnet primario, Haiku de fallback: solo Claude Sonnet primario, Codex de fallback (asume ChatGPT Pro) —
Licencia MIT MIT —

La idea central, un hook PreCompact que llama a un segundo LLM para escribir estado estructurado, viene de compact-plus. La tabla recoge las diferencias documentadas en el README a julio de 2026; si sus premisas encajan con tu entorno, compact-plus es una buena elección.

FAQ

¿Cuánto cuesta cada compact?

Una llamada extra de LLM para generar el estado (por defecto Sonnet, con fallback en Haiku). Puedes apuntar COMPACT_OPS_PRIMARY_BACKEND a Haiku para abaratarlo, o dejarlo vacío para desactivar solo la generación de estado y conservar los demás hooks.

¿Cambia el summary integrado?

No cambia. El algoritmo de compresión y el summary quedan intocados; todo ocurre en hooks oficiales alrededor. Tras el compact, el agente simplemente tiene dos pistas, el summary y el archivo de estado, en lugar de una.

¿A dónde van los datos de mi conversación?

Los archivos de estado y los backups se quedan en ~/.claude/compact-ops/ en tu máquina, creados con umask 077 y borrados a los 30 días. La única llamada de red es la generación de estado a través de tu propio CLI claude, el mismo canal que tu sesión ya usa.

¿Funciona también con el auto-compact?

Sí. El PreCompact se dispara tanto en la compactación manual como en la automática, así que el backup y el estado siempre se escriben. Un límite conocido: el aviso de uso se calcula en UserPromptSubmit, así que si un solo turno quema contexto suficiente para disparar el auto-compact antes de tu siguiente mensaje, el aviso no llega antes.

¿Debe el agente confiar en el archivo de estado?

Como mapa, sí; como territorio, nunca. La guía inyectada dice explícitamente que el estado es menos confiable que los archivos del proyecto, los planes y las skills, y manda al agente releer los originales antes de actuar.

¿En qué se diferencia de compact-plus?

Tres cambios: el aviso de uso es autocontenido en lugar de depender de un script externo de statusline, el estado persiste 30 días en ~/.claude/ en lugar de $TMPDIR, y claude --resume también recibe inyección de recuperación con fallback de 72 horas. Los backends son solo Claude. La tabla de arriba tiene la lista completa.

¿Por qué no mejorar el propio prompt del summary?

Porque ese lugar está cerrado: el prompt de compactación integrado no está expuesto. Los hooks oficiales son la superficie soportada, y quedarse en ellos significa que el plugin sigue funcionando entre actualizaciones de Claude Code y puede permitirse ser fail-open.

¿Funciona fuera de Claude Code?

No. Está construido sobre los eventos de hook de Claude Code v2.x (PreCompact, SessionStart, UserPromptSubmit) y asume el CLI claude como backend. Otros CLIs de agente tienen superficies de hook distintas.

Sobre el autor

Creado por Ken Imoto: más de 300 artículos técnicos en Zenn, Qiita, Dev.to y este sitio, más de 40 libros en 4 idiomas, más de 400 mil páginas vistas en Zenn y Qiita, 4 artículos de investigación en Zenodo y creador del LLMO Framework.

Más sobre Ken →

Herramientas relacionadas para devs

Todos los productos →

← Todos los productos