promptlint

Quick Start

Install, point at your prompts, get results.

# Lint a single file
$ promptlint check my-prompt.yaml

# Lint a directory with model-aware thresholds
$ promptlint check prompts/ --model claude-3-sonnet

# Lint a multi-prompt pipeline
$ promptlint check prompts/ --pipeline

# Auto-fix fixable issues
$ promptlint check prompts/ --fix

# List all rules
$ promptlint rules

33 Rules Across 9 Categories

Every rule has an ID, a default severity, and a clear description of what it catches.

Category	IDs	What It Checks
Token Budget	PL001-003	Token count thresholds, filler content density
System Prompt	PL010-014	Missing/misplaced system prompt, injection vectors, conflicting instructions
Formatting	PL020-024	Trailing whitespace, inconsistent delimiters, missing output format, repetition
Variables	PL030-033	Undefined/unused variables, missing defaults, mixed placeholder formats
Pipeline	PL040-043	Handoff gaps, context overflow, orphan references, persona drift
Hallucination	PL050-054	Requests for numbers/URLs/citations without data, no uncertainty instructions
Security	PL060-063	PII in prompts, API keys, no output constraints, unbounded tool use
Smells	PL070-074	Ambiguous quantifiers, buried instructions, no examples, wall of text
Gates	PL080-083	Conditional logic without enforcement, missing fallbacks, no evidence gates
Tokenizer	PL090	Warns when model profile uses an approximate tokenizer (Claude, Gemini)

Features

Not just a linter. A complete prompt quality toolkit.

Pipeline

Pipeline Analysis

Lint multi-prompt systems as a unit. Catches handoff drift, context window overflow, orphan references, and persona inconsistency across stages.

Models

Model Profiles

Set --model claude-3-sonnet to auto-configure context windows and tokenizers. Supports GPT-4, Claude, and Gemini families.

Plugins

Custom Rules

Write rules in Python by extending BaseRule. Drop them in a directory, register in config. Full access to parsed prompt structure.

Fix

Auto-fix

Run with --fix to automatically repair fixable violations: trailing whitespace, inconsistent delimiters, missing defaults.

Watch

Watch Mode

Continuously re-lint on file changes during prompt development. Instant feedback loop while you iterate on prompts.

CI

CI Integration

GitHub Actions annotations with --format github. JSON output for scripting. Baseline mode to only fail on new violations.

Supported Formats

Parses the prompt formats you already use.

.txt

Plain text prompts

.md

Markdown + frontmatter

.yaml

Messages list format

.json

OpenAI chat format

Configuration

Drop a .promptlint.yaml in your project root, or run promptlint init to scaffold one.

.promptlint.yaml

model: "claude-3-sonnet"

token_budget:
  warn_threshold: 2048
  error_threshold: 4096

rules:
  PL003: "error"
  PL022: "ignore"

ignore:
  - PL020
  - PL024

exclude:
  - "tests/**"

CI Integration

# .github/workflows/lint-prompts.yml
- name: Lint prompts
  run: >
    promptlint check prompts/
    --format github
    --min-severity warning

# Baseline mode: only fail on new violations
$ promptlint check prompts/
  --baseline prev.json
  --format json > report.json

Output Formats

Human-readable by default. Machine-readable when you need it.

# Human-readable (default)
$ promptlint check prompts/

# JSON for scripting
$ promptlint check prompts/ --format json

# GitHub Actions annotations
$ promptlint check prompts/ --format github

Exit Codes

No violations (or all below --min-severity)
Violations found
Tool error (bad config, parse failure)