prompt-lens

ESLint for prompts. Analyzes your prompt before you send it to any LLM — detects missing context, vague instructions, filler tokens — and proposes a leaner rewrite. Zero API calls, works offline, instant feedback.

Installation

Via npx (zero install)

npx @redpi/prompt-lens install

Registers the hook using npx --yes @redpi/prompt-lens hook — no global install needed. The hook runs via npx on every prompt, always using the latest published version.

Global install (recommended for daily use)

npm install -g @redpi/prompt-lens
prompt-lens install

Registers the hook as prompt-lens hook — faster per-prompt (no npx overhead).

From source

git clone <repo>
cd prompt-lens
pnpm install && pnpm build
npm link        # then: prompt-lens install

Quick start

Analyze a prompt directly

prompt-lens "I would like you to please write a blog post about TypeScript generics for intermediate developers, formatted as a bullet list."

Output:

prompt-lens v0.1.0

Overall Score: 81/100 (B) — passed
─────────────────────────────────────────────────────────
Rules:
  Clarity         ██████████  10/10  ✓ OK
  Specificity     ████████░░   8/10  ✓ No quantities or numbers
  Context         ███████░░░   7/10  ✓ No target audience specified
  Instructions    ██████████  10/10  ✓ OK
  Tone            █████░░░░░   5/10  ℹ No tone or formality specified
  Output Format   ██████░░░░   6/10  ℹ No length constraint
  Length          ██████████  10/10  ✓ OK
  Efficiency      ██████░░░░   6/10  ⚠ Filler phrase "I would like you to" wastes tokens

Top Issues:
  1. ⚠ No target audience specified — who is this for?
  2. ⚠ Filler phrase "I would like you to" wastes tokens — remove it
  3. ⚠ Filler phrase "please" wastes tokens — remove it

Token Analysis:
  Original:  ~32 tokens
  Optimized: ~25 tokens (↓22%, save 7 tokens)

  Cost per 1M calls (original → optimized):
    OpenAI GPT-4o            $0.0000800 → $0.0000625  save $17.5/M calls
    OpenAI GPT-4o mini       $0.0000048 → $0.0000038  save $1.0/M calls
    Anthropic Claude Opus    $0.0004800 → $0.0003750  save $105.0/M calls
    Anthropic Claude Haiku   $0.0000256 → $0.0000200  save $5.6/M calls
    Google Gemini 2.5 Pro    $0.0000400 → $0.0000313  save $8.7/M calls
    Google Gemini Flash 2.5  $0.0000024 → $0.0000019  save $0.5/M calls

Lean Rewrite (25 tokens, fluency 10/10, conservative):
─────────────────────────────────────────────────────────
Write a blog post about TypeScript generics for intermediate developers, formatted as a bullet list.
─────────────────────────────────────────────────────────

Other input modes

# From file
prompt-lens --file ./my-prompt.txt

# From stdin
echo "my prompt" | prompt-lens

# JSON output
prompt-lens "..." --json

# Only specific rules
prompt-lens "..." --rules clarity,specificity

# Fail with exit code 1 if score below threshold (useful in CI)
prompt-lens "..." --min-score 80

# Generate HTML dashboard (opens in browser)
prompt-lens "..." --report

Claude Code hook

Install prompt-lens as a UserPromptSubmit hook — it runs automatically before every message you send and shows a compact analysis inline in the conversation.

prompt-lens install

When installed, every prompt you type in Claude Code is intercepted and analyzed:

┌─ prompt-lens ──────────────────────────────────────────┐
│ Score 81/100 (B)  •  Tokens: 32→25 ↓22%  •  Fluency: 10/10
│
│ ⚠ No target audience specified
│ ⚠ Filler phrase "I would like you to" wastes tokens
│ ⚠ Filler phrase "please" wastes tokens
│
│   Write a blog post about TypeScript generics for intermediate
│   developers, formatted as a bullet list.
└────────────────────────────────────────────────────────┘

Short conversational messages (ok, thanks, continue) are skipped automatically.

prompt-lens install --claude   # Claude Code only
prompt-lens install --codex    # Codex CLI only
prompt-lens uninstall          # remove hook

Enable / Disable

Toggle the hook on and off without reinstalling. The hook entry stays in settings.json — the runner simply exits silently when disabled.

Disable

prompt-lens disable

prompt-lens disabled — hook stays registered, analysis skipped

Status confirms:

prompt-lens status

Claude Code (/Users/you/.claude/settings.json): ✓ installed
Codex CLI   (/Users/you/.codex/config.json):    ✓ installed
State: ✗ disabled

While disabled, the hook fires but outputs nothing — your prompts go through unchanged, with zero overhead.

Enable

prompt-lens enable

prompt-lens enabled

prompt-lens status

Claude Code (/Users/you/.claude/settings.json): ✓ installed
Codex CLI   (/Users/you/.codex/config.json):    ✓ installed
State: ✓ enabled

Hook resumes immediately — no reinstall needed.

State is stored in ~/.prompt-lens.json. Default (file absent) = enabled.

CLI reference

| Command | Description | |---|---| | prompt-lens [prompt] | Analyze a prompt (default command) | | prompt-lens --file <path> | Read prompt from file | | prompt-lens --json | Output raw JSON | | prompt-lens --report | Generate HTML dashboard | | prompt-lens --rules <list> | Run only specific rules (comma-separated) | | prompt-lens --min-score <n> | Exit 1 if score below threshold | | prompt-lens install | Register hook in Claude Code + Codex CLI | | prompt-lens uninstall | Remove hook | | prompt-lens enable | Enable hook (no reinstall) | | prompt-lens disable | Disable hook (no uninstall) | | prompt-lens status | Show installation + enabled state |

How it works

Eight synchronous heuristic rules, each scoring 0–10:

| Rule | Weight | Detects | |---|---|---| | Instructions | 22% | Weak verbs, no clear deliverable, contradictions | | Clarity | 18% | Vague words (thing, stuff), double negatives | | Specificity | 18% | No numbers, no examples, no proper nouns | | Context | 15% | No role (You are a...), no audience, no domain | | Output Format | 10% | No format keyword (list, JSON, table...) | | Efficiency | 10% | Filler phrases, over-hedging, repeated sentences | | Tone | 5% | No formality signal | | Length | 2% | Too short (<20 chars) or too long (>8000 chars) |

The token optimizer strips filler syntactically (never paraphrases) and validates that all named entities, numbers, and constraint keywords are preserved before accepting a rewrite. If the compressed version reads worse than a fluency threshold of 4/10, the original is returned as-is.

Environment variables

| Variable | Default | Description | |---|---|---| | PROMPT_LENS_MIN_TOKENS | 10 | Skip hook output for prompts below this token count |