preflight-dev/preflight

**Stop burning tokens on vague prompts.**
A 24-tool MCP server for Claude Code that catches ambiguous instructions before they cost you 2-3x in wrong→fix cycles — plus semantic search across your entire session history, cross-service contract awareness, and 12-category scorecards.
Quick Start · How It Works · Tool Reference · Configuration · Scoring
---
What's New in v3.2.0
- **Unified preflight_check entry point** — one tool that triages every prompt and chains the right checks automatically
- **Smart triage classification** — routes prompts through a decision tree (trivial → ambiguous → multi-step → cross-service)
- **Correction pattern learning** — remembers past mistakes and warns you before repeating them
- **Cross-service contracts** — extracts types, interfaces, routes, and schemas across related projects
- **.preflight/ config directory** — team-shareable YAML config for triage rules and thresholds
- **Trend & comparative scorecards** — weekly/monthly trend lines, cross-project comparisons, radar charts, PDF export
- **Cost estimator** — estimates token spend and waste from corrections
---
The Problem
We built this after analyzing **9 months of real Claude Code usage** — 512 sessions, 32,000+ events, 3,200+ prompts, 1,642 commits, and 258 sub-agent spawns across a production Next.js/Prisma/Supabase app. The findings were brutal:
- **41% of prompts were under 50 characters** — things like fix the tests, commit this, remove them
- Each vague prompt triggers a **wrong→fix cycle costing 2-3x tokens**
- **~33K characters/day** duplicated from repeated context pastes
- **124 corrections logged** — places where Claude went the wrong direction and had to be steered back
- **94 context compactions** from unbounded session scope blowing past the context window
- Estimated **30-40% of tokens wasted** on avoidable back-and-forth
The pattern is always the same: vague prompt → Claude guesses → wrong output → you correct → repeat. That's your money evaporating.
The Solution
24 tools in 5 categories that run as an MCP server inside Claude Code:
| Category | Tools | What it does |
|----------|-------|-------------|
| ✈️ **Preflight Core** | 1 | Unified entry point — triages every prompt, chains the right checks automatically |
| 🎯 **Prompt Discipline** | 12 | Catches vague prompts, enforces structure, prevents waste |
| 🔍 **Timeline Intelligence** | 4 | LanceDB vector search across months of session history |
| 📊 **Analysis & Reporting** | 4 | Scorecards, cost estimation, session stats, pattern detection |
| ✅ **Verification & Hygiene** | 3 | Type-check, test, audit, and contract search |
Before / After
---
Quick Start
Option A: npx (fastest — no install)
With environment variables:
Option B: Clone & configure manually
Add to your project's .mcp.json:
Restart Claude Code. The tools activate automatically.
Option C: npm (global)
> **Note:** preflight-dev runs the interactive setup wizard. preflight-dev-serve starts the MCP server — that's what you want in your Claude Code config.
---
How It Works
The Triage Decision Tree
Every prompt flows through a classification engine before any work begins. This is the actual decision tree from src/lib/triage.ts:
Each level triggers different tool chains:
| Level | What fires | Example prompt |
|-------|-----------|----------------|
| **Trivial** | Nothing — pass through | commit |
| **Clear** | File verification only | fix null check in src/auth/jwt.ts line 42 |
| **Ambiguous** | Clarify intent + git state + workspace priorities | fix the auth bug |
| **Cross-service** | Clarify + search related projects + contracts | add tiered rewards |
| **Multi-step** | Clarify + scope + sequence + checkpoints | refactor auth to OAuth2 and update all consumers |
Additionally, **correction pattern matching** can boost any triage level. If your prompt matches 2+ keywords from a previously logged correction, it's bumped to at least ambiguous — even if it would otherwise pass through.
Data Flow
Session Data Structure
Claude Code stores session data as JSONL files:
Each JSONL line is an event. The session parser extracts **8 event types**:
| Event Type | Source | What it captures |