Token Optimizer — экономия токенов и защита контекста для AI-кодинг-агентов
📂 Исходный код на GitHubПлагин для AI-кодинг-агентов: сжатие контекста на восьми поверхностях, чекпоинты до авто-компакции и восстановление после неё, кросс-сессионные подсказки, оценка качества контекста и локальный дашборд с подсчётом экономии в долларах. Python 3.9+, без зависимостей и телеметрии.
Token Optimizer — открытый плагин для AI-кодинг-агентов, который решает две смежные задачи: режет токены, которые ассистент тратит впустую, и сохраняет сделанную работу, когда контекст уплотняется или сессия заканчивается. Большая часть функциональности работает автоматически через хуки: вы устанавливаете плагин, один раз запускаете аудит /token-optimizer, дальше сжатие, чекпоинты, оценка качества и обновление дашборда происходят сами.
Поддерживаются Claude Code (CLI и VS Code), OpenCode, OpenClaw, Codex, Hermes, GitHub Copilot, Cursor, Google Antigravity (beta) и Grok Build (beta); Windsurf в планах. Написан на Python 3.9+ (для OpenCode и OpenClaw — на TypeScript), не имеет рантайм-зависимостей, не отправляет телеметрию. Лицензия — PolyForm Noncommercial 1.0.0: для личного, исследовательского и образовательного использования платить не нужно.
Чем он отличается от обычных компрессоров
Инструменты вроде Headroom или RTK сжимают вывод команд — а это, по подсчётам автора, лишь 15–25% контекста. Token Optimizer покрывает восемь поверхностей:
- вывод bash-команд (111 команд в 22 семействах паттернов, credential-safe);
- результаты поиска (grep/rg/web) — топ-хиты плюс счётчик;
- табличный и JSON-вывод (jq, yq, csvtool) с сохранением значений;
- повторные чтения файлов в режиме дельты — только diff;
- повторные чтения кода — структурный скелет вместо полного файла;
- крупные результаты инструментов (>4K символов) — архивация на диск с извлечением по требованию;
- многословность самой модели — «lean-output» подсказки;
- структурный контекст (конфиги, скиллы, MCP, память) — по-компонентный аудит.
Поверх сжатия инструмент работает с тремя видами потерь: структурными (раздутые конфиги, неиспользуемые скиллы, протухшая память), рантаймными (многословный вывод, повторные чтения) и поведенческими (неверный выбор модели, истечение кэша, циклы ретраев). Ключевое отличие — экономия переживает компакцию: без чекпоинтов и восстановления все сбережения испаряются в момент авто-уплотнения контекста.
Установка
Для Claude Code (рекомендуемый путь):
/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizerЗатем один раз выполнить /token-optimizer для настройки хуков. Стоит сразу включить автообновление маркетплейса в настройках плагинов — по умолчанию оно выключено. Для облачных сессий claude.ai/code плагин подключается через extraKnownMarketplaces в .claude/settings.json репозитория.
Прочие платформы: для Codex — codex plugin marketplace add, для OpenCode — строка token-optimizer-opencode в массиве plugin конфига opencode.json, для OpenClaw — openclaw plugins install github:alexgreensh/token-optimizer, для Hermes, Copilot, Cursor, Antigravity и Grok Build — install.sh с соответствующим флагом (--copilot, --cursor и т.д.). На Windows рекомендован только plugin-вариант установки. Удаление полностью обратимое: uninstall-скрипты убирают только то, что было установлено.
Что работает автоматически
- Smart Compaction — чекпоинты состояния сессии до авто-компакции и восстановление потерянного после неё.
- Session Continuity — кросс-сессионные подсказки с оценкой релевантности, «холодное» возобновление сессии из чекпоинта без чтения полного транскрипта.
- Активное сжатие — девять функций, включённых по умолчанию (дельты, скелеты, сжатие bash/поиска, lean-output и quality-подсказки, детекция циклов, режимы активности, извлечение решений).
- Оценка качества контекста — семь сигналов в реальном времени, оценки от S до F.
- База сессий — локальный SQLite, 15 таблиц, полный аудит; ноль сетевых вызовов.
- Progressive Disclosure — крупные результаты инструментов архивируются, полный оригинал достаётся командой
expand. - Context Intel Digest — после компакции в контекст вводится эвристическая сводка крупных результатов инструментов, чтобы модель переориентировалась без повторных чтений.
- Model Routing Nudges — подсказки уводят задачу на подходящий по цене уровень модели.
Активное сжатие: девять функций
Под капотом хуки PreToolUse перехватывают каждый вызов Read и Bash до попадания в контекст: если файл уже читался — вернётся только diff; повторное чтение кода заменяется структурным скелетом (функции, классы, импорты); вывод CLI-команд сжимается. Хуки PostToolUse архивируют полный оригинал на диск и пишут событие сжатия в SQLite — ничего не теряется, всё извлекается через expand.
| Функция | Что делает | Экономия |
|---|---|---|
| Delta Mode | повторное чтение возвращает только изменения | ~20% на ре-ридах |
| Structure Map | скелет сигнатур вместо полного кода | ~30% (до 99% на файл) |
| Bash Compression | вывод CLI сжимается до сути | ~10% |
| Search Compression | grep/rg-результаты — топ-хиты + счётчик | ~15% |
| Lean-Output Nudges | подсказки к лаконичному выводу при заполнении контекста | оценка 10–15% |
| Quality Nudges | предупреждения при падении качества контекста | предотвращает потери при компакции |
| Loop Detection | ловит циклы ретраев и edit-compile-fail спирали | измеряется по факту |
| Activity Mode | подстраивает компакцию под фазу сессии (code/debug/review/infra) | предотвращает потерю решений |
| Decision Extraction | сохраняет решения через компакции | предотвращает дрейф решений |
Любую функцию можно выключить из дашборда, через CLI (measure.py v5 enable|disable <feature>) или переменные окружения вида TOKEN_OPTIMIZER_BASH_COMPRESS=0. Свои фильтры команд добавляются TOML-файлом command-filters.toml с жёсткой защитой: загрузчик отвергает интерпретаторы, sudo-обёртки, деструктивные подкоманды и метасимволы шелла.
Важная гарантия — cache-safety: инструмент никогда не модифицирует уже существующий префикс контекста, поэтому промпт-кэш остаётся целым, и вы экономите дважды — на вводе и на дешёвых чтениях из кэша. Все хуки неблокирующие и fail-open: если скрипт упал, ваша команда выполняется как обычно.
Непрерывность сессий и умная компакция
Когда срабатывает авто-компакция, 60–70% разговора исчезает: решения, последовательности исправления ошибок, состояние агентов. Token Optimizer делает прогрессивные чекпоинты на порогах заполнения 20/35/50/65/80% плюс при падении качества, а перед компакцией — снимок состояния: активная задача, ключевые решения, изменённые файлы, git-ветка, недавние чтения.
Decision Extraction ловит формулировки решений прямо из вывода инструментов по ходу сессии и при компакции требует сохранить их дословно как CRITICAL DECISIONS. Context Intel Digest генерируется эвристически за <30 мс без вызова LLM. Команда resume-lean открывает «остывшую» сессию, реконструируя компактный контекст из SQLite — без вызова LLM и без оплаты полного транскрипта.
Оценка качества контекста
Quality Score отслеживает два аспекта: Resource Health (насколько вы близко к обрыву деградации) и Session Efficiency (тратятся ли токены на полезную работу). Оценки от S до F, статусная строка меняет цвет по мере деградации. Смысл простой: по мере заполнения окна модель объективно глупеет (MRCR падает с 93% до 76% между 256K и 1M контекста) — скор показывает, когда именно это происходит.
Дашборд, Coach Mode и экономия
Дашборд — одна HTML-страница, которая перегенерируется автоматически после каждой сессии: по-терновые разбивки токенов, стоимость по четырём ценовым тирам, анализ кэша (TTL, hit rate), оценки качества по сессиям, разбивка расходов на субагентов.
/token-coach анализирует 30 дней истории и выдаёт приоритизированные исправления: дрейф качества вниз, удлинение сессий, падение hit rate кэша, частые переключения моделей, ломающие кэш паттерны в CLAUDE.md, никогда не используемые скиллы. Одиннадцать детекторов находят PDF-проглатывание, retry-churn, «Опус на простых правках», монструозные промпты и прочие антипаттерны. Отдельно есть Keep-Warm для API-биллинга (обновление TTL промпт-кэша перед истечением) и Fleet Auditor для поиска «холостых» расходов между разными агентами.
Экономия считается в двух непересекающихся уровнях и никогда не суммируется: counted — зафиксированные события (по снапшоту автора ~$313/мес: модельный роутинг ~$260 + сжатие на лету ~$53) и big picture — контрфактическая оценка против замороженного базлайна (~$1,877/мес, ~18%, на 684 сессиях за 30 дней: уход с 95% Opus на смешанный микс даёт основную часть). Это числа конкретного пользователя — ваши будут своими, но измеряются локально и по той же методике.
Где лежат данные
Всё локально: per-session база (~/.claude/token-optimizer/snapshots/session-store/<session>.db, 8 таблиц, WAL-режим, лимит 50 МБ на сессию) и трендовая база (trends.db, 7 таблиц). Каждый вызов measure.py compression-stats — это SQL-запрос к вашим же данным, дашборд — read-only вид поверх них. Ноль сетевых вызовов, ноль телеметрии.
Итог
Token Optimizer — редкий случай, когда инструмент сжатия контекста честно измеряет, помогло ли оно: до/после дельты токенов, экономия в долларах по четырём пулам, quality-скоры, отслеживающие деградацию. Если вы живёте в Claude Code или другом агенте подолгу и платите за токены, плагин ставится за две минуты и дальше работает сам. Репозиторий: github.com/alexgreensh/token-optimizer, документация: alexgreensh.github.io/token-optimizer.