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.

Prefer checkboxes? Installing via npm (npm i promptopt) or running promptopt init opens an interactive checklist - arrow keys to move, space to toggle the CLIs you want, a to check all, enter to configure them:

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

It only appears on real interactive installs - never in CI, never during npx runs, never inside this repo itself (PROMPTOPT_NO_INIT=1 disables it permanently).

$ 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

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
# or the interactive checklist, anytime:
npx promptopt init

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

💸 Model routing

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                # print (and open) the static report
promptopt dashboard                    # LIVE dashboard on http://localhost:4739
promptopt "..." --no-report            # optimize without recording

Live dashboard

promptopt dashboard starts a local-only server (binds 127.0.0.1, never exposed to your network), auto-opens your browser, and keeps the page live: a tiny poll script detects new optimize runs and reloads the page automatically — leave it open in a tab and watch savings accumulate while you work.

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: / (dashboard), /api/data (usage snapshot JSON), /api/ping. The served page re-renders from the ledger on every request — there is no state to refresh manually.

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

⌨️ CLI cheat sheet

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

🔒 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