el plugin que ahorra tokens para agentes de IA en terminal

Claude Code · Codex CLI · opencode · Gemini CLI · Claude Desktop · cualquier cliente MCP

Tu agente quema la mayoría de los tokens antes de escribir una sola línea de código. promptopt tapa las fugas — localmente, sin conexión, gratis.

⚡ TL;DR

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

Ese único comando registra un servidor MCP, inyecta un protocolo de disciplina de ~200 tokens, añade subagentes de modelo barato y empieza a rastrear tus ahorros en un panel HTML elegante.

¿Prefieres casillas? Instalar vía npm (npm i promptopt) o ejecutar promptopt init abre un checklist interactivo — flechas para moverte, espacio para alternar los CLIs que quieras, a para marcar todos, enter para configurarlos:

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

Solo aparece en instalaciones interactivas reales — nunca en CI, nunca durante ejecuciones de npx, nunca dentro del propio repositorio (PROMPTOPT_NO_INIT=1 lo desactiva permanentemente).

$ 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)

Related MCP server: token-compressor

🩸 El problema

En tres prompts reales, promptopt gastó $0.078 donde el modelo insignia sin comprimir habría gastado $0.300 — rastreado en vivo en su propio informe.

📦 Instalación

Requisito: Node ≥ 18. Sin claves API. Sin cuentas. Nada sale de tu máquina.

Un comando para todo

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

Detecta automáticamente qué CLIs tienes instalados y configura cada uno. Añade -n para previsualizar (--dry-run), --all para forzar todos los objetivos.

Elige tu objetivo

npx promptopt install claude

Registra el servidor MCP en .mcp.json (proyecto) o ~/.claude.json (usuario, con --user), inyecta el protocolo en CLAUDE.md, y crea dos subagentes reales:

• promptopt-scout → haiku — búsquedas y consultas de solo lectura, respuestas de ≤5 líneas

• promptopt-worker → sonnet — ediciones bien acotadas, salida basada en diffs

Reinicia tu sesión de Claude Code → listo.

Aviso: los servidores MCP de ámbito de proyecto requieren una aprobación de confianza única — inicia claude en la carpeta y acepta el aviso (o ejecuta /mcp). ¿Atascado en "Aprobación pendiente"? Es esto. Instala con --user y quedará confiable en todos los proyectos sin avisos.

Claude Desktop no tiene esquema de URL para servidores locales, así que elige una de estas opciones:

Opción A — paquete de un clic (recomendada): Descarga promptopt-<versión>.mcpb desde Releases y arrástralo a la ventana de Claude Desktop. Todas las dependencias van incluidas — no necesitas herramientas de Node en el otro extremo.

Opción B — instalador:

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

Opción C — manual: pega en %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Reinicia Claude Desktop → las herramientas aparecen en tus chats.

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

Verifica y revierte

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

Todas las ediciones de archivos de instrucciones quedan entre las marcas <!-- promptopt:start vX --> y <!-- promptopt:end -->; las configuraciones JSON reciben copias de seguridad .bak antes de tocarlas.

🧠 Cómo piensa

Inyectado una vez por sesión (~200 tokens) — el seguro más barato que jamás comprarás:

1. Piensa breve. Planifica en ≤3 frases cortas antes de actuar. Nunca repitas la tarea. 2. Pregunta o asume. Si una petición tiene ≥2 interpretaciones: adopta el supuesto y di "Asumiendo X" en una línea — a menos que un error de suposición fuerce un retrabajo completo, entonces haz ≤3 preguntas agrupadas y detente. 3. Enruta barato. Las subtareas triviales van a promptopt-scout. Nunca gastes tokens de modelo insignia en trabajo de nivel grep. 4. Agrupa. Llamadas a herramientas en paralelo. Lee cada archivo una sola vez. Nunca vuelvas a leer archivos sin cambios. 5. Salida concisa. Diffs en lugar de archivos completos. Detente al terminar — nada de recapitulaciones. 6. Trabajos grandes. Antes de >5k tokens de salida, ejecuta optimize_prompt y sigue su plan.

❓ Preguntas que se responden solas

Cada prompt se clasifica por intención (pregunta / construir / planificar / corregir / añadir) y las peticiones vagas de construcción reciben menús de opción múltiple en lugar de ensayos:

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

Tres modos: hybrid (predeterminado — asume con ≥70% de confianza, pregunta el resto) · auto (asume todo) · ask (nunca asumas).

🛠️ Herramientas MCP

💸 Enrutamiento de modelos

Precios verificados contra el registro público de LiteLLM el 2026-08-21. Los precios cambian — fija los tuyos actuales:

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

La intención dirige el nivel: question degrada (las explicaciones rara vez necesitan Opus), plan promueve al menos a estándar (los planes equivocados son el error más caro).

📊 Informes de uso

Cada ejecución de optimize escribe en ./promptopt-report/ e imprime la ruta:

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

Un panel con degradado oscuro, cero JavaScript, que funciona sin conexión, con tarjetas de estadísticas y barras de progreso:

• tokens ahorrados — esta ejecución y acumulado

• dólares estimados ahorrados frente a la línea base siempre-insignia

• presupuesto usado / % restante (presupuesto local, $10 por defecto)

• la barra contrafactual: lo que habrías gastado sin el plugin

• antes/después de la última ejecución, supuestos, opciones preguntadas, tabla de enrutamiento, últimas 20 ejecuciones

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

Panel en vivo

promptopt dashboard inicia un servidor solo-local (se vincula a 127.0.0.1, nunca expuesto a tu red), abre tu navegador automáticamente y mantiene la página en vivo: un pequeño script de sondeo detecta nuevas ejecuciones de optimize y recarga la página automáticamente — déjala abierta en una pestaña y observa cómo se acumulan los ahorros mientras trabajas.

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

Endpoints: / (panel), /api/data (instantánea JSON de uso), /api/ping. La página servida se re-renderiza desde el registro en cada petición — no hay estado que refrescar manualmente.

Añade promptopt-report/ a .gitignore — telemetría local, solo para tus ojos.

⌨️ Hoja de referencia de la 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

🔒 Privacidad y precisión

• Cero llamadas de red en tiempo de ejecución. El único evento de red jamás es npm descargando el paquete en sí. Sin claves, sin telemetría, sin cuentas.

• La compresión protege bloques de código, URLs y rutas de archivo textualmente; los requisitos nunca se eliminan.

• Los conteos de tokens usan BPE cl100k_base sin conexión — los conteos reales de Claude/Gemini varían ~±10%. Los costos son estimaciones de precios de registros públicos, no facturas.

Claude Desktop acepta conectores remotos por URL, pero los servidores stdio locales — como promptopt, que se ejecuta enteramente en tu máquina — no tienen esquema de enlace profundo. Es exactamente por eso que existe el formato de extensión de escritorio .mcpb: un solo archivo, instalación de doble clic, dependencias incluidas.

🤝 Contribuciones

Se aceptan PRs — nuevas reglas de compresión, actualizaciones del catálogo de modelos, nuevos objetivos de agentes. Ver CONTRIBUTING.md.

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

📄 Licencia

MIT © contribuidores de promptopt