PrePrompt for Claude Code: Your Prompts, Optimized Before the Model Sees Them

How PrePrompt Uses Claude Code's UserPromptSubmit Hook

Claude Code exposes a UserPromptSubmit hook — a subprocess that fires every time a developer submits a prompt, before the prompt reaches the LLM. PrePrompt registers itself as this hook, giving it the earliest possible interception point in the prompt lifecycle.

The flow when you have PrePrompt installed in Claude Code:

You type a prompt and press Enter
    ↓
UserPromptSubmit hook fires (PrePrompt subprocess, <1ms)
    ↓
Heuristic classifier scores the prompt (local, no API)
    ↓
score < 38?  →  Pass through unchanged
score ≥ 38?  →  Claude Haiku rewrites it (~1-2 seconds)
    ↓
Claude Code sends the optimized prompt to the LLM
    ↓
Interaction logged to ~/.preprompt/history.db

The hook also writes a JSON sidecar to ~/.preprompt/pending/. When you next invoke an MCP tool (or run preprompt-stats), the sidecar is flushed to the SQLite database and the stack memory is updated.

What the Annotation Looks Like

When PrePrompt intercepts and rewrites a prompt, you see a rich annotation box in your Claude Code terminal output before the LLM response:

╔═══════════════════════════════════════════════════╗
║  PrePrompt — ENRICHED                            ║
║  score: 52  route: enrich                        ║
╠═══════════════════════════════════════════════════╣
║  Original:                                       ║
║  write middleware that validates tokens          ║
║                                                  ║
║  Optimized:                                      ║
║  Write a FastAPI middleware that validates JWT   ║
║  tokens from the Authorization header. If the   ║
║  token is expired, call POST /auth/refresh...    ║
╚═══════════════════════════════════════════════════╝

The annotation appears on stderr — it is visible in your terminal but does not affect the prompt Claude Code receives. Simple prompts produce no annotation at all.

Installation

1. Prerequisites

   Python 3.11+, an Anthropic API key from console.anthropic.com, and Claude Code installed.

2. Install PrePrompt

   pip install preprompt

3. Run the one-command setup

   preprompt-install

   This wizard prompts for your Anthropic API key, saves it to ~/.preprompt/.env, and writes both the MCP server entry and the UserPromptSubmit hook to ~/.claude/settings.json.

4. Verify the installation

   preprompt-stats

   This should show your session stats and confirm the API key is configured.

The Settings File Entries

preprompt-install writes two entries to ~/.claude/settings.json:

{
  "mcpServers": {
    "preprompt": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": { "ANTHROPIC_API_KEY": "your-key-here" }
    }
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "python -m cli.hook"
        }]
      }
    ]
  }
}

The MCP server entry enables the optimize_prompt and get_prompt_history tools that Claude Code can call directly. The UserPromptSubmit hook is what provides the automatic, transparent interception on every prompt.

Frequently Asked Questions