плагин для экономии токенов для терминальных ИИ-агентов

Claude Code · Codex CLI · opencode · Gemini CLI · Claude Desktop · любой MCP-клиент

Ваш агент сжигает большую часть токенов ещё до того, как напишет первую строку кода. promptopt закрывает утечки — локально, офлайн, бесплатно.

⚡ TL;DR

npx promptopt install        # one command. every detected CLI. done.

Эта одна команда регистрирует MCP-сервер, внедряет протокол дисциплины на ~200 токенов, добавляет дешёвые субагенты и начинает отслеживать вашу экономию в стильном HTML-дашборде.

Предпочитаете чекбоксы? Установка через npm (npm i promptopt) или запуск promptopt init открывает интерактивный чек-лист — стрелки для перемещения, space для переключения нужных CLI, a для отметки всех, enter для их настройки:

promptopt - select the CLIs to configure:
  [x] claude
  > [ ] claude-desktop
  [x] codex
  [ ] opencode
  [ ] gemini
  [ ] generic
  space: toggle   a: check all   enter: continue   esc: cancel

Он появляется только при реальных интерактивных установках — никогда в CI, никогда во время npx-запусков, никогда внутри самого репозитория (PROMPTOPT_NO_INIT=1 отключает его навсегда).

$ promptopt "Hey, could you please fix the bug in src/app.ts? Thanks!"

tokens: 15 -> 7 compressed (net -53.3%)
intent: fix (85% confidence)

--- optimized prompt ---
Fix the bug in src/app.ts

route: simple · gemini-2.5-flash ~$0.0032  (92% under flagship pricing)

🩸 Проблема

На трёх реальных промптах promptopt потратил $0.078, тогда как несжатый флагман потратил бы $0.300 — отслеживается в реальном времени в его собственном отчёте.

📦 Установка

Требование: Node ≥ 18. Никаких API-ключей. Никаких аккаунтов. Ничего не покидает ваш компьютер.

Одна команда для всего

npx promptopt install
# or the interactive checklist, anytime:
npx promptopt init

Автоматически определяет, какие CLI у вас установлены, и настраивает каждый. Добавьте -n для предпросмотра (--dry-run), --all для принудительной настройки всех целей.

Выберите свою цель

npx promptopt install claude

Регистрирует MCP-сервер в .mcp.json (проект) или ~/.claude.json (флаг --user), внедряет протокол в CLAUDE.md и создаёт два настоящих субагента:

• promptopt-scout → haiku — поиск и запросы только на чтение, ответы ≤5 строк

• promptopt-worker → sonnet — правки в заданных рамках, вывод в виде диффов

Перезапустите сессию Claude Code → готово.

Внимание: MCP-серверы в области проекта требуют однократного подтверждения доверия — запустите claude в папке и примите запрос (или выполните /mcp). Застряли на «Pending approval»? Это оно. Установите с --user — и он будет доверенным в каждом проекте без каких-либо запросов.

У Claude Desktop нет URL-схемы для локальных серверов, поэтому выберите один из вариантов:

Вариант A — пакет в один клик (рекомендуется): Скачайте promptopt-<version>.mcpb из Releases и перетащите его в окно Claude Desktop. Все зависимости включены — на другом конце не нужен Node-инструментарий.

Вариант B — установщик:

npx promptopt install claude-desktop     # writes claude_desktop_config.json for you

Вариант C — вручную: вставьте в %APPDATA%\Claude\claude_desktop_config.json (Windows) или ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "promptopt": { "command": "npx", "args": ["-y", "promptopt", "mcp"] }
  }
}

Перезапустите Claude Desktop → инструменты появятся в ваших чатах.

npx promptopt install codex --user    # ~/.codex/config.toml + ~/.codex/AGENTS.md
npx promptopt install codex           # project AGENTS.md only

npx promptopt install opencode   # opencode.json + AGENTS.md
npx promptopt install gemini     # .gemini/settings.json + GEMINI.md
npx promptopt install generic    # any MCP client: AGENTS.md + printed snippet

Проверка и откат

npx promptopt doctor       # health-check every registration
npx promptopt uninstall    # removes everything cleanly (marker-based, zero residue)

Все правки файлов инструкций находятся между маркерами <!-- promptopt:start vX --> и <!-- promptopt:end -->; JSON-конфиги получают резервные копии .bak перед изменением.

🧠 Как это работает

Внедряется один раз за сессию (~200 токенов) — самая дешёвая страховка, которую вы когда-либо купите:

1. Думайте кратко. Планируйте в ≤3 коротких предложениях перед действием. Никогда не повторяйте задачу. 2. Спрашивайте или предполагайте. Если запрос имеет ≥2 интерпретаций: примите допущение и скажите «Предполагаю X» в одной строке — если только неверная догадка не приведёт к полной переделке, тогда задайте ≤3 объединённых вопроса и остановитесь. 3. Направляйте дёшево. Тривиальные подзадачи идут к promptopt-scout. Никогда не тратьте токены флагмана на работу уровня grep. 4. Группируйте. Параллельные вызовы инструментов. Читайте каждый файл один раз. Никогда не перечитывайте неизменённые файлы. 5. Вывод лаконичный. Диффы вместо полных файлов. Останавливайтесь, когда готово — без резюме. 6. Большие задачи. Перед работой с >5k выходных токенов запустите optimize_prompt и следуйте его плану.

❓ Вопросы, которые отвечают сами

Каждый промпт классифицируется по намерению (вопрос / создание / план / исправление / добавление), а нечёткие задачи получают меню с вариантами вместо эссе-промптов:

questions (1) - ask these before acting:
  1. What should be built?
     choices: feature inside the existing app | standalone script | CLI tool |
              library / package | service / API endpoint | full new app
     default if unanswered: a feature integrated into the existing project

Три режима: hybrid (по умолчанию — предполагать при ≥70% уверенности, остальное спрашивать) · auto (предполагать всё) · ask (никогда не предполагать).

🛠️ MCP-инструменты

💸 Маршрутизация моделей

Цены проверены по публичному реестру LiteLLM 2026-08-21. Цены меняются — зафиксируйте свои актуальные:

promptopt models --refresh   # re-syncs into ~/.promptopt/models.json (trusted 7 days)

Намерение управляет уровнем: question понижает (для объяснений редко нужен Opus), plan повышает как минимум до стандартного (неверные планы — самая дорогая ошибка).

📊 Отчёты об использовании

Каждый запуск optimize записывает данные в ./promptopt-report/ и выводит путь:

report: C:\dev\myproject\promptopt-report\index.html

Тёмный градиентный дашборд без JS, работающий офлайн, со статистическими карточками и прогресс-барами:

• сохранённые токены — за этот запуск и накопительно

• оценка сэкономленных долларов по сравнению с базовым всегда-флагманом

• использованный бюджет / % остатка (локальный бюджет, по умолчанию $10)

• контрфактический столбец: сколько бы вы сожгли без плагина

• последний запуск: до/после, допущения, заданные вопросы, таблица маршрутизации, последние 20 запусков

promptopt budget                       # usage + % left
promptopt budget --set-usd 25 --set-tokens 2000000
promptopt report --open                # print (and open) the static report
promptopt dashboard                    # LIVE dashboard on http://localhost:4739
promptopt "..." --no-report            # optimize without recording

Живой дашборд

promptopt dashboard запускает локальный сервер (привязка к 127.0.0.1, никогда не доступен из сети), автоматически открывает браузер и держит страницу живой: небольшой скрипт опроса обнаруживает новые запуски optimize и автоматически перезагружает страницу — оставьте её открытой во вкладке и наблюдайте, как накапливается экономия, пока вы работаете.

promptopt dashboard              # http://localhost:4739
promptopt dashboard -p 8080      # custom port (auto-falls forward if taken)
promptopt dashboard --no-open    # serve without opening the browser

Эндпоинты: / (дашборд), /api/data (JSON-снимок использования), /api/ping. Отображаемая страница перерисовывается из журнала при каждом запросе — нет состояния, которое нужно обновлять вручную.

Добавьте promptopt-report/ в .gitignore — локальная телеметрия, только для ваших глаз.

⌨️ Шпаргалка по CLI

promptopt "<prompt>"                     # optimize (hybrid mode + report)
promptopt init                           # interactive checkbox installer
promptopt "<prompt>" --mode ask          # all questions, zero assumptions
promptopt route "<prompt>"               # tier + cheapest model per provider
promptopt audit "$(cat big-log.txt)"     # token count + compression report
promptopt models                         # catalog + source
promptopt dashboard                      # live localhost usage dashboard
promptopt doctor                         # installation health check

🔒 Конфиденциальность и точность

• Ноль сетевых вызовов во время работы. Единственное сетевое событие — это загрузка самого пакета через npm. Никаких ключей, телеметрии, аккаунтов.

• Сжатие защищает блоки кода, URL и пути к файлам дословно; требования никогда не отбрасываются.

• Подсчёт токенов использует офлайн-кодировку cl100k_base BPE — реальные значения для Claude/Gemini могут отличаться на ~±10%. Стоимость — это оценки по ценам из публичного реестра, а не счета.

Claude Desktop принимает удалённые коннекторы по URL, но локальные stdio-серверы — такие как promptopt, который работает полностью на вашей машине, — не имеют схемы глубоких ссылок. Именно поэтому существует формат .mcpb для десктопных расширений: один файл, установка двойным кликом, зависимости включены.

🤝 Вклад

PR приветствуются — новые правила сжатия, обновления каталога моделей, новые цели для агентов. См. CONTRIBUTING.md.

git clone https://github.com/hawktuahcoin-hurhur/promptopt && cd promptopt
npm ci && npm run build && npm test && npm run test:smoke

📄 Лицензия

MIT © участники promptopt