preprompt 0.1.0__tar.gz

preprompt-0.1.0/.claude/hooks/pre_prompt.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+Claude Code UserPromptSubmit hook for PrePrompt.
+
+Receives JSON on stdin, writes JSON to stdout.
+  stdin:  {"prompt": "...", "conversation_history": [...], "turn_number": N}
+  stdout: {"prompt": "..."}   ← optimized or original, never blocked
+
+DB writes are done via JSON sidecar files in ~/.preprompt/pending/
+so the hook never touches the SQLite file directly (avoids lock conflict
+with the running MCP server). The MCP server flushes sidecars on the
+next optimize_prompt call.
+"""
+
+import sys
+import os
+import json
+import uuid
+import time
+from pathlib import Path
+
+
+# ── Box annotation constants ──────────────────────────────────────────────────
+_WIDTH  = 62          # total box width
+_INNER  = _WIDTH - 4  # content between "║ " and " ║"  (58 chars)
+_TEXT_W = 48          # prompt text width after label   (58 - 10)
+
+
+def _box_line(content: str) -> str:
+    return f"║ {content:<{_INNER}} ║"
+
+
+def _render_annotation(score: int, reason: str, original: str, optimized: str) -> str:
+    import textwrap
+
+    # Header: ╔═ PrePrompt +{score} ══...══╗
+    prefix = f"╔═ PrePrompt +{score} "
+    header = prefix + "═" * (_WIDTH - len(prefix) - 1) + "╗"
+
+    # Reason (wrapped to inner width)
+    reason_lines = [_box_line(l) for l in (textwrap.wrap(reason, _INNER) or [""])]
+
+    # Separator
+    sep = "╠" + "═" * (_WIDTH - 2) + "╣"
+
+    # ORIGINAL (truncated to TEXT_W)
+    orig_text = original if len(original) <= _TEXT_W else original[:_TEXT_W - 3] + "..."
+    orig_line = _box_line(f"ORIGINAL  {orig_text}")
+
+    # OPTIMIZED (wrapped, continuation indented 10 spaces to align with text)
+    opt_wrapped = textwrap.wrap(optimized, _TEXT_W) or [optimized[:_TEXT_W]]
+    opt_lines = [_box_line(f"OPTIMIZED {opt_wrapped[0]}")] + [
+        _box_line(f"          {line}") for line in opt_wrapped[1:]
+    ]
+
+    # Footer
+    footer = "╚" + "═" * (_WIDTH - 2) + "╝"
+
+    return "\n".join([header] + reason_lines + [sep, orig_line] + opt_lines + [footer])
+
+
+def _write_sidecar(
+    prompt: str,
+    optimized: str,
+    score: int,
+    was_intercepted: bool,
+    turn_number: int,
+) -> None:
+    """Write event to ~/.preprompt/pending/<uuid>.json for async DB flush."""
+    sidecar = {
+        "original_prompt": prompt,
+        "optimized_prompt": optimized,
+        "classifier_score": score,
+        "was_intercepted": was_intercepted,
+        "turn_number": turn_number,
+        "timestamp": time.time(),
+    }
+    sidecar_dir = Path.home() / ".preprompt" / "pending"
+    sidecar_dir.mkdir(parents=True, exist_ok=True)
+    sidecar_path = sidecar_dir / f"{uuid.uuid4()}.json"
+    sidecar_path.write_text(json.dumps(sidecar))
+
+
+def main() -> None:
+    raw = sys.stdin.read()
+
+    # Parse stdin — on failure, echo back whatever we got and exit cleanly
+    try:
+        data = json.loads(raw)
+    except Exception:
+        print(raw, end="")
+        sys.exit(0)
+
+    prompt: str = data.get("prompt", "")
+    history: list = data.get("conversation_history", [])
+    turn: int = data.get("turn_number", 1)
+
+    def passthrough() -> None:
+        print(json.dumps({"prompt": prompt}))
+
+    try:
+        # Always resolve paths relative to this file's location,
+        # not the caller's working directory
+        _HOOK_FILE = os.path.abspath(__file__)
+        _HOOK_DIR = os.path.dirname(_HOOK_FILE)          # .claude/hooks/
+        _CLAUDE_DIR = os.path.dirname(_HOOK_DIR)          # .claude/
+        _PROJECT_ROOT = os.path.dirname(_CLAUDE_DIR)      # project root
+
+        # Add project root to path so mcp_server imports work
+        if _PROJECT_ROOT not in sys.path:
+            sys.path.insert(0, _PROJECT_ROOT)
+
+        # Load .env from project root
+        from dotenv import load_dotenv
+        load_dotenv(os.path.join(_PROJECT_ROOT, ".env"))
+
+        # ── Classify (no API call — always fast) ──────────────────────────────
+        from mcp_server.classifier import classify_prompt, OPTIMIZATION_THRESHOLD
+
+        score = classify_prompt(prompt, history, turn)
+
+        if score < OPTIMIZATION_THRESHOLD:
+            passthrough()
+            sys.exit(0)
+
+        # ── Check API key before importing optimizer (which triggers config) ──
+        api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+        if not api_key:
+            print(
+                "[PrePrompt WARNING] ANTHROPIC_API_KEY not set — skipping optimization",
+                file=sys.stderr,
+            )
+            passthrough()
+            sys.exit(0)
+
+        # ── Optimize via Haiku API ────────────────────────────────────────────
+        from mcp_server.optimizer import optimize
+
+        result = optimize(prompt, history)
+        optimized: str = result["optimized_prompt"]
+        reason: str = result["reason"]
+        was_intercepted: bool = optimized != prompt
+
+        # ── Write sidecar (no DB lock needed) ────────────────────────────────
+        try:
+            _write_sidecar(prompt, optimized, score, was_intercepted, turn)
+        except Exception as sidecar_err:
+            print(f"[PrePrompt] Sidecar write failed: {sidecar_err}", file=sys.stderr)
+
+        # ── Rich annotation to stderr ─────────────────────────────────────────
+        if was_intercepted:
+            print(_render_annotation(score, reason, prompt, optimized), file=sys.stderr)
+        else:
+            print(f"[PrePrompt +{score}] {reason}", file=sys.stderr)
+
+        print(json.dumps({"prompt": optimized}))
+
+    except Exception as e:
+        print(f"[PrePrompt ERROR] {e}", file=sys.stderr)
+        passthrough()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

preprompt-0.1.0/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "preprompt": {
+      "command": "python",
+      "args": ["-m", "mcp_server.server"],
+      "cwd": "${workspaceFolder}/promptforge",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/promptforge"
+      }
+    }
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python ${workspaceFolder}/promptforge/.claude/hooks/pre_prompt.py"
+          }
+        ]
+      }
+    ]
+  }
+}

preprompt-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# Anthropic API key — required for classifier and optimizer agents
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Model used for classification (cheap + fast)
+CLASSIFIER_MODEL=claude-haiku-4-5-20251001
+
+# Model used for prompt optimization (more capable)
+OPTIMIZER_MODEL=claude-sonnet-4-6
+
+# DuckDB database file path (use :memory: for in-memory only)
+DB_PATH=./promptforge.duckdb
+
+# Minimum confidence score (0.0–1.0) to trigger optimization
+OPTIMIZATION_THRESHOLD=0.7
+
+# MCP server transport: stdio or sse
+MCP_TRANSPORT=stdio

preprompt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dev deps
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        env:
+          ANTHROPIC_API_KEY: sk-ant-test-dummy-key-for-ci
+        run: python -m pytest -v

preprompt-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

preprompt-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Environment
+.env
+*.env
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# DuckDB (local dev databases)
+*.duckdb
+*.duckdb.wal
+
+# IDE
+.vscode/
+*.swp
+
+# macOS
+.DS_Store
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+
+# PrePrompt runtime DB lives outside the repo:
+# ~/.preprompt/history.db  ← not tracked
+.venv/

preprompt-0.1.0/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Activate venv first
+source .venv/bin/activate
+
+# Run all tests
+python -m pytest
+
+# Run a single test file
+python -m pytest tests/test_classifier.py -v
+
+# Install in editable mode (includes dev deps)
+pip install -e ".[dev]"
+
+# Start the MCP server
+python -m mcp_server.server
+
+# CLI tools (after pip install)
+preprompt-history [--limit N] [--intercepted-only]
+preprompt-stats
+preprompt-test-classifier
+preprompt-memory
+preprompt-optimize "your prompt here"   # or pipe: echo "..." | preprompt-optimize
+preprompt-optimize --raw "prompt"        # prints optimized text only
+preprompt-update-context
+
+# One-command install + global hook registration (auto-detects Claude Code, Cursor, Windsurf, Zed)
+bash scripts/install.sh
+
+# Per-IDE registration
+python scripts/install_cursor.py
+python scripts/install_windsurf.py
+python scripts/install_zed.py
+```
+
+## Architecture
+
+PrePrompt is an MCP server that intercepts prompts before they reach the LLM, scores them with a local heuristic classifier, optionally rewrites vague/complex ones via Claude Haiku, and logs everything to a local SQLite DB.
+
+### Request flow
+
+```
+User types prompt
+    → .claude/hooks/pre_prompt.py  (UserPromptSubmit hook, subprocess)
+        → classify_prompt()        (score 0–100, no API call)
+        → if score < 38: passthrough
+        → else: optimize() via Haiku API
+        → write JSON sidecar → ~/.preprompt/pending/<uuid>.json
+        → print optimized prompt to stdout
+    → Claude Code sends optimized prompt to LLM
+    → (next MCP tool call)
+        → flush_pending_hook_events()  reads sidecars → SQLite
+```
+
+The hook **never touches the DB directly** — this avoids SQLite lock contention with the running MCP server. The sidecar files are the IPC mechanism.
+
+### Key modules
+
+| File | Responsibility |
+|------|---------------|
+| `mcp_server/classifier.py` | Heuristic scorer. `OPTIMIZATION_THRESHOLD = 38`. No API calls. |
+| `mcp_server/optimizer.py` | Calls Claude Haiku to rewrite prompt. |
+| `mcp_server/tools.py` | MCP tool `optimize_prompt()` — entry point from Claude Code. Calls `flush_pending_hook_events()` first. |
+| `mcp_server/extractor.py` | Extracts stack facts (language, framework, etc.) from prompts → `stack_memory`. |
+| `storage/db.py` | SQLite (WAL mode). Tables: `prompt_history`, `stack_memory`, `sessions`. `_get_connection()` is the long-lived write conn; `get_read_connection()` opens fresh read conns for CLI/history. |
+| `cli/commands.py` | CLI entry points. Always calls `flush_pending_hook_events()` before reading history. Includes `optimize_cmd` for standalone CLI optimization. |
+| `.claude/hooks/pre_prompt.py` | Hook subprocess. Resolves project root via `__file__` (not cwd). Writes sidecars, never imports `storage.db`. |
+| `scripts/install_windsurf.py` | Registers MCP in `~/.codeium/windsurf/mcp_config.json`. |
+| `scripts/install_zed.py` | Registers MCP in `~/.config/zed/settings.json`. |
+| `.github/workflows/publish.yml` | Publishes to PyPI on `git tag v*` via OIDC trusted publisher. |
+| `preprompt.skill.md` | Claude Skill file — manual PrePrompt scoring/optimization for tools without MCP. |
+
+### Data directory
+
+All runtime data lives in `~/.preprompt/`:
+- `history.db` — SQLite database
+- `pending/*.json` — sidecar files written by hook, flushed by MCP server
+
+### Classifier scoring
+
+Positive: ambiguity verbs (+25 max), multi-requirement density (12 pts/hit, max 30), turn depth (+5/turn after turn 2, max 15), code task without format hint (+15).  
+Negative: short prompt (−20), "what is/are/does" opener (−15), already structured (−15), conversational opener (−25).
+
+### SQLite type conventions
+
+- Timestamps stored as ISO 8601 TEXT; parsed back to `datetime` via `_coerce_row()` on read.
+- Booleans stored as INTEGER (0/1); coerced back to `bool` on read.
+- All writes followed by `conn.commit()`.
+
+### Session identity
+
+One session per `hostname + calendar day`. Session key format: `{hostname}-{YYYY-MM-DD}`.
+
+### Landing page
+
+`docs/index.html` — GitHub Pages site (Tailwind CDN, Space Grotesk + JetBrains Mono, dark theme). Sections: hero terminal, interactive classifier demo, how it works, stack memory CLI mockup, session replay, stats bar, open source CTA, beta signup, FAQ. All interactivity is vanilla JS — no build step.
+
+## Mandatory after every task
+
+After completing any task in this repository, you MUST always:
+
+1. Run `pytest -v` and confirm all tests still pass
+
+2. Run `preprompt-update-context` to update CONTEXT.md
+
+3. Update CLAUDE.md if any architecture, file map, or interface changed
+
+4. Commit with a clear descriptive message authored by Yashdeep Tehlan:
+
+   ```
+   git -c user.name="yashdeeptehlan" -c user.email="0yashdeeptehlan@gmail.com" commit -m "your message here"
+   ```
+
+5. Push to main
+
+Never skip these steps. Never use co-authored-by or mention AI tools in commit messages.

preprompt-0.1.0/CONTEXT.md

@@ -0,0 +1,117 @@
+<!-- Last updated: 2026-04-27 22:40 -->
+# PrePrompt — CONTEXT.md
+# This file is auto-maintained. Read it fully at the start of every chat.
+
+## Build status
+Phase 7c complete. 28/28 tests passing.
+
+## What PrePrompt does
+MCP server that intercepts prompts in Claude Code and Cursor, scores them
+with a heuristic classifier (no API), optimizes complex ones using Claude
+Haiku, logs everything to SQLite (WAL mode), and learns the user's stack
+over time via a memory layer. Runs entirely locally.
+
+## Tech stack
+- Python 3.11+, FastMCP, Anthropic SDK, SQLite (WAL mode), pydantic-settings
+- Haiku model: claude-haiku-4-5-20251001
+- DB: SQLite WAL at ~/.preprompt/history.db
+
+## File map
+mcp_server/
+  server.py      — entry point, mcp.run(transport=settings.mcp_transport)
+  tools.py       — MCP tools: optimize_prompt, get_prompt_history
+                   uses get_or_create_session() for stable daily session identity
+  classifier.py  — pure heuristic scorer, threshold=38, multi-req weight=12/hit, no API calls
+  optimizer.py   — Haiku API call + memory context injection
+                   strips markdown fences from model JSON response
+  extractor.py   — heuristic stack signal extractor
+  config.py      — pydantic-settings, reads .env
+
+storage/
+  db.py          — SQLite WAL: prompt_history + stack_memory + sessions tables
+                   Sidecar pattern: hook writes JSON to ~/.preprompt/pending/,
+                   flushed by MCP server or CLI commands via flush_pending_hook_events()
+                   get_or_create_session(): stable {hostname}-{date} session key
+                   get_all_history(): cross-session history query
+                   upsert_stack_memory(): compounding confidence (+0.02/hit, reset on value change)
+
+cli/
+  commands.py    — preprompt-history (all sessions), stats, memory,
+                   test-classifier, optimize, update-context
+
+.claude/
+  settings.json           — MCP server + UserPromptSubmit hook config
+  hooks/pre_prompt.py     — interception hook with rich box annotation on stderr
+                            path resolved via __file__ (CWD-independent)
+                            writes JSON sidecar to ~/.preprompt/pending/ — never touches DB directly
+
+scripts/
+  install.sh              — one-command installer (auto-detects Claude Code, Cursor, Windsurf, Zed)
+  setup_global_hook.py    — global Claude Code MCP + UserPromptSubmit registration
+  install_cursor.py       — registers MCP in ~/.cursor/mcp.json
+  install_windsurf.py     — registers MCP in ~/.codeium/windsurf/mcp_config.json
+  install_zed.py          — registers MCP in ~/.config/zed/settings.json
+  init_github.py          — git init + first commit + push instructions
+
+.github/
+  workflows/ci.yml        — runs pytest on every push/PR
+  workflows/publish.yml   — builds + publishes to PyPI on git tag v*
+
+preprompt.skill.md        — Claude Skill file for tools without MCP hook support
+
+LICENSE                   — MIT
+
+tests/
+  test_classifier.py    — 12 tests
+  test_optimizer.py     —  4 tests
+  test_integration.py   — 12 tests
+
+## Key interfaces — never change these signatures
+- classify_prompt(prompt: str, history: list, turn: int) -> int
+- optimize(prompt: str, history: list) -> dict
+- optimize_prompt(user_prompt, conversation_history, turn_number) -> dict
+- save_prompt_event(...) in storage/db.py
+- get_recent_history(session_id, limit) in storage/db.py
+- upsert_stack_memory(key, value, confidence) in storage/db.py
+- get_stack_memory() -> dict[str, str] in storage/db.py
+- extract_stack_signals(prompt, history) -> dict
+- update_memory_from_prompt(prompt, history) -> None
+- flush_pending_hook_events() -> int in storage/db.py
+
+## Completed phases
+- Phase 1: scaffold, classifier, optimizer, SQLite, MCP server
+- Phase 2: hook, Cursor install, CLI commands
+- Phase 3: stack memory, extractor, memory-aware optimizer
+- Phase 4: GitHub, live test, CONTEXT.md
+- Phase 5: session identity, memory consolidation, rich annotations, cross-session history
+- Phase 6: packaging, SQLite WAL migration, sidecar concurrency pattern, classifier tuned (38/12), absolute hook path, one-command install, MIT license, distribution README
+- Phase 6b: global rename PromptForge → PrePrompt
+- Phase 7: GitHub Actions CI + publish workflow, PyPI trusted publisher setup
+- Phase 7b: preprompt-optimize CLI command, Windsurf + Zed MCP installers
+- Phase 7c: preprompt.skill.md — Claude Skill for tools without MCP support
+
+## PyPI publish instructions
+1. Create account at https://pypi.org
+2. Go to https://pypi.org/manage/account/publishing/
+3. Add trusted publisher: owner=yashdeeptehlan, repo=preprompt, workflow=publish.yml, env=release
+4. Create GitHub environment "release" at https://github.com/yashdeeptehlan/preprompt/settings/environments
+5. Tag a release: git tag v0.1.0 && git push origin v0.1.0
+
+## Next phases
+- Phase 8: web dashboard (local FastAPI + HTMX) to browse history and replay sessions
+- Phase 8b: prompt diff view (original vs optimized, side by side)
+
+## GitHub Pages
+Landing page: https://yashdeeptehlan.github.io/preprompt/
+Source: docs/index.html (Tailwind CDN, JetBrains Mono, interactive demo, session replay, FAQ)
+
+## How new chats should start
+User will say "continuing from last chat" or paste this file.
+Ask for: cat preprompt/CONTEXT.md
+Confirm phase + what comes next, then proceed.
+
+## Environment
+- Dev machine: macOS
+- API key: in .env as ANTHROPIC_API_KEY
+- Claude Code workspace: /Users/user/Documents/Promptforge/promptforge
+- GitHub: https://github.com/yashdeeptehlan/preprompt

preprompt-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+Copyright (c) 2026 Yashdeep Tehlan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.