{"id":50126180,"url":"https://github.com/maximizegpt/prompt-guard","last_synced_at":"2026-05-23T20:03:24.663Z","repository":{"id":346691273,"uuid":"1191161556","full_name":"maximizeGPT/prompt-guard","owner":"maximizeGPT","description":"Context-aware prompt enhancement for AI coding agents","archived":false,"fork":false,"pushed_at":"2026-05-17T03:04:52.000Z","size":246,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T03:28:02.031Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximizeGPT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T01:19:21.000Z","updated_at":"2026-05-17T03:04:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximizeGPT/prompt-guard","commit_stats":null,"previous_names":["mohltbot/prompt-guard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maximizeGPT/prompt-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fprompt-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fprompt-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fprompt-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fprompt-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximizeGPT","download_url":"https://codeload.github.com/maximizeGPT/prompt-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fprompt-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33410346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-23T20:03:19.182Z","updated_at":"2026-05-23T20:03:24.657Z","avatar_url":"https://github.com/maximizeGPT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prompt Guard\n\n\u003e Context-aware prompt enhancement and corpus-grounded clarifying questions for AI coding agents.\n\nPrompt Guard helps you write prompts that AI coding agents can act on first-shot — by reading your project context files (`PROJECT.md`, `CONTEXT.md`, etc.) AND by learning from your own past prompts to surface the specific clarifications that previously consumed iteration cycles.\n\n## Two ways to use it\n\n### 1. Static context injection (the original tool)\n\nReads `.md` files in your project and injects them into prompts before they go to the AI.\n\n```bash\nprompt-guard init                                # creates PROJECT.md + CONTEXT.md templates\nprompt-guard check \"refactor the auth system\"    # flags missing files/tests/criteria\nprompt-guard enhance \"refactor the auth system\"  # outputs an enriched prompt\n```\n\n### 2. Corpus-grounded clarification (new in v0.2)\n\nIngests your past conversations from Claude Code and Cowork, builds a local SQLite corpus, and uses Claude Sonnet 4.6 to propose clarifying questions grounded in *your* past prompts when you're about to send a new vague one.\n\n```bash\nprompt-guard ingest --source all                 # parses ~/.claude/projects + ~/Library/.../local-agent-mode-sessions\nprompt-guard corpus stats                        # sanity-check the ingested data\nprompt-guard learn \"refactor the auth handler\"\n```\n\nExample output (synthetic — illustrative of the format):\n\n```\nPROMPT: \"refactor the auth handler\"\n\n2 clarifying questions grounded in your corpus\n\nQ1 [file-scope, conf=0.91]\n  Which auth handler — `src/auth/login.ts` (the JWT flow from the OAuth migration),\n  `src/middleware/auth-check.ts` (the bearer-token verifier), or somewhere else?\n  Grounded in:\n    • past prompt id=4231: \"migrate src/auth/login.ts from session cookies to JWT\n      with 24h expiry. Don't break the /api/v1/auth response shape...\"\n    • past prompt id=4502: \"add bearer-token check to src/middleware/auth-check.ts\n      for the new /api/v2 routes\"\n\nQ2 [success-criteria, conf=0.84]\n  Goal: extract shared logic into a helper, swap to a new library\n  (like the move from `jsonwebtoken` to `jose` you started in turn 891), or fix a\n  specific bug?\n  Grounded in:\n    • past prompt id=5187: \"swap our auth from jsonwebtoken to jose — the old lib\n      has CVE-2024-... and isn't getting patched\"\n```\n\n## How it works\n\nThe corpus-grounded path is a six-stage pipeline:\n\n1. **Ingest** — parses Claude Code JSONL and Cowork audit logs into `~/.prompt-guard/corpus.db`, applies hygiene filters (scheduled-task auto-runs excluded, tool-result envelopes filtered out, replay duplicates consolidated).\n2. **Tag** — heuristic regex tags (files, tests, criteria, constraints, local-env, shape, ui) on every user prompt for retrieval and labeling.\n3. **Extract** — rule-based extractor finds prompt pairs where the second user message clarified the first; LLM extractor (Sonnet 4.6) reviews and refines.\n4. **Hand-label** — interactive TUI for marking a gold subset. The hand-labeled set is the eval-harness ground truth.\n5. **Retrieve** — BM25 over SQLite FTS5, project-scoped with global fallback, synthetic-prompt filter at retrieval time.\n6. **Generate** — Sonnet 4.6 with a tuned system prompt (v4: verb-disambiguation, anticipated-content, concrete-options-beat-abstract-categories, tightened skip rule) proposes up to 3 specific clarifying questions per prompt.\n\nThe eval harness scores generated questions against hand-labeled gold using jaccard-over-tokens + a kind-match floor.\n\n## Baseline (v0.2, May 2026)\n\nOn a 38-case hand-labeled gold subset: **mean overlap@3 = 0.283**, kind-match (any of top-3) = 50%. Strongest slice: `domain-context` at 0.397.\n\nFull results, methodology, per-kind breakdown, limitations, and reproduction in **[SHIP.md](./SHIP.md)**.\n\n## Architecture\n\n```\nprompt-guard/\n├── src/\n│   ├── index.ts                     # main PromptGuard class (static-context path)\n│   ├── checks/                      # check registry pattern\n│   │   ├── registry.ts\n│   │   ├── types.ts\n│   │   ├── files.ts                 # one file per check\n│   │   ├── tests.ts\n│   │   ├── criteria.ts\n│   │   ├── constraints.ts\n│   │   ├── local-env.ts\n│   │   ├── context-window.ts\n│   │   └── corpus-clarify.ts        # MVP-3 corpus-grounded check\n│   ├── corpus/\n│   │   ├── schema.ts                # SQLite schema + FTS5\n│   │   ├── db.ts                    # opener + migrations\n│   │   ├── reader.ts                # BM25 retrieval (CorpusReader)\n│   │   ├── question-gen.ts          # Sonnet 4.6 adapter (v4 system prompt)\n│   │   ├── llm-extractor.ts         # MVP-1.5 LLM extractor\n│   │   ├── labeler.ts               # rule + outcome labelers\n│   │   ├── snapshots.ts             # content-addressed code snapshot ingestion\n│   │   ├── scoring.ts               # eval scoring (jaccard + kind-match floor)\n│   │   ├── parsers/                 # Claude Code + Cowork JSONL parsers\n│   │   └── heuristics.ts            # shared regex taggers\n│   ├── eval/\n│   │   ├── patterns.json            # vague-verb regex, live-vs-local detectors (config-driven)\n│   │   ├── detect.ts                # instrumentation functions\n│   │   └── shape-coverage-prompts.json\n│   └── commands/                    # CLI commands\n│       ├── ingest.ts\n│       ├── stats.ts\n│       ├── label-llm.ts\n│       ├── label-gold.ts            # hand-label TUI\n│       ├── backfill-reasons.ts\n│       ├── dedupe-prompts.ts\n│       ├── learn.ts\n│       └── eval.ts\n├── tests/                           # 15 jest tests\n├── NOTES.md                         # design decisions + deferred items\n├── CRITICAL_PATH.md                 # MVP roadmap with cost/wall estimates\n├── ANNOTATION_GUIDELINES.md         # hand-labeling decision rules\n└── SHIP.md                          # MVP-4 baseline results writeup\n```\n\n## Commands reference\n\n```\nprompt-guard \u003ccommand\u003e [options]\n\nStatic-context path:\n  init                                          # scaffold PROJECT.md + CONTEXT.md\n  check \u003cprompt\u003e                                # warn about missing context\n  enhance \u003cprompt\u003e                              # output prompt enriched with .md context\n  config                                        # show config\n  stats                                         # show token budget + check status\n\nCorpus path:\n  ingest [--source claude-code|cowork|all]      # parse JSONL → SQLite\n  corpus stats                                  # sanity-check the ingested corpus\n  dedupe-prompts [--dry-run]                    # consolidate replay-duplicate rows\n  label-llm [--retry-missing]                   # run LLM extractor on rule pairs\n  backfill-reasons                              # fill missing reasons on existing LLM rows\n  label-gold [--preview --limit N]              # hand-label TUI for gold subset\n  learn \"\u003cprompt\u003e\"                              # generate clarifying questions\n  eval --mode gold|shape-coverage|wide          # run baseline eval\n\nOptions:\n  --db-path \u003cpath\u003e                              # override ~/.prompt-guard/corpus.db\n  --budget \u003cusd\u003e                                # cap LLM spend per eval run\n  --verbose                                     # per-file progress\n```\n\n## Installation\n\nRequires Node 18+, SQLite (included via `better-sqlite3`), and an Anthropic API key for the corpus-grounded path.\n\n```bash\ngit clone https://github.com/prompt-guard/prompt-guard.git\ncd prompt-guard\nnpm install\nnpm run build\necho \"ANTHROPIC_API_KEY=sk-ant-...\" \u003e\u003e ~/.env\n```\n\n## Privacy\n\n- The corpus stays local in `~/.prompt-guard/corpus.db`. Nothing is uploaded without explicit opt-in.\n- Static-context path is fully offline.\n- Corpus-grounded path makes Anthropic API calls only when you run `learn` or `eval`. Past prompts retrieved by BM25 are sent to the API as context.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximizegpt%2Fprompt-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximizegpt%2Fprompt-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximizegpt%2Fprompt-guard/lists"}