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.

[](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](LICENSE) [](https://www.npmjs.com/package/preflight-dev) [](https://nodejs.org/)

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)

---

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

❌  "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](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{"|Yes| T2[✅ TRIVIAL]
    F -->|No| 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:

| 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

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//
├── .jsonl              # Main session
├── /
│   └── subagents/
│       └── .jsonl          # Sub-agent sessions

Each JSONL line is an event. The [session parser](src/lib/session-parser.ts) extracts 8 event types:

| Event Type | Source | What it captures | |-----------|--------|-----------------| | prompt | user messages | What the dev typed | | assistant | assistant messages | Claude's text response | | tool_call | assistant tooluse blocks | Tool invocations (Read, Write, Bash, etc.) | | sub_agent_spawn | Task/dispatchagent tooluse | When Claude delegates to a sub-agent | | correction | user messages after assistant | Detected via negation patterns (no, wrong, actually, undo…) | | compaction | system messages | Context was compressed (session hit token limit) | | error | tool_result with iserror | Failed operations | | commit | git log integration | Commits made during session |

LanceDB Schema

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

~/.preflight/projects//
├── 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](src/lib/contracts.ts) scans your project for API surfaces:

| Pattern | What it finds | |---------|--------------| | export interface/type/enum | TypeScript type definitions | | export function GET/POST/… | Next.js API routes | | router.get/post/… | Express route handlers | | model Foo { … } | Prisma models and enums | | OpenAPI/Swagger specs | Routes and schema components | | .preflight/contracts/*.yml | Manual contract definitions |

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//, 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//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

| Tool | What it does | |------|-------------| | preflight_check | The main entry point. Triages your prompt (trivial → multi-step), chains the right checks automatically, matches against known correction patterns. Accepts force_level override: skip, light, full. |

🎯 Prompt Discipline

| Tool | What it does | |------|-------------| | scope_work | Creates structured execution plans before coding starts | | clarify_intent | Gathers project context (git state, workspace docs, ambiguity signals) to disambiguate vague prompts | | enrich_agent_task | Enriches sub-agent tasks with file paths, patterns, and cross-service context | | sharpen_followup | Resolves "fix it" / "do the others" to actual file targets | | token_audit | Detects waste patterns, grades your session A–F | | sequence_tasks | Orders tasks by dependency, locality, and risk | | checkpoint | Save game before compaction — commits + resumption notes | | check_session_health | Monitors uncommitted files, time since commit, turn count | | log_correction | Tracks corrections and identifies recurring error patterns | | check_patterns | Checks prompts against learned correction patterns — warns about known pitfalls | | session_handoff | Generates handoff briefs for new sessions | | what_changed | Summarizes diffs since last checkpoint |

🔍 Timeline Intelligence

| Tool | What it does | |------|-------------| | onboard_project | Indexes a project's session history + contracts into per-project LanceDB | | search_history | Semantic search with scope: current project, related, or all indexed projects | | timeline | Chronological view of events across sessions | | scan_sessions | Live scanning of active session data |

📊 Analysis & Reporting

| Tool | What it does | |------|-------------| | generate_scorecard | 12-category report card — session, trend (week/month), or cross-project comparative. Radar chart SVG, PDF or markdown. | | estimate_cost | Token usage, dollar cost, waste from corrections, preflight savings | | session_stats | Lightweight session analysis — no embeddings needed | | prompt_score | Gamified A–F grading on specificity, scope, actionability, done-condition |

✅ Verification & Hygiene

| Tool | What it does | |------|-------------| | verify_completion | Runs type check + tests + build before declaring done | | audit_workspace | Finds stale/missing workspace docs vs git activity | | search_contracts | Search API contracts, types, and schemas across current and related projects |

---

Usage Examples

Real prompts you'd type in Claude Code once preflight is installed. The tools fire automatically via preflight_check, or you can call them directly.

Catch a vague prompt before it wastes tokens

> fix the auth bug

preflight_check intercepts → clarify_intent fires:
  "I found 3 auth-related recent changes:
   1. JWT refresh logic in src/auth/jwt.ts (modified 2h ago)
   2. OAuth callback route in src/routes/oauth.ts (3 open TODOs)
   3. Session middleware in src/middleware/auth.ts (failing test)
   Which one? Or describe the symptoms."

Scope a multi-step task before starting

> refactor the database layer to use Drizzle instead of Prisma

preflight_check triages as MULTI-STEP → scope_work + sequence_tasks fire:
  Phase 1: Install drizzle-orm, create schema (src/db/schema.ts)
  Phase 2: Migrate queries in src/services/ (12 files)
  Phase 3: Update tests (8 files reference prisma mocks)
  Phase 4: Remove prisma dependencies, delete prisma/ dir
  Estimated: 4 checkpoints, ~45 min

Search your session history

> use search_history to find how I set up the rate limiter

Searches LanceDB across your indexed sessions:
  Found 3 relevant events (similarity > 0.82):
  - Session abc123 (Jan 15): Added express-rate-limit to src/middleware/
  - Session def456 (Jan 16): Configured per-route limits in src/routes/api.ts
  - Session ghi789 (Feb 2): Fixed rate limit bypass via X-Forwarded-For

Grade your prompting habits

> use prompt_score on "update the thing"

  Grade: D
  - Specificity: 1/5 — no file paths, no identifiers
  - Scope: 1/5 — "the thing" is completely ambiguous
  - Actionability: 2/5 — "update" is vague (refactor? fix? add feature?)
  - Done-condition: 0/5 — no way to know when it's done
  Suggestion: "Update the price formatter in src/utils/currency.ts
  to handle JPY (zero-decimal currency)"

Check session health mid-work

> use check_session_health

  ⚠️ 47 uncommitted files (last commit: 38 min ago)
  ⚠️ 23 turns since last checkpoint
  💡 Consider running `checkpoint` before context compaction hits

Get a cost estimate

> use estimate_cost

  This session: ~$2.40 (148K tokens)
  Waste from corrections: ~$0.85 (3 wrong→fix cycles)
  Preflight savings: ~$1.20 (4 vague prompts caught early)
  Net: saving roughly 35% vs unchecked prompting

---

The 12-Category Scorecard

generate_scorecard evaluates your prompt discipline across 12 categories. Each one measures something specific about how you interact with Claude Code:

| # | Category | What it mea

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: preflight-dev
• Source: preflight-dev/preflight
• License: MIT
• Homepage: https://www.npmjs.com/package/preflight-dev

Install and usage instructions live in the source repository linked above.