Notas · Xabi

Token Optimizer — README (alexgreensh/token-optimizer)

Properties1
tagsia, lua-wiki, contexto, tokens

Se lee en 4 min

📄 Token Optimizer — README

Fuente: README del repo GitHub alexgreensh/token-optimizer (clipping del 2026-10-28)
Tipo: README de herramienta / plugin multi-plataforma
Licencia: no indicada en el README

Resumen

Token Optimizer es un plugin que se engancha a los hooks del agente de código para reducir el gasto de tokens de tres formas a la vez: compresión activa de lo que entra en contexto, supervivencia a la compactación (checkpoints antes y restauración después) y auditoría estructural de lo que ocupa contexto de forma permanente (configs, skills sin usar, memoria vieja, MCP). Su tesis central: las herramientas que solo comprimen salida de comandos cubren el 15-25% del contexto; el otro 75% es basura estructural, de comportamiento y de relecturas.

Funciona sobre Claude Code, Codex, OpenCode, OpenClaw, Hermes, Copilot, Cursor, Pi, Google Antigravity y Grok Build (beta); hay también un filtro de salida en beta para Devin.

Takeaways clave

  1. Tres tipos de desperdicio, no uno: estructural (configs hinchados, skills que nunca se usan, memoria obsoleta), de runtime (salida verbosa, relecturas de ficheros) y de comportamiento (modelo sobredimensionado para la tarea, caché caducada, bucles de reintento).
  2. Ocho superficies de compresión: salida bash (113 comandos, 25 familias de patrones), salida de búsquedas (500 líneas → 20), JSON/tabular, relectura en modo delta (2.000 tokens → ~50), mapa estructural de código (720KB → 250 tokens), resultados grandes archivados a disco, verbosidad de salida, y contexto estructural.
  3. La compresión no sirve si la compactación la borra: checkpoints progresivos al 20/35/50/65/80% de llenado (y cuando la calidad baja de 80/70/50/40), restauración tras compactar, y un context intel digest heurístico (<30 ms, sin llamada al LLM) que reorienta al modelo sin releer todo.
  4. Continuidad entre sesiones: al cerrar, guarda checkpoint en SQLite (tarea activa, decisiones, ficheros tocados, rama git); al abrir, puntúa los checkpoints por relevancia y los inyecta marcados como RECOVERED DATA, nunca como instrucciones. resume-lean reconstruye contexto frío sin coste de transcripción.
  5. Todo se mide, en tres niveles separados: acciones registradas (medidas), relecturas evitadas (estimadas) y otras estimaciones. En el mes del autor: ~1.396 $ de valor API-equivalente y 59,6M tokens no enviados (~28% del workload; 150,8M gastados frente a ~210,4M sin la herramienta), sobre 1.698 sesiones.
  6. Cache-safe por diseño: nunca modifica el prefijo ya presente en contexto; solo actúa sobre contenido nuevo y sobre la frontera de compactación. Cero telemetría, cero llamadas de red, SQLite local, hooks fail-open (si el script falla, el comando corre normal).
  7. Calidad de contexto como métrica de primera clase: score de 7 señales en dos bloques (Resource Health y Session Efficiency) con notas S–F. Cita caída de MRCR de 93% a 76% entre 256K y 1M de contexto.

Datos relevantes

  • Instalación en Claude Code: /plugin marketplace add alexgreensh/token-optimizer + /plugin install token-optimizer@alexgreensh-token-optimizer; después /token-optimizer una vez para enganchar los hooks.
  • Instalación en Hermes: git clone https://github.com/alexgreensh/token-optimizer.git y token-optimizer/install.sh --hermes (compresión de salida de terminal, relecturas más baratas, avisos de bucle, checkpoints que sobreviven a la compactación, pistas de sesiones previas y dashboard, vía hooks de plugin de Hermes).
  • Comandos: /token-optimizer (auditoría completa), /token-coach (tendencias a 30 días), quick, route, doctor, savings, report, dashboard, memory-review, expand, resume-lean, compression-stats, pricing-tier.
  • Dashboard HTML autonómico; servidor local opcional en http://localhost:24842/token-optimizer (measure.py setup-daemon).
  • Base de datos: DB por sesión (~/.claude/token-optimizer/snapshots/session-store/.db, 8 tablas, cap 50 MB) + trends.db (7 tablas), WAL, sin red.
  • Compatibilidad de plataforma: casi todo lo automático es común; la status bar de escritorio, subagent-cache, las recomendaciones de uso y parte de Coach Mode son solo de Claude Code.
  • Instalador verifica CHECKSUMS.sha256 de la release (no firma GPG); sin dependencias de runtime (stdlib de Python / TypeScript sin deps).

Limitaciones y escepticismo

  • Fuente única y vendor: todas las cifras de ahorro las publica el autor sobre sus propias sesiones. No hay estudio de pass-rate; el benchmark propio es un A/B controlado sobre 7 tareas reales (tokens de salida), y la reducción por lean-output (10-15%) está declarada como estimada, no medida contrafactualmente.
  • Las filas de comparación con Headroom / RTK / Boost / context-mode están autoevaluadas por el propio proyecto; las celdas vacías significan “no verificado en la auditoría del 2026-07-26”, no “no existe”.
  • Orientado a Claude Code: hooks, status bar y coaching asumen su modelo de plugins. En Hermes solo está documentada la parte de compresión/continuidad, no la paridad completa.
  • Interacción con el propio sistema de memoria del agente (MEMORY.md) es de auditoría, no de reescritura automática.

Vista Gráfica

Retroenlaces