터미널 AI 에이전트를 위한 토큰 절약 플러그인

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.json(프로젝트) 또는 ~/.claude.json(--user 플래그)에 MCP 서버를 등록하고, CLAUDE.md에 프로토콜을 주입하며, 두 개의 실제 서브에이전트를 생성합니다:

• 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 — 수동: Windows의 %APPDATA%\Claude\claude_desktop_config.json 또는 macOS의 ~/Library/Application Support/Claude/claude_desktop_config.json에 붙여넣기:

{
  "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. 간결하게 출력하라. 전체 파일보다 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

세 가지 모드: 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 데스크톱 확장 형식이 존재하는 이유입니다: 파일 하나, 더블클릭 설치, 의존성 포함.

🤝 기여

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 기여자들