Claude Prompt Optimizer

Prompt Control Plane

The control plane for AI prompts. Score, enforce policy, lock config, and audit every prompt decision. Free tier included.

---

Quick Start

# Install globally (requires Node.js 20+)

npm install -g pcp-engine

Pre-flight: classify, score, route, and enforce policy in one call

pcp preflight "your prompt here" --json

Run the guided demo

pcp demo

Two powerhouse commands:

Supporting commands:

Free tier gives you 50 optimizations/month to try it out.

Try It

# Pre-flight a vague prompt: see why it scores low

pcp preflight "make the code better" --json

Pre-flight a well-specified prompt: see the full analysis

pcp preflight "Refactor auth middleware in src/auth/middleware.ts to use JWT. Do not modify the user model." --json

Run the full optimization pipeline (compile + blocking questions + approval)

pcp optimize "Build a REST API with auth" --json

Quick quality check on all prompts in a directory

pcp check --file "prompts/**/*.txt"

Run the guided demo

pcp demo

GitHub Action

# .github/workflows/prompt-quality.yml

• uses: rishi-banerjee1/prompt-control-plane@v5 with: subcommand: preflight files: "prompts/**/*.txt"

Full GitHub Action configuration

# .github/workflows/pcp.yml

name: Prompt Quality Gate on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest permissions: pull-requests: write steps:

• uses: actions/checkout@v4
• uses: rishi-banerjee1/prompt-control-plane@v5 with: subcommand: preflight files: 'prompts/**/*.txt' threshold: 70 comment: 'true' # Posts results as PR comment

Run optimize in CI (full pipeline):

      - uses: rishi-banerjee1/prompt-control-plane@v5

with: subcommand: optimize files: 'prompts/**/*.txt'

This action expects your repo to be checked out (actions/checkout). Without it, file globs will match nothing.

SHA-pinned example (for enterprise users):

      - uses: rishi-banerjee1/prompt-control-plane@abc123def  # SHA-pinned

with: version: '5.0.0' # Required when pinning by SHA files: 'prompts/**/*.txt' threshold: 70

Notes:

• The action installs pcp via npm install --prefix into $RUNNER_TEMP, then runs the binary. Falls back to prompt-lint for v4 installs.
• Action tag @v5 maps to npm @5 (latest 5.x). Use @v5.0.0 for exact pinning.
• subcommand input accepts check (default), preflight, optimize, or score. Use preflight for CI gates.
• comment: 'true' posts results as a PR comment (requires pull-requests: write permission).
• Exit code 2 means no files matched or invalid input: not "all passed." Zero matched files is always an error.
• On Windows runners, prefer single quotes or escape glob wildcards in PowerShell.
• Rule IDs (e.g., vague_objective, missing_constraints) are stable: treat as a public contract.

Why This Exists

• Prompts run without any quality check. "Make the code better" gives Claude no constraints, no success criteria, and no target: leading to unpredictable results and wasted compute.
• No structure scoring, no ambiguity detection. Even experienced engineers skip success criteria, constraints, and workflow steps. This linter flags structural gaps before you send.
• Cost is invisible until after you've spent it. Most users have no idea how many tokens their prompt will consume. The linter shows cost breakdowns across 21 costed models from Anthropic, OpenAI, Google, and Perplexity before you commit. Cost estimates are approximate: validate for billing-critical workflows.
• Simple tasks run on expensive models. Without routing intelligence, every prompt goes to the same model. The decision engine classifies complexity and routes simple tasks to cheaper models automatically: reducing LLM spend without changing your prompts.
• Context bloat is the hidden cost multiplier. Sending 500 lines of code when 50 are relevant burns tokens on irrelevant context. The smart compressor runs 5 heuristics (license strip, comment collapse, duplicate collapse, stub collapse, aggressive truncation) with zone protection for code blocks and tables: standard mode is safe, aggressive mode is opt-in.
• Human-in-the-loop approval. The MCP asks blocking questions when your prompt is ambiguous, requires you to answer them before proceeding, and only finalizes the compiled prompt after you explicitly approve. No prompt runs without your sign-off: the gate is enforced in code, not convention.

How It Works

flowchart LR

A([Your prompt]) --> B[Host Claude] B -->|calls optimize_prompt| C{PCP Engine}

subgraph C[PCP Engine: Zero LLM Calls] direction TB D[1. Tokenize & normalize] --> E[2. Detect task type] E --> F[3. Score 5 dimensions] F --> G[4. Run 14 rules] G --> H[5. Assess risk] H --> I[6. Route model] I --> J[7. Estimate cost] J --> K[8. Compile prompt] end

C -->|PreviewPack| B B --> L([User reviews & approves]) L -->|approve_prompt| B B --> M([Execute with compiled prompt])

The Approval Loop

Every prompt goes through a mandatory review cycle before it's finalized:

1. Analyze: You type a prompt. The MCP scores it, detects ambiguities, and compiles a structured version.
2. Ask: If the prompt is vague or missing context, the MCP surfaces up to 3 blocking questions. You answer them via refine_prompt.
3. Review: You see the compiled prompt, quality score, cost estimate, and what changed. No surprises.
4. Approve: You say "approve" and the compiled prompt is locked in. approve_prompt hard-fails if unanswered blocking questions remain: the gate is enforced in code, not convention.

The MCP is a co-pilot for the co-pilot. It does the structural work (decomposition, gap detection, template compilation, token counting) so Claude can focus on intelligence.

Zero LLM calls inside the MCP. All analysis is deterministic: regex, heuristics, and rule engines. The host Claude provides all intelligence. This means the MCP itself is instant, free, and predictable.

Works for all prompt types: code, writing, research, planning, analysis, communication, data, and more. The pipeline auto-detects 13 task types and adapts scoring, constraints, templates, and model recommendations accordingly. A Slack post gets writing-optimized constraints; a refactoring task gets code safety guardrails. Intent-first detection classifies prompts *about* technical topics that request non-code work correctly: the opening verb phrase takes priority over technical keywords in the body.

Benchmarks

Real results from the deterministic pipeline. PCP scores the input prompt quality, not the compiled output: the compiled prompt gets a structural checklist instead:

Score = input prompt quality (0-100). Confidence = how much improvement to expect (high = prompt is weak, lots of room; low = prompt is already strong). Compiled output gets a structural checklist (e.g. 7/9 elements present), not an inflated numeric score. Vague prompts get blocked with targeted questions. Well-specified prompts get compiled with safety constraints, workflow steps, and model routing: all deterministically, with zero LLM calls.

Features

Vague Prompt Detection

Raw: "make the code better"

Quality: 50/100 Confidence: high State: ANALYZING

Blocking Questions: ⛔ Which file(s) or module(s) should this change apply to?

Changes Made: ✓ Added: role definition ✓ Added: success criteria ✓ Added: safety constraints ✓ Added: workflow (4 steps) ✓ Added: uncertainty policy

*Catches missing targets, vague objectives, and scope explosions before Claude starts working*

Well-Specified Prompt Compilation

Raw: "Refactor auth middleware in

src/auth/middleware.ts..."

Quality: 68/100 Confidence: medium State: COMPILED Risk: high (auth domain) Model: claude-opus-5 (recommended)

Detected Inputs: 📄 src/auth/middleware.ts 📄 auth.test.ts

Extracted Constraints: 🚫 Do not touch user model or DB layer

*Detects high-risk domains, extracts file paths and constraints, recommends the right model*

Multi-Task Overload Detection

Raw: "update payment processing and

also refactor the dashboard and then fix rate limiting and finally clean up tests"

Quality: 53/100 Confidence: medium Risk: high (payment domain) Blocking: 3 questions

Assumptions: 💡 Consider splitting into separate prompts for better focus.

*Detects when one prompt tries to do too much and suggests splitting*

Context Compression

Intent: "fix updateProfile to validate

email format"

Original: ~397 tokens Compressed: ~169 tokens Saved: ~228 tokens (57%)

What Was Removed: 🗑️ Trimmed 7 import statements 🗑️ Removed 15-line block comment 🗑️ Removed test code (not relevant) 🗑️ Collapsed excessive blank lin