ターミナルAIエージェント向けトークン節約プラグイン

Claude Code · Codex CLI · opencode · Gemini CLI · Claude Desktop · あらゆるMCPクライアント

あなたのエージェントは、コードを1行書く前にほとんどのトークンを消費しています。 promptoptがその漏れを塞ぎます — ローカルで、オフラインで、無料で。

⚡ 概要

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

この1コマンドで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)

🩸 問題

実際の3つのプロンプトで、promptoptは**$0.078を消費しました。非圧縮のフラッグシップモデルなら$0.300**かかるところです — 専用レポートでライブ追跡されます。

📦 インストール

要件: Node ≥ 18。APIキー不要。アカウント不要。データがマシンの外に出ることはありません。

すべてを1コマンドで

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

インストール済みのCLIを自動検出し、それぞれを設定します。-nで事前プレビュー（--dry-run）、--allで全ターゲットを強制設定。

ターゲットを選択

npx promptopt install claude

.mcp.json（プロジェクト）または~/.claude.json（--userフラグ）にMCPサーバーを登録し、CLAUDE.mdにプロトコルを注入し、2つの実サブエージェントを作成します:

• promptopt-scout → haiku — 読み取り専用の検索・調査、5行以内の回答

• promptopt-worker → sonnet — 適切にスコープされた編集、diff優先の出力

Claude Codeセッションを再起動 → 完了です。

注意: プロジェクトスコープのMCPサーバーは初回の信頼承認が必要です — フォルダ内でclaudeを起動し、プロンプトを受け入れてください（または/mcpを実行）。「Pending approval」で止まっていますか？ それが原因です。代わりに--userでインストールすれば、すべてのプロジェクトでプロンプトなしで信頼されます。

Claude Desktopにはローカルサーバー用のURLスキームがないため、次のいずれかを選択してください:

オプションA — ワンクリックバンドル（推奨）: Releasesからpromptopt-<version>.mcpbをダウンロードし、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バックアップが作成されます。

🧠 動作の仕組み

セッションごとに1回注入（~200トークン）— これまでで最も安い保険です:

1. 簡潔に考える。 行動前に3文以内の短い計画を立てる。タスクを繰り返さない。 2. 質問するか仮定するか。 リクエストに2つ以上の解釈がある場合: 仮定を採用し、*「Xと仮定します」*と1行で伝える — ただし、誤った推測が完全なやり直しにつながる場合は、最大3つの質問をまとめて行い、停止する。 3. 安価にルーティング。 些細なサブタスクはpromptopt-scoutへ。grepレベルの作業にフロンティアモデルのトークンを費やさない。 4. バッチ処理。 ツール呼び出しを並列化。各ファイルは1回だけ読む。変更のないファイルを再読込しない。 5. 出力を簡潔に。 全ファイルではなくdiff。完了したら停止 — 要約なし。 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

3つのモード: hybrid （デフォルト — 信頼度≥70%は仮定、残りは質問） · auto （すべて仮定） · ask （決して仮定しない）。

🛠️ MCPツール

💸 モデルルーティング

価格は2026-08-21時点の公開LiteLLMレジストリで検証済み。価格は変動します — 最新に固定するには:

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で受け入れますが、promptoptのように完全にマシン上で動作するローカルstdioサーバーにはディープリンクスキームがありません。それがまさに.mcpbデスクトップ拡張形式が存在する理由です: 1ファイル、ダブルクリックでインストール、依存関係込み。

🤝 コントリビューション

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 contributors