the token-saving plugin for terminal AI agents

Claude Code · Codex CLI · opencode · Gemini CLI · Claude Desktop · any MCP client

Your agent burns most of its tokens before it writes a single line of code. promptopt plugs the leaks — locally, offline, for free.

⚡ TL;DR

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

That single command registers an MCP server, injects a ~200-token discipline protocol, adds cheap-model subagents, and starts tracking your savings in a stylish HTML dashboard.

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

🩸 The problem

| Token leak | What actually happens | promptopt's fix | |---|---|---| | 🔁 Rework loops | Agent guesses an ambiguous request wrong → you re-prompt → double spend | Asks ≤3 sharp questions when guessing is expensive; auto-assumes + states assumptions when it isn't | | 🗣️ Chatty prompts | "Hey, could you please maybe..." | Rule-based compression: 15–55% off typical prompts | | 🏋️ Wrong-size model | Opus-grade reasoning spent on grep-level lookups | Tier classifier routes to the cheapest capable model/subagent | | 📜 Verbose sessions | Restating tasks, narrating unchanged code, recaps | Behavior protocol rules 1–6 |

On three real prompts, promptopt spent $0.078 where uncompressed-flagship would have spent $0.300 — tracked live in its own report.

📦 Install

Requirement: Node ≥ 18. No API keys. No accounts. Nothing leaves your machine.

One command for everything

npx promptopt install

Auto-detects which CLIs you have installed and configures each one. Add -n to preview first (--dry-run), --all to force every target.

Pick your target

npx promptopt install claude

Registers the MCP server in .mcp.json (project) or ~/.claude.json (--user flag), injects the protocol into CLAUDE.md, and creates two real subagents:

• promptopt-scout → haiku — read-only lookups & searches, ≤5-line answers
• promptopt-worker → sonnet — well-scoped edits, diff-first output

Restart your Claude Code session → done.

Heads-up: project-scope MCP servers need a one-time trust approval — start claude in the folder and accept the prompt (or run /mcp). Stuck at "Pending approval"? That's this. Install with --user instead and it's trusted in every project with zero prompts.

Claude Desktop has no URL scheme for local servers, so pick one of these:

Option A — one-click bundle (recommended): Download promptopt-<version>.mcpb from Releases and drag it onto the Claude Desktop window. All dependencies are bundled — no Node tooling needed on the other end.

Option B — installer:

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

Option C — manual: paste into %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Restart Claude Desktop → the tools appear in your 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

Verify & reverse

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

All instruction-file edits sit between <!-- promptopt:start vX --> and <!-- promptopt:end --> markers; JSON configs get .bak backups before touching them.

🧠 How it thinks

Injected once per session (~200 tokens) — the cheapest insurance you'll ever buy:

1. Think terse. Plan in ≤3 short sentences before acting. Never restate the task. 2. Ask or assume. If a request has ≥2 interpretations: adopt the assumption and say "Assuming X" in one line — unless a wrong guess forces a full rework, then ask ≤3 batched questions and stop. 3. Route cheap. Trivial subtasks go to promptopt-scout. Never spend frontier tokens on grep-level work. 4. Batch. Parallel tool calls. Read each file once. Never re-read unchanged files. 5. Output lean. Diffs over full files. Stop when done — no recap. 6. Big jobs. Before >5k output tokens of work, run optimize_prompt and follow its plan.

❓ Questions that answer themselves

Every prompt is intent-classified (question / build / plan / fix / add) and vague builds get multiple-choice menus instead of essay prompts:

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

Three modes: hybrid (default — assume ≥70% confidence, ask the rest) · auto (assume everything) · ask (never assume).

🛠️ MCP tools

| Tool | Does | |---|---| | optimize_prompt | Intent → compression → auto-assumptions → choice-based blockers → routing → usage report | | route_prompt | Cheapest capable model per provider, costed against always-flagship | | token_audit | Offline BPE token count + compression opportunities for any text | | get_protocol | Protocol text for agents that can't read instruction files |

💸 Model routing

| Tier | Claude | OpenAI | Gemini | |---|---|---|---| | trivial | claude-haiku-4-5 · $1/$5 | gpt-5.4-nano · $0.20/$1.25 | gemini-3.1-flash-lite · $0.25/$1.50 | | standard | claude-sonnet-5 · $2/$10 | gpt-5.1 · $1.25/$10 | gemini-2.5-flash · $0.30/$2.50 | | complex | claude-opus-5 · $5/$25 | o3 · $2/$8 | gemini-3-pro-preview · $2/$12 |

Prices verified against the public LiteLLM registry on 2026-08-21. Prices drift — pin yours current:

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

Intent steers the tier: question demotes (explanations rarely need Opus), plan promotes to at least standard (wrong plans are the priciest mistake).

📊 Usage reports

Every optimize run writes to ./promptopt-report/ and prints the path:

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

A dark-gradient, zero-JS, works-offline dashboard with stat cards and progress bars:

• tokens saved — this run and cumulative
• est. dollars saved vs the always-flagship baseline
• budget used / % left (local budget, default $10)
• the counterfactual bar: what you'd have burned without the plugin
• latest run's before/after, assumptions, choices asked, routing table, last 20 runs

promptopt budget                       # usage + % left
promptopt budget --set-usd 25 --set-tokens 2000000
promptopt report --open                # opens the dashboard in your browser
promptopt "..." --no-report            # optimize without recording

Add promptopt-report/ to .gitignore — local telemetry, your eyes only.

⌨️ CLI cheat sheet

promptopt "<prompt>"                     # optimize (hybrid mode + report)
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 doctor                         # installation health check

🔒 Privacy & accuracy

• Zero network calls at runtime. The only network event ever is npm fetching the package itself. No keys, no telemetry, no accounts.
• Compression protects code blocks, URLs, and file paths verbatim; requirements are never dropped.
• Token counts use offline cl100k_base BPE — Claude/Gemini actual counts vary ~±10%. Costs are estimates from public registry prices, not invoices.

Claude Desktop accepts remote connectors by URL, but local stdio servers — like promptopt, which runs entirely on your machine — have no deep-link scheme. That's exactly why the .mcpb desktop-extension format exists: one file, double-click install, dependencies included.

🤝 Contributing

PRs welcome — new compression rules, model catalog updates, new agent targets. See CONTRIBUTING.md.

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

📄 License

MIT © promptopt contributors