Preflight

✈️ 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:

Before / After

❌  "fix the auth bug"
     → Claude guesses which auth bug, edits wrong file
     → You correct it, 3 more rounds
     → 12,000 tokens burned

✅  preflight intercepts → clarify_intent fires
     → "Which auth bug? I see 3 open issues:
        1. JWT expiry not refreshing (src/auth/jwt.ts)
        2. OAuth callback 404 (src/auth/oauth.ts)
        3. Session cookie SameSite (src/middleware/session.ts)
        Pick one and I'll scope the fix."
     → 4,000 tokens, done right the first time

Quick Start

Option A: npx (fastest — no install)

claude mcp add preflight -- npx -y preflight-dev-serve

With environment variables:

claude mcp add preflight \
  -e CLAUDE_PROJECT_DIR=/path/to/your/project \
  -- npx -y preflight-dev-serve

Option B: Clone & configure manually

git clone https://github.com/TerminalGravity/preflight.git
cd preflight && npm install

Add to your project's .mcp.json:

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["tsx", "/path/to/preflight/src/index.ts"],
      "env": {
        "CLAUDE_PROJECT_DIR": "/path/to/your/project"
      }
    }
  }
}

Restart Claude Code. The tools activate automatically.

Option C: npm (global)

npm install -g preflight-dev
claude mcp add preflight -- preflight-dev-serve

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:

flowchart TD
    A[Prompt Arrives] --> B{Skip keyword?}
    B -->|Yes| T1[✅ TRIVIAL]
    B -->|No| C{Multi-step indicators?}
    C -->|Yes| MS[🔶 MULTI-STEP]
    C -->|No| D{Cross-service keywords?}
    D -->|Yes| CS[🔗 CROSS-SERVICE]
    D -->|No| E{always_check keyword?}
    E -->|Yes| AM1[⚠️ AMBIGUOUS]
    E -->|No| F{"< 20 chars + common cmd?"}
    F -->|Yes| T2[✅ TRIVIAL]
    F -->|No| G{"< 50 chars, no file refs?"}
    G -->|Yes| AM2[⚠️ AMBIGUOUS]
    G -->|No| H{Vague pronouns or verbs?}
    H -->|Yes| AM3[⚠️ AMBIGUOUS]
    H -->|No| CL[✅ CLEAR]

    style T1 fill:#2d6a4f,color:#fff
    style T2 fill:#2d6a4f,color:#fff
    style CL fill:#2d6a4f,color:#fff
    style AM1 fill:#e9c46a,color:#000
    style AM2 fill:#e9c46a,color:#000
    style AM3 fill:#e9c46a,color:#000
    style CS fill:#457b9d,color:#fff
    style MS fill:#e76f51,color:#fff

Each level triggers different tool chains:

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

flowchart LR
    A[User Prompt] --> B[Triage Engine]
    B --> C[Tool Chain]
    C --> D[Response]

    B -.-> E[".preflight/\nconfig.yml\ntriage.yml"]
    B -.-> F["Patterns\nLog"]
    C -.-> G["LanceDB\n(per-project)"]
    C -.-> H["Contracts\n(per-project)"]
    G -.-> I["~/.claude/projects/\n(session JSONL)"]

    style A fill:#264653,color:#fff
    style B fill:#2a9d8f,color:#fff
    style C fill:#e9c46a,color:#000
    style D fill:#e76f51,color:#fff

Session Data Structure

Claude Code stores session data as JSONL files:

~/.claude/projects/<encoded-path>/
├── <session-uuid>.jsonl              # Main session
├── <session-uuid>/
│   └── subagents/
│       └── <sub-uuid>.jsonl          # Sub-agent sessions

Each JSONL line is an event. The session parser extracts 8 event types:

LanceDB Schema

Events are stored in per-project LanceDB databases with vector embeddings for semantic search:

~/.preflight/projects/<sha256-12-char>/
├── timeline.lance/       # LanceDB vector database
├── contracts.json        # Extracted API contracts
└── meta.json             # Project metadata

Table: events
├── id: string            (UUID)
├── content: string       (event text)
├── content_preview: string (first 200 chars)
├── vector: float32[384]  (Xenova/all-MiniLM-L6-v2) or float32[1536] (OpenAI)
├── type: string          (event type from above)
├── timestamp: string     (ISO 8601)
├── session_id: string    (session UUID)
├── project: string       (decoded project path)
├── project_name: string  (short name)
├── branch: string        (git branch at time of event)
├── source_file: string   (path to JSONL file)
├── source_line: number   (line number in JSONL)
└── metadata: string      (JSON — model, tool name, etc.)

The project registry at ~/.preflight/projects/index.json maps absolute paths to their SHA-256 hashes.

Contract Extraction

The contract extractor scans your project for API surfaces:

Contracts are stored per-project and searched across related projects during cross-service triage.

Onboarding a Project

Run onboard_project to index a project's history. Here's what happens:

1. Discovers sessions — finds JSONL files in ~/.claude/projects/<encoded-path>/, including subagent sessions
2. Parses events — extracts the 8 event types from each session file (streams files >10MB)
3. Extracts contracts — scans source for types, interfaces, enums, routes, Prisma models, OpenAPI schemas
4. Loads manual contracts — merges any .preflight/contracts/*.yml definitions (manual wins on name conflicts)
5. Generates embeddings — local Xenova/all-MiniLM-L6-v2 by default (~90MB model download on first run, ~50 events/sec) or OpenAI if OPENAI_API_KEY is set (~200 events/sec)
6. Stores in LanceDB — per-project database at ~/.preflight/projects/<sha256-12>/timeline.lance/
7. Updates registry — records the project in ~/.preflight/projects/index.json

No data leaves your machine unless you opt into OpenAI embeddings.

After onboarding, you get:

• 🔎 Semantic search — "How did I set up auth middleware last month?" actually works
• 📊 Timeline view — see what happened across sessions chronologically
• 🔄 Live scanning — index new sessions as they happen
• 🔗 Cross-service search — query across related projects

Tool Reference

✈️ Preflight Core

🎯 Prompt Discipline

…